Självstudie: Använda REST API för att hantera ett Azure IoT Central-program

Artikel
03/04/2024

Den här självstudien visar hur du använder Rest-API:et för Azure IoT Central för att skapa och interagera med ett IoT Central-program. I den här självstudien används REST-API:et för att slutföra många av de steg som du har slutfört med hjälp av webbgränssnittet i snabbstarterna. Dessa steg omfattar användning av en app på din smartphone som en IoT-enhet som ansluter till IoT Central.

I den här självstudien lär du dig att:

Auktorisera REST-API:et.
Skapa ett IoT Central-program.
Lägg till en enhet i programmet.
Fråga och kontrollera enheten.
Konfigurera dataexport.
Ta bort ett program.

Förutsättningar

För att slutföra stegen i den här självstudien behöver du:

En aktiv Azure-prenumeration. Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.
En Android- eller iOS-smartphone där du kan installera en kostnadsfri app från någon av de officiella appbutikerna.

Azure CLI

Du använder Azure CLI för att generera ägartoken som vissa REST-API:er använder för auktorisering.

Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.
Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.
- Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.
- När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.
- Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Postman

I den här självstudien använder du Postman för att göra REST API-anrop. Om du föredrar att inte ladda ned och installera Postman kan du använda onlineversionen. Du kan slutföra alla steg i självstudien med hjälp av den kostnadsfria versionen av Postman.

I självstudien används en fördefinierad Postman-samling som innehåller några skript som hjälper dig att slutföra stegen.

Importera en Postman-samling

Om du vill importera samlingen öppnar du Postman och väljer Importera. I dialogrutan Importera väljer du Länka och klistrar in följande URL och väljer Fortsätt.

Din arbetsyta innehåller nu IoT Central REST-självstudiesamlingen. Den här samlingen innehåller alla API:er som du använder i självstudien.

Samlingen använder variabler för att parametrisera REST API-anropen. Om du vill se variablerna väljer du ... nästa rest-självstudiekurs för IoT Central och väljer Redigera. Välj sedan Variabler. Många av variablerna anges antingen automatiskt när du gör API-anropen eller har förinställda värden.

Auktorisera REST-API:et

Innan du kan använda REST-API:et måste du konfigurera auktoriseringen. REST API-anropen i den här självstudien använder någon av tre auktoriseringstyper:

En ägartoken som tillåter åtkomst till https://management.azure.com. Du använder den här ägartoken när du skapar och tar bort och IoT Central-programmet. Ett IoT Central-program är en Azure-resurs.
En ägartoken som tillåter åtkomst till https://apps.azureiotcentral.com. Du använder den här ägartoken för att skapa API-token i IoT Central-programmet.
Api-token för administratör och operatör som auktoriserar åtkomst till funktioner i ditt IoT Central-program. Du använder dessa token för de flesta API-anrop i den här självstudien. Dessa token auktoriserar endast åtkomst till ett specifikt IoT Central-program.

Tilldela värden till följande variabler i Postman-samlingen:

bearerToken: Kör följande Azure CLI-kommandon för att generera en ägartoken som ger åtkomst till https://management.azure.com:
```
az login
az account get-access-token --resource https://management.azure.com
```
Dricks

Du kan behöva köra az login även om du använder Cloud Shell.

Kopiera värdet accessToken till kolumnen Aktuellt värde för bearerToken i samlingsvariablerna.
bearerTokenApp: Kör följande Azure CLI-kommandon för att generera en ägartoken som ger åtkomst till https://apps.azureiotcentral.com:
```
az account get-access-token --resource https://apps.azureiotcentral.com
```
Dricks

Om du har startat en ny instans av gränssnittet kör du az login igen.

Kopiera värdet accessToken till kolumnen Aktuellt värde för bearerTokenApp i samlingsvariablerna.
subscriptionId: Ditt prenumerations-ID ingick i utdata från de två tidigare kommandona. Kopiera värdet subscription till kolumnen Aktuellt värde för subscriptionId i samlingsvariablerna.

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

Spara ändringarna i Postman-samlingen.

Kommentar

Ägartoken upphör att gälla efter en timme.

Skapa ett program

Använd kontrollplansbegäranden för att skapa och hantera centrala IoT-program. Använd följande PUT-begäran för att skapa det program som du använder i den här självstudien. Begäran använder en ägartoken för att auktorisera och genererar ett slumpmässigt programnamn.

Öppna självstudiesamlingen IoT Central REST i Postman och välj begäran Skapa ett centralt IoT-program.
Välj Skicka.
Kontrollera att begäran lyckas. Om det misslyckas kontrollerar du att du har angett variabelvärdena bearerToken och subscriptionId i Postman-samlingen.
Välj Visualisera för att se URL:en för ditt nya IoT Central-program. Anteckna den här URL:en. Du behöver den senare i den här självstudien.

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

Skapa API-token

Använd följande dataplansbegäranden för att skapa program-API-token i ditt IoT Central-program. Vissa av begäranden i den här självstudien kräver en API-token med administratörsbehörigheter, men de flesta kan använda operatörsbehörigheter:

Öppna självstudiesamlingen IoT Central REST i Postman och välj begäran Skapa en operatortoken.
Välj Skicka.
Öppna självstudiesamlingen IoT Central REST i Postman och välj begäran Skapa en administratörstoken.
Välj Skicka.

Om du vill se dessa token i ditt centrala IoT-program öppnar du programmet och navigerar till API-token för säkerhetsbehörigheter >>.

Kommentar

Ett skript i Postman lägger automatiskt till dessa API-token i listan över samlingsvariabler åt dig.

Registrera en enhet

Du måste registrera en enhet med IoT Central innan den kan ansluta. Använd följande begäranden för att registrera enheten i ditt program och hämta enhetens autentiseringsuppgifter. Den första begäran skapar en enhet med telefon-001 som enhets-ID:

Öppna självstudiesamlingen IoT Central REST i Postman och välj Lägg till en enhetsbegäran.
Välj Skicka. Observera att enheten inte har etablerats i svaret.
Öppna självstudiesamlingen IoT Central REST i Postman och välj begäran Hämta autentiseringsuppgifter för enheten.
Välj Skicka.
Fliken Visualisera visar de ID-omfång och primärnyckelvärden som enheten behöver för att kunna ansluta.

Etablera och ansluta en enhet

För att undvika behovet av att ange enhetens autentiseringsuppgifter manuellt på din smartphone kan du använda en QR-kod som genereras av IoT Central. QR-koden kodar enhets-ID, ID-omfång, primärnyckel. Så här visar du QR-koden:

Öppna ditt centrala IoT-program med hjälp av den program-URL som du antecknade tidigare.
I ditt IoT Central-program går du till Enheter > Min telefonapp > Anslut > QR-kod. Håll den här sidan öppen tills enheten är ansluten.

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

För att förenkla installationen använder den här artikeln IoT Plug and Play smartphone-appen som en IoT-enhet. Appen skickar telemetri som samlas in från smarttelefonens sensorer, svarar på kommandon som anropas från IoT Central och rapporterar egenskapsvärden till IoT Central.

Installera appen på din smartphone från någon av appbutikerna:

Så här ansluter du IoT Plug and Play-appen till ditt Iot Central-program:

Öppna IoT PnP-appen på din smartphone.
På välkomstsidan väljer du Skanna QR-kod. Rikta smarttelefonens kamera mot QR-koden. Vänta sedan några sekunder medan anslutningen upprättas.
På telemetrisidan i appen kan du se de data som appen skickar till IoT Central. På loggsidan kan du se enheten som ansluter och flera initieringsmeddelanden.

Om du vill kontrollera att enheten nu har etablerats kan du använda REST-API:et:

Öppna självstudiesamlingen IoT Central REST i Postman och välj hämta en enhetsbegäran.
Välj Skicka. Observera att enheten nu har etablerats i svaret. IoT Central tilldelade också en enhetsmall till enheten baserat på modell-ID:t som skickades av enheten.

Du kan använda REST-API:et för att hantera enhetsmallar i programmet. Om du till exempel vill visa enhetsmallarna i programmet:

I Postman öppnar du IoT Central REST-självstudiesamlingenoch väljer begäran List device templates (Lista enhetsmallar ).
Välj Skicka.

Fråga och kontrollera enheten

Du kan använda REST-API:et för att fråga telemetri från dina enheter. Följande begäran returnerar accelerometerdata från alla enheter som delar ett specifikt enhetsmalls-ID:

Öppna självstudiesamlingen IoT Central REST i Postman och välj kör en frågebegäran.
Välj Skicka.

Du kan använda REST-API:et för att läsa och ange enhetsegenskaper. Följande begäran returnerar alla egenskapsvärden från komponenten Enhetsinformation som enheten implementerar:

Öppna självstudiesamlingen IoT Central REST i Postman och välj Hämta egenskaper från en komponentbegäran.
Välj Skicka.

Du kan använda REST-API:et för att anropa enhetskommandon. Följande begäran anropar ett kommando som slår på din smartphone-lampa två gånger i tre sekunder. För att kommandot ska köras måste smarttelefonskärmen vara på med IoT Plug and Play-appen synlig:

I Postman öppnar du IoT Central REST-självstudiesamlingenoch väljer kommandotolken Samtal.
Välj Skicka.

Exportera telemetri

Du kan använda REST-API:et för att konfigurera och hantera ditt IoT Central-program. Följande steg visar hur du konfigurerar dataexport för att skicka telemetrivärden till en webhook. För att förenkla installationen använder den här artikeln en RequestBin-webhook som mål. RequestBin är en tjänst som inte kommer från Microsoft.

Så här skapar du testslutpunkten för dataexportmålet:

Gå till RequestBin.
Välj Skapa en RequestBin.
Logga in med någon av de tillgängliga metoderna.
Kopiera URL:en för din RequestBin-slutpunkt.
I Postman öppnar du IoT Central REST-självstudiesamlingen och navigerar till samlingsvariablerna.
Klistra in URL:en för din RequestBin-slutpunkt i kolumnen Aktuellt värde för webHookURL i samlingsvariablerna.
Spara ändringarna.

Så här konfigurerar du exportmålet i ditt IoT Central-program med hjälp av REST-API:et:

Öppna självstudiesamlingen IoT Central REST i Postman och välj begäran Skapa en webhook-exportmål.
Välj Skicka.

Så här konfigurerar du exportdefinitionen i ditt IoT Central-program med hjälp av REST-API:et:

Öppna självstudiesamlingen IoT Central REST i Postman och välj begäran Skapa en telemetriexportdefinition.
Välj Skicka. Observera att statusen Inte har startats.

Det kan ta några minuter innan exporten startar. Så här kontrollerar du statusen för exporten med hjälp av REST-API:et:

Öppna självstudiesamlingen IoT Central REST i Postman och välj begäran Hämta en export efter ID.
Välj Skicka. När statusen är felfri skickar IoT Central telemetri till din webhook.

Appen på din smartphone skickar inte telemetri om inte skärmen är på och IoT Plug and Play-appen är synlig.

När din smartphone-app skickar telemetri går du till din RequestBin för att visa den exporterade telemetrin.

Rensa resurser

Om du är klar med det IoT Central-program som du använde i den här självstudien kan du använda REST API för att ta bort det:

Öppna självstudiesamlingen IoT Central REST i Postman och välj begäran Ta bort ett centralt IoT-program.
Välj Skicka.

Dricks

Den här begäran använder en ägartoken som du genererade i början av självstudien. Ägartoken upphör att gälla efter timme. Du kan behöva generera en ny ägartoken som ger åtkomst till https://apps.azureiotcentral.com.

Nästa steg

Om du föredrar att fortsätta med IoT Central-självstudierna och lära dig mer om att skapa en IoT Central-lösning kan du läsa:

Skapa en gatewayenhetsmall