Använda IoT Central REST API till att hantera dataexport

  • Artikel

Med REST API för IoT Central kan du utveckla klientprogram som integreras med IoT Central-program. Du kan använda REST-API:et för att skapa och hantera dataexporter i ditt IoT Central-program.

Varje IoT Central REST API-anrop kräver ett auktoriseringshuvud. Mer information finns i Autentisera och auktorisera IoT Central REST API-anrop.

Referensdokumentationen för REST API:et för IoT Central finns i Referens för Rest API för Azure IoT Central.

Information om hur du hanterar dataexport med hjälp av IoT Central-användargränssnittet finns i Exportera IoT-data till Blob Storage.

Dataexport

Du kan använda funktionen för dataexport i IoT Central för att strömma telemetri, egenskapsändringar, enhetsanslutningshändelser, händelser för enhetslivscykel och livscykelhändelser för enhetsmallar till mål som Azure Event Hubs, Azure Service Bus, Azure Blob Storage och webhook-slutpunkter.

Varje dataexportdefinition kan skicka data till ett eller flera mål. Skapa måldefinitionerna innan du skapar exportdefinitionen.

Skapa eller uppdatera ett mål

Använd följande begäran för att skapa eller uppdatera en måldefinition:

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

destinationId är ett unikt ID för målet.

I följande exempel visas en begärandetext som skapar ett bloblagringsmål:

{
  "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    }
}

Begärandetexten innehåller några obligatoriska fält:

  • displayName: Målets visningsnamn.
  • type: Typ av målobjekt. En av: blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, servicebustopic@v1, webhook@v1.
  • authorization: Auktoriseringsinformationen för målet. Auktoriseringstyperna som stöds är systemAssignedManagedIdentity och connectionString.

Svaret på den här begäran ser ut som i följande exempel:

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

Hämta ett mål efter ID

Använd följande begäran för att hämta information om ett mål från ditt program:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Lista mål

Använd följande begäran för att hämta en lista över mål från ditt program:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Korrigera ett mål

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

Du kan använda det här anropet för att utföra en inkrementell uppdatering av en export. Brödtexten för exempelbegäran ser ut som i följande exempel som uppdaterar containerName målets:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Ta bort ett mål

Använd följande begäran för att ta bort ett mål:

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

Skapa eller uppdatera en exportdefinition

Använd följande begäran för att skapa eller uppdatera en definition för dataexport:

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

I följande exempel visas en begärandetext som skapar en exportdefinition för enhetstelemetri:

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

Begärandetexten innehåller några obligatoriska fält:

  • displayName: Exportens visningsnamn.
  • enabled: Växla till att starta/stoppa en export från att skicka data.
  • source: Vilken typ av data som ska exporteras.
  • destinations: Listan över mål som exporten ska skicka data till. Mål-ID:t måste redan finnas i programmet.

Det finns några valfria fält som du kan använda för att lägga till mer information i exporten.

  • enrichments: Extra information som ska ingå i varje skickat meddelande. Data representeras som en uppsättning nyckel/värde-par, där nyckeln är namnet på berikningen som ska visas i utdatameddelandet och värdet identifierar de data som ska skickas.
  • filter: Fråga som definierar vilka händelser från källan som ska exporteras.

Svaret på den här begäran ser ut som i följande exempel:

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

Berikningar

Det finns tre typer av berikning som du kan lägga till i en export: anpassade strängar, systemegenskaper och anpassade egenskaper:

I följande exempel visas hur du använder enrichments noden för att lägga till en anpassad sträng i det utgående meddelandet:

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

I följande exempel visas hur du använder enrichments noden för att lägga till en systemegenskap i det utgående meddelandet:

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

Du kan lägga till följande systemegenskaper:

Property beskrivning
$enabled Är enheten aktiverad?
$displayName Enhetsnamnet.
$templateDisplayName Namnet på enhetsmallen.
$organizations De organisationer som enheten tillhör.
$provisioned Är enheten etablerad?
$simulated Simuleras enheten?

I följande exempel visas hur du använder enrichments noden för att lägga till en anpassad egenskap i det utgående meddelandet. Anpassade egenskaper är egenskaper som definieras i enhetsmallen som enheten är associerad med:

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

Filter

Du kan filtrera de exporterade meddelandena baserat på telemetri- eller egenskapsvärden.

I följande exempel visas hur du använder fältet filter för att endast exportera meddelanden där telemetrivärdet accelerometer-X är större än 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"
}

I följande exempel visas hur du använder fältet filter för att endast exportera meddelanden där temperature telemetrivärdet är större än targetTemperature egenskapen:

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

Hämta en export efter ID

Använd följande begäran för att hämta information om en exportdefinition från ditt program:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Lista exportdefinitioner

Använd följande begäran för att hämta en lista över exportdefinitioner från ditt program:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Korrigera en exportdefinition

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

Du kan använda det här anropet för att utföra en inkrementell uppdatering av en export. Brödtexten för exempelbegäran ser ut som i följande exempel som uppdaterar enrichments till en export:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Ta bort en exportdefinition

Använd följande begäran för att ta bort en exportdefinition:

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

Nästa steg

Nu när du har lärt dig hur du hanterar dataexport med REST-API:et är ett föreslaget nästa steg att använda REST-API:et för IoT Central för att hantera enhetsmallar.