Share via

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 REST API-anrop i IoT Central kräver ett auktoriseringshuvud. Mer information finns i Autentisera och auktorisera REST API-anrop för IoT Central.

Referensdokumentationen för REST API för IoT Central finns i REST API-referensen för Azure IoT Central.

Tips

Du kan använda Postman för att prova REST API-anropen som beskrivs i den här artikeln. Ladda ned IoT Central Postman-samlingen och importera den till Postman. I samlingen måste du ange variabler som appens underdomän och administratörstoken.

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 dataexportfunktionen IoT Central för att strömma telemetri, egenskapsändringar, enhetsanslutningshändelser, händelser för enhetens livscykel 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 Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=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.
  • connectionString: Anslutningssträngen för åtkomst till målresursen.
  • containerName: För ett bloblagringsmål ska namnet på containern där data ska skrivas.

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": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=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": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=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": "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"
        }
    ]
}

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. Exempelbegärandetexten ser ut som i följande exempel som uppdaterar connectionString ett mål:

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

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": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "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 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 berikande 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:

Egenskap Beskrivning
$enabled Är enheten aktiverad?
$displayName Enhetens namn.
$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.

Följande exempel visar hur du använder fältet filter för att exportera endast 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": "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"
}

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. Exempelbegärandetexten 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.