IoT Central REST API gebruiken om gegevensexports te beheren

Artikel
07/25/2023

Met de IoT Central REST API kunt u clienttoepassingen ontwikkelen die kunnen worden geïntegreerd met IoT Central-toepassingen. U kunt de REST API gebruiken om gegevensexports te maken en te beheren in uw IoT Central-toepassing.

Voor elke IoT Central REST API-aanroep is een autorisatieheader vereist. Zie IoT Central REST API-aanroepen verifiëren en autoriseren voor meer informatie.

Zie Azure IoT Central REST API reference (Naslaginformatie over azure IoT Central REST API) voor de referentiedocumentatie voor de IoT Central REST API.

Tip

U kunt Postman gebruiken om de REST API-aanroepen uit te proberen die in dit artikel worden beschreven. Download de IoT Central Postman-verzameling en importeer deze in Postman. In de verzameling moet u variabelen instellen, zoals uw app-subdomein en beheertoken.

Zie IoT-gegevens exporteren naar Blob Storage voor meer informatie over het beheren van gegevensexport met behulp van de IoT Central-gebruikersinterface.

Gegevensexport

U kunt de ioT Central-functie voor het exporteren van gegevens gebruiken om telemetrie, wijzigingen van eigenschappen, apparaatconnectiviteitsevenementen, levenscyclus gebeurtenissen van apparaten en levenscyclus gebeurtenissen van apparaatsjablonen te streamen naar bestemmingen zoals Azure Event Hubs, Azure Service Bus, Azure Blob Storage en webhook-eindpunten.

Elke definitie van gegevensexport kan gegevens verzenden naar een of meer bestemmingen. Maak de doeldefinities voordat u de exportdefinitie maakt.

Een bestemming maken of bijwerken

Gebruik de volgende aanvraag om een doeldefinitie te maken of bij te werken:

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

destinationId is een unieke id voor de bestemming.

In het volgende voorbeeld ziet u een aanvraagbody waarmee een blobopslagbestemming wordt gemaakt:

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

De aanvraagbody heeft een aantal vereiste velden:

displayName: Weergavenaam van het doel.
type: Type doelobject. Een van: blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, , servicebustopic@v1, . webhook@v1
connectionString: de connection string voor toegang tot de doelresource.
containerName: voor een blobopslagbestemming de naam van de container waarin de gegevens moeten worden geschreven.

Het antwoord op deze aanvraag ziet er als volgt uit:

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

Een bestemming ophalen op id

Gebruik de volgende aanvraag om details van een bestemming op te halen uit uw toepassing:

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

Het antwoord op deze aanvraag ziet er als volgt uit:

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

Bestemmingen weergeven

Gebruik de volgende aanvraag om een lijst met bestemmingen op te halen uit uw toepassing:

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

Het antwoord op deze aanvraag ziet er als volgt uit:

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

Een bestemming patchen

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

U kunt deze aanroep gebruiken om een incrementele update voor een export uit te voeren. De voorbeeldaanvraagbody ziet eruit als in het volgende voorbeeld, waarmee de connectionString van een bestemming wordt bijgewerkt:

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

Het antwoord op deze aanvraag ziet er als volgt uit:

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

Een bestemming verwijderen

Gebruik de volgende aanvraag om een bestemming te verwijderen:

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

Een exportdefinitie maken of bijwerken

Gebruik de volgende aanvraag om een definitie voor gegevensexport te maken of bij te werken:

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

In het volgende voorbeeld ziet u een aanvraagbody waarmee een exportdefinitie voor apparaattelemetrie wordt gemaakt:

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

De aanvraagbody heeft een aantal vereiste velden:

displayName: Weergavenaam van de export.
enabled: Schakel deze optie in om een export te starten/stoppen met het verzenden van gegevens.
source: het type gegevens dat moet worden geëxporteerd.
destinations: De lijst met bestemmingen waarnaar de export gegevens moet verzenden. De doel-id's moeten al in de toepassing bestaan.

Er zijn enkele optionele velden die u kunt gebruiken om meer details toe te voegen aan de export.

enrichments: Extra stukjes informatie die moet worden opgenomen in elk verzonden bericht. Gegevens worden weergegeven als een set sleutel-waardeparen, waarbij de sleutel de naam is van de verrijking die wordt weergegeven in het uitvoerbericht en de waarde de gegevens identificeert die moeten worden verzonden.
filter: Query die definieert welke gebeurtenissen uit de bron moeten worden geëxporteerd.

Het antwoord op deze aanvraag ziet er als volgt uit:

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

Verrijkingen

Er zijn drie typen verrijking die u aan een export kunt toevoegen: aangepaste tekenreeksen, systeemeigenschappen en aangepaste eigenschappen:

In het volgende voorbeeld ziet u hoe u het enrichments knooppunt gebruikt om een aangepaste tekenreeks toe te voegen aan het uitgaande bericht:

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

In het volgende voorbeeld ziet u hoe u het enrichments knooppunt gebruikt om een systeemeigenschap toe te voegen aan het uitgaande bericht:

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

U kunt de volgende systeemeigenschappen toevoegen:

Eigenschap	Beschrijving
`$enabled`	Is het apparaat ingeschakeld?
`$displayName`	De apparaatnaam.
`$templateDisplayName`	De naam van de apparaatsjabloon.
`$organizations`	De organisaties waartoe het apparaat behoort.
`$provisioned`	Is het apparaat ingericht?
`$simulated`	Is het apparaat gesimuleerd?

In het volgende voorbeeld ziet u hoe u het enrichments knooppunt gebruikt om een aangepaste eigenschap toe te voegen aan het uitgaande bericht. Aangepaste eigenschappen zijn eigenschappen die zijn gedefinieerd in de apparaatsjabloon waar het apparaat aan is gekoppeld:

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

Filters

U kunt de geëxporteerde berichten filteren op basis van telemetrie of eigenschapswaarden.

In het volgende voorbeeld ziet u hoe u het filter veld gebruikt om alleen berichten te exporteren waarvan de telemetriewaarde voor versnellingsmeter-X groter is dan 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"
}

In het volgende voorbeeld ziet u hoe u het filter veld gebruikt om alleen berichten te exporteren waarvan de temperature telemetriewaarde groter is dan de targetTemperature eigenschap:

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

Een export ophalen op id

Gebruik de volgende aanvraag om details van een exportdefinitie op te halen uit uw toepassing:

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

Het antwoord op deze aanvraag ziet er als volgt uit:

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

Exportdefinities weergeven

Gebruik de volgende aanvraag om een lijst met exportdefinities op te halen uit uw toepassing:

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

Het antwoord op deze aanvraag ziet er als volgt uit:

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

Een patch voor een exportdefinitie toepassen

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

U kunt deze aanroep gebruiken om een incrementele update voor een export uit te voeren. De voorbeeldaanvraagbody ziet eruit als in het volgende voorbeeld, waarmee de enrichments wordt bijgewerkt naar een export:

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

Het antwoord op deze aanvraag ziet er als volgt uit:

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

Een exportdefinitie verwijderen

Gebruik de volgende aanvraag om een exportdefinitie te verwijderen:

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

Volgende stappen

Nu u hebt geleerd hoe u gegevensexport beheert met de REST API, is een voorgestelde volgende stap Naar de IoT Central REST API gebruiken om apparaatsjablonen te beheren.

Share via

IoT Central REST API gebruiken om gegevensexports te beheren

Gegevensexport

Een bestemming maken of bijwerken

Een bestemming ophalen op id

Bestemmingen weergeven

Een bestemming patchen

Een bestemming verwijderen

Een exportdefinitie maken of bijwerken

Verrijkingen

Filters

Een export ophalen op id

Exportdefinities weergeven

Een patch voor een exportdefinitie toepassen

Een exportdefinitie verwijderen

Volgende stappen

Aanvullende resources