Az IoT Central REST API használata adatexportálások kezelésére

Cikk
07/25/2023

Az IoT Central REST API lehetővé teszi az IoT Central-alkalmazásokkal integrálható ügyfélalkalmazások fejlesztését. A REST API-val adatexportálásokat hozhat létre és kezelhet az IoT Central-alkalmazásban.

Minden IoT Central REST API-híváshoz szükség van egy engedélyezési fejlécre. További információ: IoT Central REST API-hívások hitelesítése és engedélyezése.

Az IoT Central REST API referenciadokumentációját lásd: Azure IoT Central REST API-referencia.

Tipp

A Postman használatával kipróbálhatja a cikkben ismertetett REST API-hívásokat. Töltse le az IoT Central Postman gyűjteményt , és importálja a Postmanbe. A gyűjteményben olyan változókat kell beállítania, mint az alkalmazás altartománya és a rendszergazdai jogkivonat.

Az IoT Central felhasználói felületének használatával történő adatexportálás kezeléséről az IoT-adatok Blob Storage-ba való exportálása című témakörben olvashat.

Adatexportálás

Az IoT Central adatexportálási funkciójával telemetriai adatokat, tulajdonságváltozásokat, eszközkapcsolati eseményeket, eszközéletciklus-eseményeket és eszközsablon-életciklus-eseményeket streamelhet olyan célhelyekre, mint a Azure Event Hubs, a Azure Service Bus, a Azure Blob Storage és a webhookvégpontok.

Minden adatexportálási definíció egy vagy több célhelyre küldhet adatokat. Az exportálási definíció létrehozása előtt hozza létre a céldefiníciókat.

Cél létrehozása vagy frissítése

A céldefiníció létrehozásához vagy frissítéséhez használja a következő kérést:

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

destinationId a cél egyedi azonosítója.

Az alábbi példa egy blobtároló célhelyét létrehozó kérelemtörzset mutat be:

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

A kérelem törzse tartalmaz néhány kötelező mezőt:

displayName: A célhely neve.
type: A célobjektum típusa. Az alábbiak egyike: blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, , servicebustopic@v1. webhook@v1
connectionString: A célerőforrás elérésére szolgáló kapcsolati sztring.
containerName: Blob Storage-célhely esetén annak a tárolónak a neve, amelyben az adatokat meg kell írni.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Cél lekérése azonosító alapján

A következő kéréssel lekérheti egy célhely adatait az alkalmazásból:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Célhelyek listázása

A következő kéréssel lekérheti a célhelyek listáját az alkalmazásból:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Célhely javítása

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

Ezzel a hívással növekményes frissítést hajthat végre egy exportáláson. A mintakérés törzse a következő példához hasonlóan néz ki, amely frissíti a connectionString célhelyet:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Cél törlése

A célhely törléséhez használja a következő kérést:

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

Exportálási definíció létrehozása vagy frissítése

Az alábbi kéréssel hozhat létre vagy frissíthet adatexportálási definíciót:

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

Az alábbi példa egy kérelemtörzset mutat be, amely létrehoz egy exportálási definíciót az eszköz telemetriai adataihoz:

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

A kérelem törzse tartalmaz néhány kötelező mezőt:

displayName: Az exportálás megjelenítendő neve.
enabled: Az exportálás indításához/leállításához állítsa le az adatküldést.
source: Az exportálandó adatok típusa.
destinations: Azon célhelyek listája, amelyekre az exportálásnak adatokat kell küldenie. A célazonosítóknak már létezniük kell az alkalmazásban.

Néhány választható mezővel további részleteket adhat hozzá az exportáláshoz.

enrichments: További információk, amelyeket minden elküldött üzenethez mellékelhet. Az adatok kulcs/érték párok halmazaként jelennek meg, ahol a kulcs a kimeneti üzenetben megjelenő bővítés neve, az érték pedig az elküldendő adatokat azonosítja.
filter: Lekérdezés, amely meghatározza, hogy a forrásból mely eseményeket kell exportálni.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Bővítés

Az exportáláshoz három bővítési típust adhat hozzá: egyéni sztringeket, rendszertulajdonságokat és egyéni tulajdonságokat:

Az alábbi példa bemutatja, hogyan adhat hozzá egyéni sztringet a enrichments kimenő üzenethez a csomópont használatával:

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

Az alábbi példa bemutatja, hogyan adhat hozzá rendszertulajdonságot a enrichments kimenő üzenethez a csomópont használatával:

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

A következő rendszertulajdonságokat adhatja hozzá:

Tulajdonság	Leírás
`$enabled`	Engedélyezve van az eszköz?
`$displayName`	Az eszköz neve.
`$templateDisplayName`	Az eszközsablon neve.
`$organizations`	Azok a szervezetek, amelyhez az eszköz tartozik.
`$provisioned`	Ki van építve az eszköz?
`$simulated`	Szimulálja az eszközt?

Az alábbi példa bemutatja, hogyan adhat hozzá egyéni tulajdonságot a enrichments kimenő üzenethez a csomópont használatával. Az egyéni tulajdonságok olyan tulajdonságok, amelyek abban az eszközsablonban vannak meghatározva, amelyhez az eszköz társítva van:

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

Szűrők

Az exportált üzeneteket telemetria- vagy tulajdonságértékek alapján szűrheti.

Az alábbi példa bemutatja, hogyan lehet a filter mezőt csak olyan üzenetek exportálására használni, ahol a gyorsulásmérő-X telemetria értéke 0-nál nagyobb:

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

Az alábbi példa bemutatja, hogyan lehet a filter mezőt csak olyan üzenetek exportálására használni, ahol a temperature telemetriai érték nagyobb a targetTemperature tulajdonságnál:

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

Exportálás lekérése azonosító alapján

Az alábbi kéréssel kérheti le egy exportálási definíció részleteit az alkalmazásból:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Exportálási definíciók listázása

Az alábbi kéréssel lekérheti az alkalmazásból az exportálási definíciók listáját:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Exportálási definíció javítása

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

Ezzel a hívással növekményes frissítést hajthat végre egy exportáláson. A mintakérés törzse az alábbi példához hasonlóan néz ki, amely az exportálást frissíti enrichments :

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Exportálási definíció törlése

Az exportálási definíció törléséhez használja az alábbi kérést:

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

Következő lépések

Most, hogy megismerte, hogyan kezelheti az adatexportálást a REST API-val, a következő javasolt lépés az IoT Central REST API használata az eszközsablonok kezeléséhez.

Az IoT Central REST API használata adatexportálások kezelésére

Adatexportálás

Cél létrehozása vagy frissítése

Cél lekérése azonosító alapján

Célhelyek listázása

Célhely javítása

Cél törlése

Exportálási definíció létrehozása vagy frissítése

Bővítés

Szűrők

Exportálás lekérése azonosító alapján

Exportálási definíciók listázása

Exportálási definíció javítása

Exportálási definíció törlése

Következő lépések

További források