Freigeben über

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 REST-API-Aufrufe zu tätigen und 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.

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 zwei Autorisierungstypen:

  • 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.

Führen Sie die folgenden Azure CLI-Befehle zum Generieren eines Bearertokens aus, 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.

Notieren Sie sich den accessToken-Wert. Sie benötigen ihn später im Tutorial.

Hinweis

Bearertoken laufen nach einer Stunde ab. Falls sie ablaufen, führen Sie dieselben Befehle aus, um neue Bearertoken zu generieren.

Erstellen einer Ressourcengruppe

Verwenden Sie die Azure CLI, um eine Ressourcengruppe zu erstellen, die die IoT Central-Anwendung enthält, die Sie in diesem Tutorial erstellen:

az group create --name iot-central-rest-tutorial --location eastus

Erstellen einer IoT Central-Anwendung

Verwenden Sie den folgenden Befehl, um eine IoT Central-Anwendung mit einem zufälligen Namen zu generieren, der in diesem Tutorial verwendet werden soll:

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

Notieren Sie sich den Anwendungsnamen, das Sie Ihn später in diesem Tutorial benötigen.

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:

Führen Sie den folgenden Befehl aus, um ein Operatortoken namens operator-token zu erstellen, das mithilfe der Azure CLI aufgerufen wird. Die Rollen-GUID ist die ID der Operatorrolle in allen IoT Central-Anwendungen:

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

Notieren Sie sich das Operatortoken, das der Befehl zurückgibt, da Sie es später im Tutorial benötigen. Das Token sieht wie SharedAccessSignature sr=2... aus.

Führen Sie den folgenden Befehl aus, um ein Administratortoken namens admin-token zu erstellen, das mithilfe der Azure CLI aufgerufen wird. Die Rollen-GUID ist die ID der Administratorrolle in allen IoT Central-Anwendungen:

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

Notieren Sie sich das Administratortoken, das der Befehl zurückgibt, da Sie es später im Tutorial benötigen. Das Token sieht wie SharedAccessSignature sr=2... 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.

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Notieren Sie sich die Werte idScope und primaryKey, die der Befehl zurückgibt, da Sie sie später im Tutorial benötigen.

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: QR-Code zum Verbinden des Geräts

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:

Abrufen der App für Ihr Android-Smartphone aus Google PlayLaden Sie die App für Ihr Telefon aus dem App Store herunter.

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Notieren Sie sich den Wert template, den der Befehl zurückgibt, da Sie ihn später im Tutorial benötigen.

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

Bereinigen von Ressourcen

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

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial