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

Článek
07/25/2023

Rozhraní IoT Central REST API 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 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 je 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",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "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",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "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é žádosti vypadá jako v následujícím příkladu connectionString , který aktualizuje cíl:

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

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",
    "authorization": {
      "type": "connectionString",
      "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"
}

Rozšiřování

Existují tři typy rozšiřování, které můžete přidat do exportu: vlastní řetězce, systémové vlastnosti a vlastní vlastnosti:

Následující příklad ukazuje, jak pomocí enrichments uzlu přidat vlastní řetězec do odchozí zprávy:

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

Následující příklad ukazuje, jak pomocí enrichments uzlu přidat systémovou vlastnost do odchozí zprávy:

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

Můžete přidat následující vlastnosti systému:

Vlastnost	Popis
`$enabled`	Je zařízení povolené?
`$displayName`	Název zařízení.
`$templateDisplayName`	Název šablony zařízení.
`$organizations`	Organizace, do které zařízení patří.
`$provisioned`	Je zařízení zřízené?
`$simulated`	Je zařízení simulované?

Následující příklad ukazuje, jak pomocí enrichments uzlu přidat vlastní vlastnost do odchozí zprávy. Vlastní vlastnosti jsou vlastnosti definované v šabloně zařízení, ke které je zařízení přidružené:

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

Filtry

Exportované zprávy můžete filtrovat na základě telemetrie nebo hodnot vlastností.

Následující příklad ukazuje, jak použít pole k exportu filter pouze zpráv, u kterých je hodnota telemetrie akcelerometer-X větší než 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"
}

Následující příklad ukazuje, jak použít pole k exportu filter pouze zpráv, u kterých temperature je hodnota telemetrie větší než targetTemperature vlastnost:

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

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ého požadavku vypadá jako v následujícím příkladu enrichments , který aktualizuje objekt na export:

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

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 2"
        }
    },
    "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 postup použití rozhraní IoT Central REST API ke správě šablon zařízení.

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

Export dat

Vytvoření nebo aktualizace cíle

Získání cíle podle ID

Vypsat cíle

Oprava cíle

Odstranění cíle

Vytvoření nebo aktualizace definice exportu

Rozšiřování

Filtry

Získání exportu podle ID

Definice exportu seznamu

Oprava definice exportu

Odstranění definice exportu

Další kroky

Další materiály