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

Článek
10/22/2024

Rozhraní IoT Central REST API umožňuje vyvíjet klientské aplikace, které se integrují s aplikacemi IoT Central. Rozhraní REST API můžete použít k vytváření a správě exportů dat v 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í dokumentaci k rozhraní IoT Central REST API najdete v referenčních informacích k rozhraní REST API služby Azure IoT Central.

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 definice cíle.

Vytvoření nebo aktualizace cíle

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

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",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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. Jeden z: blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, servicebustopic@v1, , webhook@v1. .
authorization: Podrobnosti o autorizaci cíle. Podporované typy autorizace jsou systemAssignedManagedIdentity a connectionString.

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": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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 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": "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"
        }
    ]
}

Oprava cíle

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

Pomocí tohoto volání můžete provést přírůstkovou aktualizaci exportu. Tělo ukázkové žádosti vypadá jako v následujícím příkladu, který aktualizuje containerName cíl:

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

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": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data-analysis"
    },
    "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

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

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, aby se odesílala data.
source: Typ dat, která se mají exportovat.
destinations: Seznam cílů, do kterých má export odesílat data. V aplikaci už musí existovat cílová ID.

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

enrichments: Dodatečné 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šiřování, 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é mají být exportovány.

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šíření

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í systémové vlastnosti:

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`	Simuluje se zařízení?

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 pomocí filter pole exportovat pouze zprávy, ve kterých je hodnota telemetrie accelerometer-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 pomocí filter pole exportovat pouze zprávy, ve 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": "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"
}

Definice exportu seznamu

Pomocí následujícího požadavku načtěte ze své aplikace seznam definic exportu:

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

Pomocí tohoto volání můžete provést přírůstkovou aktualizaci exportu. Text ukázkové žádosti vypadá jako v následujícím příkladu enrichments , který aktualizuje 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

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

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 navrhovaným dalším krokem použití rozhraní IoT Central REST API ke správě šablon zařízení.

Sdílet prostřednictvím

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

Seznam cílů

Oprava cíle

Odstranění cíle

Vytvoření nebo aktualizace definice exportu

Rozšíření

Filtry

Získání exportu podle ID

Definice exportu seznamu

Oprava definice exportu

Odstranění definice exportu

Další kroky

Váš názor

Další materiály