Jak zarządzać eksportem danych za pomocą interfejsu API REST usługi IoT Central

Artykuł
07/25/2023

Interfejs API REST usługi IoT Central umożliwia tworzenie aplikacji klienckich zintegrowanych z aplikacjami usługi IoT Central. Za pomocą interfejsu API REST można tworzyć eksporty danych i zarządzać nimi w aplikacji usługi IoT Central.

Każde wywołanie interfejsu API REST usługi IoT Central wymaga nagłówka autoryzacji. Aby dowiedzieć się więcej, zobacz Jak uwierzytelniać i autoryzować wywołania interfejsu API REST usługi IoT Central.

Aby uzyskać dokumentację referencyjną interfejsu API REST usługi IoT Central, zobacz Dokumentacja interfejsu API REST usługi Azure IoT Central.

Porada

Możesz użyć narzędzia Postman , aby wypróbować wywołania interfejsu API REST opisane w tym artykule. Pobierz kolekcję IoT Central Postman i zaimportuj ją do narzędzia Postman. W kolekcji należy ustawić zmienne, takie jak poddomena aplikacji i token administratora.

Aby dowiedzieć się, jak zarządzać eksportem danych przy użyciu interfejsu użytkownika usługi IoT Central, zobacz Eksportowanie danych IoT do usługi Blob Storage.

Eksport danych

Za pomocą funkcji eksportowania danych usługi IoT Central można przesyłać strumieniowo dane telemetryczne, zmiany właściwości, zdarzenia łączności urządzeń, zdarzenia cyklu życia urządzenia i zdarzenia cyklu życia szablonu urządzenia do miejsc docelowych, takich jak Azure Event Hubs, Azure Service Bus, Azure Blob Storage i punkty końcowe elementów webhook.

Każda definicja eksportu danych może wysyłać dane do co najmniej jednego miejsca docelowego. Przed utworzeniem definicji eksportu utwórz definicje docelowe.

Tworzenie lub aktualizowanie miejsca docelowego

Użyj następującego żądania, aby utworzyć lub zaktualizować definicję docelową:

PUT https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

destinationId jest unikatowym identyfikatorem miejsca docelowego.

Poniższy przykład przedstawia treść żądania, która tworzy miejsce docelowe magazynu obiektów blob:

{
  "displayName": "Blob Storage Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
  "containerName": "central-data"
}

Treść żądania zawiera kilka wymaganych pól:

displayName: nazwa wyświetlana miejsca docelowego.
type: typ obiektu docelowego. Jeden z: blobstorage@v1, , eventhubs@v1dataexplorer@v1, servicebusqueue@v1, , servicebustopic@v1. webhook@v1
connectionString: parametry połączenia służące do uzyskiwania dostępu do zasobu docelowego.
containerName: w przypadku miejsca docelowego magazynu obiektów blob nazwa kontenera, w którym powinny być zapisywane dane.

Odpowiedź na to żądanie wygląda podobnie do następującego przykładu:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Pobieranie miejsca docelowego według identyfikatora

Użyj następującego żądania, aby pobrać szczegóły miejsca docelowego z aplikacji:

GET https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Odpowiedź na to żądanie wygląda podobnie do następującego przykładu:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Wyświetlanie listy miejsc docelowych

Użyj następującego żądania, aby pobrać listę miejsc docelowych z aplikacji:

GET https://{your app subdomain}/api/dataExport/destinations?api-version=2022-10-31-preview

Odpowiedź na to żądanie wygląda podobnie do następującego przykładu:

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
                "type": "connectionString",
                "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
                "containerName": "central-data"
            },
            "status": "waiting"
        },
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9",
            "displayName": "Webhook destination",
            "type": "webhook@v1",
            "url": "https://eofnjsh68jdytan.m.pipedream.net",
            "headerCustomizations": {},
            "status": "error"
        }
    ]
}

Stosowanie poprawek do miejsca docelowego

PATCH https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

To wywołanie służy do przeprowadzania przyrostowej aktualizacji eksportu. Przykładowa treść żądania wygląda podobnie do poniższego przykładu, który aktualizuje connectionString obiekt docelowy:

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net"
}

Odpowiedź na to żądanie wygląda podobnie do następującego przykładu:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Usuwanie miejsca docelowego

Użyj następującego żądania, aby usunąć miejsce docelowe:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Tworzenie lub aktualizowanie definicji eksportu

Użyj następującego żądania, aby utworzyć lub zaktualizować definicję eksportu danych:

PUT https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

Poniższy przykład przedstawia treść żądania, która tworzy definicję eksportu dla telemetrii urządzenia:

{
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
        }
    ]
}

Treść żądania zawiera kilka wymaganych pól:

displayName: nazwa wyświetlana eksportu.
enabled: Przełącz, aby uruchomić/zatrzymać eksportowanie z wysyłania danych.
source: typ danych do wyeksportowania.
destinations: lista miejsc docelowych, do których eksport powinien wysyłać dane. Identyfikatory docelowe muszą już istnieć w aplikacji.

Istnieje kilka opcjonalnych pól, których można użyć, aby dodać więcej szczegółów do eksportu.

enrichments: Dodatkowe informacje do uwzględnienia w każdej wysłanej wiadomości. Dane są reprezentowane jako zestaw par klucz/wartość, gdzie klucz jest nazwą wzbogacania, która będzie wyświetlana w komunikacie wyjściowym, a wartość identyfikuje dane do wysłania.
filter: Kwerenda definiująca, które zdarzenia ze źródła powinny być eksportowane.

Odpowiedź na to żądanie wygląda podobnie do następującego przykładu:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "starting"
}

Wzbogacanie

Istnieją trzy typy wzbogacania, które można dodać do eksportu: niestandardowe ciągi, właściwości systemu i właściwości niestandardowe:

W poniższym przykładzie pokazano, jak za pomocą węzła enrichments dodać ciąg niestandardowy do komunikatu wychodzącego:

"enrichments": {
  "My custom string": {
    "value": "My value"
  },
  //...
}

W poniższym przykładzie pokazano, jak za pomocą węzła enrichments dodać właściwość systemową do komunikatu wychodzącego:

"enrichments": {
  "Device template": {
    "path": "$templateDisplayName"
  },
  //...
}

Możesz dodać następujące właściwości systemowe:

Właściwość	Opis
`$enabled`	Czy urządzenie jest włączone?
`$displayName`	Nazwa urządzenia.
`$templateDisplayName`	Nazwa szablonu urządzenia.
`$organizations`	Organizacje, do których należy urządzenie.
`$provisioned`	Czy urządzenie jest aprowidowane?
`$simulated`	Czy urządzenie jest symulowane?

W poniższym przykładzie pokazano, jak za pomocą węzła enrichments dodać właściwość niestandardową do komunikatu wychodzącego. Właściwości niestandardowe to właściwości zdefiniowane w szablonie urządzenia, z które urządzenie jest skojarzone:

"enrichments": {
  "Device model": {
    "target": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "path": "model"
  },
  //...
}

Filtry

Wyeksportowane komunikaty można filtrować na podstawie danych telemetrycznych lub wartości właściwości.

W poniższym przykładzie pokazano, jak używać filter pola do eksportowania tylko komunikatów, w których wartość telemetrii accelerometer-X jest większa niż 0:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 WHERE accelerometerX > 0",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

W poniższym przykładzie pokazano, jak używać filter pola do eksportowania tylko komunikatów, w których temperature wartość telemetrii jest większa niż targetTemperature właściwość:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 AS A, dtmi:contoso:Thermostat;1 WHERE A.temperature > targetTemperature",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

Pobieranie eksportu według identyfikatora

Użyj następującego żądania, aby pobrać szczegóły definicji eksportu z aplikacji:

GET https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

Odpowiedź na to żądanie wygląda podobnie do następującego przykładu:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage Destination",
    "type": "blobstorage@v1",
    "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
    "containerName": "central-data",
    "status": "waiting"
}

Wyświetlanie listy definicji eksportu

Użyj następującego żądania, aby pobrać listę definicji eksportu z aplikacji:

GET https://{your app subdomain}/api/dataExport/exports?api-version=2022-10-31-preview

Odpowiedź na to żądanie wygląda podobnie do następującego przykładu:

{
  "value": [
    {
      "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "starting"
    },
    {
      "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "healthy"
    }
  ]
}

Stosowanie poprawek definicji eksportu

PATCH https://{your app subdomain}/dataExport/exports/{exportId}?api-version=2022-10-31-preview

To wywołanie służy do przeprowadzania przyrostowej aktualizacji eksportu. Przykładowa treść żądania wygląda podobnie do następującego przykładu enrichments , który aktualizuje element do eksportu:

{
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    }
}

Odpowiedź na to żądanie wygląda podobnie do następującego przykładu:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "healthy"
}

Usuwanie definicji eksportu

Użyj następującego żądania, aby usunąć definicję eksportu:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Następne kroki

Teraz, gdy wiesz już, jak zarządzać eksportem danych za pomocą interfejsu API REST, sugerowanym następnym krokiem jest użycie interfejsu API REST usługi IoT Central do zarządzania szablonami urządzeń.

Share via

Jak zarządzać eksportem danych za pomocą interfejsu API REST usługi IoT Central

Eksport danych

Tworzenie lub aktualizowanie miejsca docelowego

Pobieranie miejsca docelowego według identyfikatora

Wyświetlanie listy miejsc docelowych

Stosowanie poprawek do miejsca docelowego

Usuwanie miejsca docelowego

Tworzenie lub aktualizowanie definicji eksportu

Wzbogacanie

Filtry

Pobieranie eksportu według identyfikatora

Wyświetlanie listy definicji eksportu

Stosowanie poprawek definicji eksportu

Usuwanie definicji eksportu

Następne kroki

Dodatkowe zasoby