Az IoT Central REST API használata adatexportálások kezelésére
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 az Azure IoT Central REST API-referenciájában találja.
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 telemetriát, tulajdonságváltozásokat, eszközkapcsolati eseményeket, eszközéletciklus-eseményeket és eszközsablon-életciklus-eseményeket streamelhet olyan célhelyekre, mint az Azure Event Hubs, az Azure Service Bus, az Azure Blob Storage és a webhook-vé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élhelyet 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 megjelenítendő neve.type
: A célobjektum típusa. Az egyik: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 adatexportálási definí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/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
: Váltás az exportálás indítására/leállítására az adatok küldésével.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
: Az egyes elküldött üzenetekhez mellékelendő további információk. Az adatok kulcs/érték párok halmazaként jelennek meg, ahol a kulcs a kimeneti üzenetben megjelenő bővítés neve, és az érték azonosítja a küldendő adatokat.filter
: A forrásból exportálandó eseményeket meghatározó lekérdezés.
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ések
Az exportáláshoz háromféle bővítést 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 kimenő üzenethez a enrichments
csomópont használatával:
"enrichments": {
"My custom string": {
"value": "My value"
},
//...
}
Az alábbi példa bemutatja, hogyan adhat hozzá rendszertulajdonságot a kimenő üzenethez a enrichments
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 kimenő üzenethez a enrichments
csomópont használatával. Az egyéni tulajdonságok az eszközsablonban definiált tulajdonságok, amelyekhez az eszköz a következőhöz van társítva:
"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 exportálhat csak olyan üzeneteket a filter
mezővel, 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 exportálhat csak olyan üzeneteket a filter
mezővel, ahol a temperature
telemetriai érték nagyobb, mint a targetTemperature
tulajdonság:
{
"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 lekérheti 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 exportálási definíciók listáját az alkalmazásból:
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 frissíti az enrichments
exportálást:
{
"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 alábbi kéréssel törölhet egy exportálási definíciót:
DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview
Következő lépések
Most, hogy megtanulta, hogyan kezelheti az adatexportálást a REST API-val, javasolt következő lépés az IoT Central REST API használata az eszközsablonok kezeléséhez.