IoT Central REST API gebruiken om gegevensexports te beheren

Artikel
08/08/2024

Met de REST API van IoT Central 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.

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

Zie de naslaginformatie voor de REST API van IoT Central voor Azure IoT Central.

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 gegevensexport gebruiken om telemetrie te streamen, eigenschappenwijzigingen, apparaatconnectiviteitsevenementen, levenscyclus-gebeurtenissen van apparaten en gebeurtenissen voor de levenscyclus van apparaatsjablonen naar bestemmingen zoals Azure Event Hubs, Azure Service Bus, Azure Blob Storage en webhookeindpunten.

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 hoofdtekst van de aanvraag bevat enkele vereiste velden:

displayName: Weergavenaam van de bestemming.
type: Type doelobject. Een van: blobstorage@v1, dataexplorer@v1, eventhubs@v1, , servicebusqueue@v1, , servicebustopic@v1. webhook@v1
connectionString: de verbindingsreeks voor toegang tot de doelresource.
containerName: Voor een blobopslagbestemming moet de naam van de container waarin gegevens worden geschreven.

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

{
    "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 basis van 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 eruit als in het volgende voorbeeld:

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

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 eruit als in het volgende voorbeeld:

{
    "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 uit te voeren naar een export. De hoofdtekst van de voorbeeldaanvraag ziet eruit als in het volgende voorbeeld waarmee de connectionString bestemming wordt bijgewerkt:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

{
    "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 telemetriegegevens van apparaten wordt gemaakt:

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

De hoofdtekst van de aanvraag bevat enkele vereiste velden:

displayName: Weergavenaam van de export.
enabled: Schakel deze wisselknop om een export te starten/stoppen van 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 aanwezig zijn in de toepassing.

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

enrichments: Extra stukjes informatie die bij elk verzonden bericht moeten worden opgenomen. 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 eruit als in het volgende voorbeeld:

{
    "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 kunt toevoegen aan een export: 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:

Eigenschappen	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`	Wordt 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 waarmee het apparaat 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 waarbij de telemetriewaarde 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 waarbij 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 eruit als in het volgende voorbeeld:

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

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 eruit als in het volgende voorbeeld:

{
  "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 exportdefinitie patchen

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

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

{
    "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 het gebruik van de IoT Central REST API voor het beheren van apparaatsjablonen.

Delen via

IoT Central REST API gebruiken om gegevensexports te beheren

Gegevensexport

Een bestemming maken of bijwerken

Een bestemming ophalen op basis van id

Bestemmingen vermelden

Een bestemming patchen

Een bestemming verwijderen

Een exportdefinitie maken of bijwerken

Verrijkingen

Filters

Een export ophalen op id

Exportdefinities vermelden

Een exportdefinitie patchen

Een exportdefinitie verwijderen

Volgende stappen

Feedback

Aanvullende resources