Správa exportu dat s využitím rozhraní IoT Central REST API

Rozhraní IoT Central REST API umožňuje vyvíjet klientské aplikace, které se integrují s aplikacemi IoT Central. K vytváření a správě exportů dat můžete použít rozhraní REST API. v aplikaci IoT Central.

Každé volání rozhraní IOT Central REST API vyžaduje autorizační hlavičku. Další informace najdete v tématu Ověřování a autorizace volání rozhraní IoT Central REST API.

Referenční dokumentaci k rozhraní IOT Central REST API najdete v referenčních informacích k rozhraní AZURE IoT Central REST API.

Tip

Pomocí nástroje Postman můžete vyzkoušet volání rozhraní REST API popsaná v tomto článku. Stáhněte si kolekci IoT Central Postman a naimportujte ji do nástroje Postman. V kolekci budete muset nastavit proměnné, jako je subdoména aplikace a token správce.

Informace o správě exportu dat pomocí uživatelského rozhraní IoT Central najdete v tématu Export dat IoT do služby Blob Storage.

Export dat

Funkci exportu dat IoT Central můžete použít ke streamování telemetrie, změn vlastností, událostí připojení zařízení, událostí životního cyklu zařízení a událostí životního cyklu zařízení do cílů, jako jsou Azure Event Hubs, Azure Service Bus, Azure Blob Storage a koncové body webhooku.

Každá definice exportu dat může odesílat data do jednoho nebo více cílů. Před vytvořením definice exportu vytvořte cílové definice.

Vytvoření nebo aktualizace cíle

Pomocí následujícího požadavku vytvořte nebo aktualizujte definici cíle:

PUT https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview
  • destinationId – jedinečné ID cíle.

Následující příklad ukazuje text požadavku, který vytvoří cíl úložiště objektů blob:

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

Text požadavku obsahuje některá povinná pole:

  • displayName: Zobrazovaný název cíle.
  • type: Typ cílového objektu. Jedna z: blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, servicebustopic@v1, . webhook@v1
  • connectionString: Připojovací řetězec pro přístup k cílovému prostředku.
  • containerName: Pro cíl úložiště objektů blob název kontejneru, do kterého se mají zapisovat data.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Získání cíle podle ID

Pomocí následujícího požadavku načtěte podrobnosti o cíli z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Vypsat cíle

Pomocí následujícího požadavku načtěte seznam cílů z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Oprava cíle

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

Toto volání můžete použít k provedení přírůstkové aktualizace exportu. Text ukázkového požadavku vypadá jako v následujícím příkladu displayName , který aktualizuje objekt na cíl:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Odstranění cíle

K odstranění cíle použijte následující požadavek:

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

Vytvoření nebo aktualizace definice exportu

Pomocí následujícího požadavku vytvořte nebo aktualizujte definici exportu dat:

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

Následující příklad ukazuje text požadavku, který vytvoří definici exportu pro telemetrii zařízení:

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

Text požadavku obsahuje některá povinná pole:

  • displayName: Zobrazovaný název exportu.
  • enabled: Přepněte na spuštění nebo zastavení exportu z odesílání dat.
  • source: Typ dat, která se mají exportovat.
  • destinations: Seznam cílů, do kterých má export odesílat data. Cílová ID již musí v aplikaci existovat.

Existují některá volitelná pole, která můžete použít k přidání dalších podrobností k exportu.

  • enrichments: Další informace, které se mají zahrnout do každé odeslané zprávy. Data jsou reprezentována jako sada párů klíč-hodnota, kde klíč je název rozšíření, který se zobrazí ve výstupní zprávě, a hodnota identifikuje data, která se mají odeslat.
  • filter: Dotaz definující, které události ze zdroje se mají exportovat.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Získání exportu podle ID

Pomocí následujícího požadavku načtěte podrobnosti o definici exportu z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Definice exportu seznamu

Pomocí následujícího požadavku načtěte seznam definic exportu z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Oprava definice exportu

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

Toto volání můžete použít k provedení přírůstkové aktualizace exportu. Text ukázkové žádosti vypadá jako v následujícím příkladu enrichments , který aktualizuje soubor na export:

{
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ]
}

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Odstranění definice exportu

Pomocí následujícího požadavku odstraňte definici exportu:

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

Další kroky

Teď, když jste se dozvěděli, jak spravovat export dat pomocí rozhraní REST API, je dalším navrhovaným krokem téma Použití rozhraní IoT Central REST API ke správě šablon zařízení.