Tutorial: Verwenden der REST-API zum Verwalten einer Azure IoT Central-Anwendung

  • Artikel

In diesem Tutorial erfahren Sie, wie Sie die Azure IoT Central-REST-API zum Erstellen einer und Interagieren mit einer IoT Central-Anwendung verwenden. In diesem Tutorial wird die REST-API verwendet, um viele der Schritte auszuführen, die Sie in den Schnellstarts über die Webbenutzeroberfläche ausgeführt haben. Zu diesen Schritten gehört die Verwendung einer App auf Ihrem Smartphone als IoT-Gerät, das eine Verbindung mit IoT Central herstellt.

In diesem Tutorial lernen Sie Folgendes:

  • Autorisieren der REST-API
  • Erstellen Sie eine IoT Central-Anwendung.
  • Hinzufügen eines Geräts zu Ihrer Anwendung
  • Abfragen und Steuern des Geräts
  • Einrichten des Datenexports
  • Löschen einer Anwendung.

Voraussetzungen

Zum Durchführen der Schritte in diesem Tutorial benötigen Sie Folgendes:

  • Ein aktives Azure-Abonnement. Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

  • Ein Android- oder iOS-Smartphone, auf dem Sie eine kostenlose App aus einem der offiziellen App-Stores installieren können.

Azure CLI

Sie verwenden die Azure CLI, um die Bearertoken zu generieren, die einige der REST-APIs für die Autorisierung verwenden.

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

postman

In diesem Tutorial verwenden Sie Postman, um die REST-API-Aufrufe durchzuführen. Wenn Sie Postman nicht herunterladen und installieren möchten, können Sie die Onlineversion verwenden. Sie können alle Schritte im Tutorial mit der kostenlosen Version von Postman ausführen.

Das Tutorial verwendet eine vordefinierte Postman-Sammlung, die einige Skripts enthält, die Ihnen beim Ausführen der Schritte helfen.

Importieren der Postman-Sammlung

Zum Importieren der Sammlung öffnen Sie Postman, und wählen Sie Import aus. Wählen Sie im Dialogfeld Import die Option Link aus, und fügen Sie die folgende URL ein. Wählen Sie dann Fortsetzen aus.

Ihr Arbeitsbereich enthält jetzt die Sammlung IoT Central REST tutorial. Diese Sammlung enthält alle APIs, die Sie im Tutorial verwenden.

Die Sammlung verwendet Variablen, um die REST-API-Aufrufe zu parametrisieren. Wählen Sie zum Anzeigen der Variablen die Auslassungspunkte (...) neben IoT Central REST tutorial und dann Bearbeiten aus. Wählen Sie anschließend Variablen aus. Viele der Variablen werden entweder automatisch festgelegt, wenn Sie die API-Aufrufe ausführen, oder sie verfügen über vordefinierte Werte.

Autorisieren der REST-API

Bevor Sie die REST-API verwenden können, müssen Sie die Autorisierung konfigurieren. Die REST-API-Aufrufe in diesem Tutorial verwenden einen von drei Autorisierungstypen:

  • Ein Bearertoken, das den Zugriff auf https://management.azure.com autorisiert. Sie verwenden dieses Bearertoken beim Erstellen und Löschen der IoT Central-Anwendung. Eine IoT Central-Anwendung ist eine Azure-Ressource.
  • Ein Bearertoken, das den Zugriff auf https://apps.azureiotcentral.com autorisiert. Sie verwenden dieses Bearertoken, um die API-Token in der IoT Central-Anwendung zu erstellen.
  • Administrator- und Operator-API-Token, die den Zugriff auf Funktionen in Ihrer IoT Central-Anwendung autorisieren. Sie verwenden diese Token für die meisten API-Aufrufe in diesem Tutorial. Diese Token autorisieren nur den Zugriff auf eine bestimmte IoT Central-Anwendung.

Weisen Sie den folgenden Variablen in der Postman-Sammlung Werte zu:

  • bearerToken: Führen Sie die folgenden Azure CLI-Befehle zum Generieren eines Bearertokens aus, das den Zugriff auf https://management.azure.com autorisiert:

    az login
az account get-access-token --resource https://management.azure.com

    Tipp

    Möglicherweise müssen Sie az login auch dann ausführen, wenn Sie Cloud Shell verwenden.

    Kopieren Sie für bearerToken in den Sammlungsvariablen den Wert accessToken in die Spalte Current value.

  • bearerTokenApp: Führen Sie die folgenden Azure CLI-Befehle aus, um ein Bearertoken zu generieren, das den Zugriff auf https://apps.azureiotcentral.com autorisiert:

    az account get-access-token --resource https://apps.azureiotcentral.com

    Tipp

    Wenn Sie eine neue Instanz Ihrer Shell gestartet haben, führen Sie az login erneut aus.

    Kopieren Sie für bearerTokenApp in den Sammlungsvariablen den Wert accessToken in die Spalte Current value.

  • subscriptionId: Ihre Abonnement-ID war in der Ausgabe der beiden vorherigen Befehle enthalten. Kopieren Sie für subscriptionId in den Sammlungsvariablen den Wert subscription in die Spalte Current value.

Screenshot that shows the variables set manually in the Postman collection.

Achten Sie darauf, die Änderungen an der Postman-Sammlung zu speichern.

Hinweis

Bearertoken laufen nach einer Stunde ab.

Erstellen einer Anwendung

Verwenden Sie die Steuerungsebene zum Erstellen und Verwalten von IoT Central-Anwendungen. Verwenden Sie die folgende PUT-Anforderung, um die Anwendung zu erstellen, die Sie in diesem Tutorial verwenden. Die Anforderung verwendet ein Bearertoken für die Autorisierung und generiert einen zufälligen Anwendungsnamen.

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Create an IoT central application aus.
  2. Wählen Sie Send (Senden) aus.
  3. Überprüfen Sie, ob die Anforderung erfolgreich war. War sie nicht erfolgreich, vergewissern Sie sich, dass Sie die Variablenwerte bearerToken und subscriptionId in die Postman-Sammlung eingegeben haben.
  4. Wählen Sie Visualize aus, um die URL Ihrer neuen IoT Central-Anwendung anzuzeigen. Notieren Sie sich diese URL, denn Sie werden sie später in diesem Tutorial benötigen.

Screenshot that shows the Visualize tab with the application URL in Postman.

Erstellen der API-Token

Verwenden Sie die folgenden Anforderungen auf Datenebene, um die Anwendungs-API-Token in Ihrer IoT Central-Anwendung zu erstellen. Einige der Anforderungen in diesem Tutorial erfordern ein API-Token mit Administratorberechtigungen, die Mehrheit kann jedoch Operatorberechtigungen verwenden:

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Create an operator token aus.
  2. Wählen Sie Send (Senden) aus.
  3. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Create an admin token aus.
  4. Wählen Sie Send (Senden) aus.

Wenn Sie diese Token in Ihrer IoT Central-Anwendung anzeigen möchten, öffnen Sie die Anwendung, und navigieren Sie zu Sicherheit > Berechtigungen > API-Token.

Hinweis

Ein Skript in Postman fügt diese API-Token automatisch für Sie der Liste der Sammlungsvariablen hinzu.

Registrieren eines Geräts

Sie müssen ein Gerät bei IoT Central registrieren, damit eine Verbindung hergestellt werden kann. Verwenden Sie die folgenden Anforderungen, um Ihr Gerät in Ihrer Anwendung zu registrieren und die Geräteanmeldeinformationen abzurufen. Die erste Anforderung erstellt ein Gerät mit phone-001 als Geräte-ID:

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Add a device aus.
  2. Wählen Sie Send (Senden) aus. In der Antwort sehen Sie, dass das Gerät nicht bereitgestellt wurde.
  3. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Get device credentials aus.
  4. Wählen Sie Send (Senden) aus.
  5. Auf der Registerkarte Visualize werden die Werte ID Scope und Primary Key angezeigt, die das Gerät zum Herstellen einer Verbindung benötigt.

Bereitstellen eines Geräts und Herstellen einer Verbindung damit

Damit Sie die Geräteanmeldeinformationen nicht manuell auf Ihrem Smartphone eingeben müssen, können Sie einen von IoT Central generierten QR-Code verwenden. Der QR-Code codiert die Geräte-ID, den ID-Bereich und den Primärschlüssel. So zeigen Sie den QR-Code an

  1. Öffnen Sie Ihre IoT Central-Anwendung mithilfe der Anwendungs-URL, die Sie sich zuvor notiert haben.
  2. Navigieren Sie in Ihrer IoT Central-Anwendung zu Geräte > Meine Smartphone-App > Verbinden> QR-Code. Lassen Sie diese Seite geöffnet, bis die Verbindung mit dem Gerät hergestellt wurde.

Screenshot that shows the QR code you use to connect the device.

Zur Vereinfachung des Setups wird in diesem Artikel die IoT Plug & Play-Smartphone-App als IoT-Gerät verwendet. Die App sendet Telemetriedaten, die von den Sensoren des Smartphones gesammelt wurden, reagiert auf Befehle, die von IoT Central ausgeführt werden, und meldet Eigenschaftswerte an IoT Central.

Installieren Sie die App aus einem der App Stores auf Ihrem Smartphone:

Get the app for your Android phone on Google Play.Download the app for your phone from the App Store.

So verbinden Sie die App IoT Plug & Play mit Ihrer IoT Central-Anwendung:

  1. Öffnen Sie die App IoT PnP auf Ihrem Smartphone.

  2. Wählen Sie auf der Willkommensseite Scan QR code (QR-Code scannen) aus. Erfassen Sie mit der Smartphone-Kamera den QR-Code. Warten Sie dann einige Sekunden, bis die Verbindung hergestellt wurde.

  3. Auf der Telemetrieseite in der App werden die Daten angezeigt, die die App an IoT Central sendet. Auf der Protokollseite wird angezeigt, dass das Gerät eine Verbindung herstellt, und es sind mehrere Initialisierungsmeldungen zu sehen.

Um zu überprüfen, ob das Gerät jetzt bereitgestellt ist, können Sie die REST-API verwenden:

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Get a device aus.
  2. Wählen Sie Send (Senden) aus. In der Antwort sehen Sie, dass das Gerät nun bereitgestellt ist. IoT Central weist dem Gerät zudem eine Gerätevorlage basierend auf der vom Gerät gesendeten Modell-ID zu.

Sie können die REST-API verwenden, um Gerätevorlagen in der Anwendung zu verwalten. So zeigen Sie beispielsweise die Gerätevorlagen in der Anwendung an

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung List device templates aus.
  2. Wählen Sie Send (Senden) aus.

Abfragen und Steuern des Geräts

Sie können die REST-API verwenden, um Telemetriedaten von Ihren Geräten abzufragen. Die folgende Anforderung gibt die Beschleunigungsmesserdaten von allen Geräten zurück, die die gleiche Gerätevorlagen-ID haben:

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Run a query aus.
  2. Wählen Sie Send (Senden) aus.

Sie können die REST-API verwenden, um Geräteeigenschaften zu lesen und festzulegen. Die folgende Anforderung gibt alle Eigenschaftswerte aus der vom Gerät implementierten Komponente Device Info zurück:

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Get properties from a component aus.
  2. Wählen Sie Send (Senden) aus.

Sie können die REST-API verwenden, um Gerätebefehle aufzurufen. Die folgende Anforderung ruft einen Befehl auf, der das Smartphone-Licht zweimal für drei Sekunden einschaltet. Damit der Befehl ausgeführt werden kann, muss der Smartphone-Bildschirm eingeschaltet und darauf die IoT Plug & Play-App sichtbar sein:

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Call command aus.
  2. Wählen Sie Send (Senden) aus.

Exportieren von Telemetriedaten

Sie können die REST-API verwenden, um Ihre IoT Central-Anwendung zu konfigurieren und zu verwalten. Die folgenden Schritte zeigen, wie Sie den Datenexport so konfigurieren, dass Telemetriewerte an einen Webhook gesendet werden. Zur Vereinfachung des Setups wird in diesem Artikel ein RequestBin-Webhook als Ziel verwendet. RequestBin ist ein Nicht-Microsoft-Dienst.

So erstellen Sie Ihren Testendpunkt für das Datenexportziel

  1. Navigieren Sie zu RequestBin.
  2. Wählen Sie Create a RequestBin aus.
  3. Melden Sie sich mit einer der verfügbaren Methoden an.
  4. Kopieren Sie die URL Ihres RequestBin-Endpunkts.
  5. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und navigieren Sie zu den Sammlungsvariablen.
  6. Fügen Sie die URL Ihres RequestBin-Endpunkts für webHookURL in den Sammlungsvariablen in die Spalte Current value ein.
  7. Speichern Sie die Änderungen.

So konfigurieren Sie das Exportziel in Ihrer IoT Central-Anwendung mithilfe der REST-API

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Create a webhook export destination aus.
  2. Wählen Sie Send (Senden) aus.

So konfigurieren Sie die Exportdefinition in Ihrer IoT Central-Anwendung mithilfe der REST-API

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Create a telemetry export definition aus.
  2. Wählen Sie Send (Senden) aus. Beachten Sie, dass der Status Not started lautet.

Es kann einige Minuten dauern, bis der Export gestartet wird. So überprüfen Sie den Status des Exports mithilfe der REST-API

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Get an export by ID aus.
  2. Wählen Sie Send (Senden) aus. Wenn der Status healthy lautet, sendet IoT Central Telemetriedaten an Ihren Webhook.

Die App auf Ihrem Smartphone sendet nur Telemetriedaten, wenn der Bildschirm eingeschaltet und die IoT Plug & Play-App sichtbar ist.

Wenn Ihre Smartphone-App Telemetriedaten sendet, navigieren Sie zu RequestBin, um die exportierten Telemetriedaten anzuzeigen.

Bereinigen von Ressourcen

Wenn Sie die IoT Central-Anwendung, die Sie in diesem Tutorial verwendet haben, nicht mehr benötigen, können Sie sie mithilfe der REST-API löschen:

  1. Öffnen Sie in Postman die Sammlung IoT Central REST tutorial, und wählen Sie die Anforderung Delete an IoT central application aus.
  2. Wählen Sie Send (Senden) aus.

Tipp

Diese Anforderung verwendet ein Bearertoken, das Sie zu Beginn des Tutorials generiert haben. Bearertoken laufen nach einer Stunde ab. Möglicherweise müssen Sie ein neues Bearertoken generieren, das den Zugriff auf https://apps.azureiotcentral.com autorisiert.

Nächste Schritte

Wenn Sie mit den Tutorials zu IoT Central fortfahren und mehr über das Erstellen einer IoT Central-Lösung erfahren möchten, lesen Sie den folgenden Artikel:

Erstellen einer Gatewaygerätevorlage