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

Rozhraní REST API služby IoT Central umožňuje vyvíjet klientské aplikace, které se integrují s aplikacemi IoT Central. Pomocí rozhraní REST API můžete vytvářet a spravovat exporty dat. ve vaší aplikaci IoT Central.

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

Referenční dokumentace k rozhraní REST API služby IoT Central najdete v referenčních informacích k rozhraní REST API služby Azure IoT Central.

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 Postmanu. 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

Pomocí funkce exportu dat IoT Central můžete streamovat telemetrická data, změny vlastností, události připojení zařízení, události životního cyklu zařízení a události ž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 cílovou definici:

PUT https://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.2-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, který může být jedním z: blobstorage@v1, , dataexplorer@v1eventhubs@v1, servicebusqueue@v1, . webhook@v1servicebustopic@v1
  • connectionString: Připojovací řetězec pro přístup k cílovému prostředku.
  • containerName: Pro cíl úložiště objektů blob zadejte 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://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.2-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"
}

Seznam cílů

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

GET https://{subdomain}.{baseDomain}/api/dataExport/destinations?api-version=1.2-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": "http://requestbin.net/r/f7x2i1ug",
            "headerCustomizations": {},
            "status": "error",
        }
        }
    ]
}

Oprava cíle

PATCH https://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.2-preview

Můžete ho použít k provedení přírůstkové aktualizace exportu. Text ukázkové žádosti vypadá jako v následujícím příkladu, který aktualizuje displayName 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://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.2-preview

Vytvoření nebo aktualizace definice exportu

K vytvoření nebo aktualizaci definice exportu dat použijte následující požadavek:

PUT https://{subdomain}.{baseDomain}/api/dataExport/exports/{exportId}?api-version=1.2-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 odesílající data.
  • source: Typ dat k exportu.
  • destinations: Seznam cílů, do kterých má export odesílat data. Cílové ID musí již existovat v aplikaci.

Existují některá volitelná pole, která můžete použít k přidání dalších podrobností do 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í události ze zdroje, které 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://{subdomain}.{baseDomain}/api/dataExport/exports/{exportId}?api-version=1.2-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://{subdomain}.{baseDomain}/api/dataExport/exports?api-version=1.2-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://{subdomain}.{baseDomain}/dataExport/exports/{exportId}?api-version=1.2-preview

Můžete ho použít k provedení přírůstkové aktualizace exportu. Text ukázkové žádosti vypadá jako v následujícím příkladu, který aktualizuje enrichments 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

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

DELETE https://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.2-preview

Další kroky

Teď, když jste se dozvěděli, jak spravovat export dat pomocí rozhraní REST API, je navrhovaný další krok, jak pomocí rozhraní IOT Central REST API spravovat šablony zařízení.