Verwenden der IoT Central-REST-API zum Verwalten von Datenexporten

Artikel
10/22/2024

Mit der IoT Central-REST-API können Sie Clientanwendungen entwickeln, die in IoT Central-Anwendungen integriert werden. Mit der REST-API können Sie in Ihrer IoT Central-Anwendung Datenexporte erstellen und verwalten.

Jeder IoT Central-REST-API-Aufruf erfordert einen Autorisierungsheader. Weitere Informationen finden Sie unter Authentifizieren und Autorisieren von IoT Central-REST-API-Aufrufen.

Die Referenzdokumentation für die IoT Central-REST-API finden Sie unter Azure IoT Central: Referenz zur REST-API.

Informationen zum Verwalten des Datenexports mithilfe der IoT Central-Benutzeroberfläche finden Sie unter Exportieren von IoT-Daten in Blob Storage.

Datenexport

Sie können das IoT Central-Datenexportfeature verwenden, um Telemetriedaten, Eigenschaftsänderungen, Gerätekonnektivitätsereignisse, Gerätelebenszyklusereignisse und Lebenszyklusereignisse von Gerätevorlagen an Ziele wie Azure Event Hubs, Azure Service Bus, Azure Blob Storage und Webhookendpunkte zu streamen.

Jede Datenexportdefinition kann Daten an ein oder mehrere Ziele senden. Erstellen Sie die Zieldefinitionen, bevor Sie die Exportdefinition erstellen.

Erstellen oder Aktualisieren eines Ziels

Verwenden Sie die folgende Anforderung, um eine Zieldefinition zu erstellen oder zu aktualisieren:

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

destinationId ist eine eindeutige ID für das Ziel.

Das folgende Beispiel zeigt einen Anforderungstext, der ein Blobspeicherziel erstellt:

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

Der Anforderungstext enthält einige erforderliche Felder:

displayName: Dies ist der Anzeigename des Ziels.
type: Typ des Zielobjekts. Einer der folgenden Werte: blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, servicebustopic@v1, webhook@v1.
authorization: Die Autorisierungsdetails für das Ziel. Die unterstützten Autorisierungstypen sind systemAssignedManagedIdentity und connectionString.

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Abrufen eines Ziels nach ID

Verwenden Sie die folgende Anforderung, um Details eines Ziels aus Ihrer Anwendung abzurufen:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Auflisten von Zielen

Verwenden Sie die folgende Anforderung, um eine Liste der Ziele aus Ihrer Anwendung abzurufen:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Patchen eines Ziels

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

Sie können diesen Aufruf verwenden, um ein inkrementelles Update für einen Export durchzuführen. Der Beispielanforderungstext sieht wie im folgenden Beispiel aus, in dem der containerName auf ein Ziel aktualisiert wird:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Löschen eines Ziels

Verwenden Sie die folgende Anforderung zum Löschen eines Ziels:

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

Erstellen oder Aktualisieren einer Exportdefinition

Verwenden Sie die folgende Anforderung, um eine Datenexportdefinition zu erstellen oder zu aktualisieren:

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

Das folgende Beispiel zeigt einen Anforderungstext, der eine Exportdefinition für Gerätetelemetriedaten erstellt:

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

Der Anforderungstext enthält einige erforderliche Felder:

displayName: Dies ist der Anzeigename des Exports.
enabled: Hiermit können Sie einstellen, ob bei einem Export das Senden von Daten gestartet oder beendet werden soll.
source: Dies ist der zu exportierende Datentyp.
destinations: Dies ist die Liste der Ziele, an die beim Exportvorgang Daten gesendet werden sollen. Die Ziel-IDs müssen bereits in der Anwendung vorhanden sein.

Es gibt einige optionale Felder, mit denen Sie dem Export weitere Details hinzufügen können.

enrichments: Dies sind zusätzliche Informationen, die in jede gesendete Nachricht eingeschlossen werden sollten. Daten werden als Schlüssel-Wert-Paare dargestellt, wobei der Schlüssel der Name der Erweiterung ist, die in der Ausgabenachricht angezeigt wird, und der Wert die zu sendenden Daten identifiziert.
filter: Mit dieser Abfrage wird definiert, welche Ereignisse aus der Quelle exportiert werden sollen.

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Anreicherungen

Es gibt drei Arten von Anreicherung, die Sie einem Export hinzufügen können: benutzerdefinierte Zeichenfolgen, Systemeigenschaften und benutzerdefinierte Eigenschaften:

Das folgende Beispiel zeigt, wie Sie den Knoten enrichments verwenden, um der ausgehenden Nachricht eine benutzerdefinierte Zeichenfolge hinzuzufügen:

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

Das folgende Beispiel zeigt, wie Sie den enrichments Knoten verwenden, um der ausgehenden Nachricht eine Systemeigenschaft hinzuzufügen:

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

Sie können die folgenden Systemeigenschaften hinzufügen:

Eigenschaft	Beschreibung
`$enabled`	Ist das Gerät aktiviert?
`$displayName`	Den Gerätenamen.
`$templateDisplayName`	Der Name der Gerätevorlage.
`$organizations`	Die Organisationen, zu denen das Gerät gehört.
`$provisioned`	Wird das Gerät bereitgestellt?
`$simulated`	Wird das Gerät simuliert?

Das folgende Beispiel zeigt, wie Sie den enrichments Knoten verwenden, um der ausgehenden Nachricht eine benutzerdefinierte Eigenschaft hinzuzufügen. Benutzerdefinierte Eigenschaften sind Eigenschaften, die in der Gerätevorlage definiert sind, der das Gerät zugeordnet ist:

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

Filter

Sie können die exportierten Nachrichten basierend auf Telemetrie- oder Eigenschaftswerten filtern.

Das folgende Beispiel zeigt, wie Sie das filter Feld verwenden, um nur Nachrichten zu exportieren, bei denen der Beschleunigungsmesser-X-Telemetriewert größer als 0 ist:

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

Das folgende Beispiel zeigt, wie Sie das filter Feld verwenden, um nur Nachrichten zu exportieren, bei denen der temperature Telemetriewert größer als die targetTemperature-Eigenschaft ist:

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

Abrufen eines Exports nach ID

Verwenden Sie die folgende Anforderung zum Abrufen von Details zu einer Exportdefinition aus Ihrer Anwendung:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Auflisten von Exportdefinitionen

Verwenden Sie die folgende Anforderung, um eine Liste der Exportdefinitionen aus Ihrer Anwendung abzurufen:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Patchen einer Exportdefinition

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

Sie können diesen Aufruf verwenden, um ein inkrementelles Update für einen Export durchzuführen. Der Beispielanforderungstext sieht wie im folgenden Beispiel aus, in dem enrichments auf einen Export aktualisiert wird:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Löschen einer Exportdefinition

Verwenden Sie die folgende Anforderung, um eine Exportdefinition zu löschen:

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

Nächste Schritte

Nachdem Sie erfahren haben, wie Sie Datenexporte mit der REST-API verwalten können, empfiehlt sich als nächster Schritt das Verwenden der IoT Central-REST-API zum Verwalten von Gerätevorlagen.

Teilen über

Verwenden der IoT Central-REST-API zum Verwalten von Datenexporten

Datenexport

Erstellen oder Aktualisieren eines Ziels

Abrufen eines Ziels nach ID

Auflisten von Zielen

Patchen eines Ziels

Löschen eines Ziels

Erstellen oder Aktualisieren einer Exportdefinition

Anreicherungen

Filter

Abrufen eines Exports nach ID

Auflisten von Exportdefinitionen

Patchen einer Exportdefinition

Löschen einer Exportdefinition

Nächste Schritte

Feedback

Zusätzliche Ressourcen