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

Artykuł
10/22/2024

Interfejs API REST usługi IoT Central umożliwia tworzenie aplikacji klienckich, które integrują się z aplikacjami usługi IoT Central. Interfejs API REST umożliwia tworzenie eksportów danych i zarządzanie 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.

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 eksportu 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 elementu 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.

W poniższym przykładzie przedstawiono treść żądania, która tworzy miejsce docelowe magazynu obiektów blob:

{
  "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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
authorization: szczegóły autoryzacji dla miejsca docelowego. Obsługiwane typy autoryzacji to systemAssignedManagedIdentity i connectionString.

Odpowiedź na to żądanie wygląda następująco:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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 następująco:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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 następująco:

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
              "type": "systemAssignedManagedIdentity",
              "endpointUri": "https://yourapplication.blob.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 następującego przykładu, który aktualizuje containerName lokalizację docelową:

{
  "containerName": "central-data-analysis"
}

Odpowiedź na to żądanie wygląda następująco:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data-analysis"
    },
    "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

W poniższym przykładzie przedstawiono 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, które mają zostać dołączone do każdej wysłanej wiadomości. Dane są reprezentowane jako zestaw par klucz/wartość, gdzie klucz jest nazwą wzbogacania wyświetlaną 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 następująco:

{
    "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"
}

Wzbogacenia

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ści	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 są właściwościami zdefiniowanymi w szablonie urządzenia skojarzonym z:

"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 następująco:

{
  "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"
}

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 następująco:

{
  "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 następująco:

{
    "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ń.

Udostępnij za pośrednictwem

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

Wzbogacenia

Filtry

Pobieranie eksportu według identyfikatora

Wyświetlanie listy definicji eksportu

Stosowanie poprawek definicji eksportu

Usuwanie definicji eksportu

Następne kroki

Opinia

Dodatkowe zasoby