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

Artikel
07/25/2023

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.

Tipp

Sie können Postman verwenden, um die in diesem Artikel beschriebenen REST-API-Aufrufe auszuprobieren. Laden Sie die IoT Central Postman-Sammlung herunter, und importieren Sie sie in Postman. In der Sammlung müssen Sie Variablen wie Ihre App-Unterdomäne und Ihr Administratortoken festlegen.

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 Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=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.
connectionString: Dies ist die Verbindungszeichenfolge für den Zugriff auf die Zielressource.
containerName: Für ein Blobspeicherziel ist dies der Name des Containers, in den Daten geschrieben werden sollen.

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

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, das den connectionString eines Ziels aktualisiert:

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

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

Im folgenden Beispiel wird gezeigt, wie das filter Feld verwendet wird, um nur Nachrichten zu exportieren, bei denen der Telemetriewert beschleunigungsmesser-X 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": "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"
}

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

Feedback

Zusätzliche Ressourcen