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

Artikel
11/09/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 göra REST API-anrop och för att generera de ä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.

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 en av två auktoriseringstyper:

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.

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.

Anteckna värdet accessToken . Du använder det senare i självstudien.

Kommentar

Ägartoken upphör att gälla efter en timme. Om de upphör att gälla kör du samma kommandon för att generera nya ägartoken.

Skapa en resursgrupp

Använd Azure cli för att skapa en resursgrupp som innehåller det IoT Central-program som du skapar i den här självstudien:

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

Skapa ett IoT Central-program

Använd följande kommando för att generera ett IoT Central-program med ett slumpmässigt namn som ska användas i den här självstudien:

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

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

Anteckna programnamnet. Du använder det senare i den här självstudien.

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:

Kör följande kommando för att skapa en operatortoken som anropas operator-token med hjälp av Azure CLI. Roll-GUID är ID för operatorrollen i alla IoT Central-program:

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

Anteckna operatortoken som kommandot returnerar. Du använder den senare i självstudien. Token ser ut som SharedAccessSignature sr=2....

Kör följande kommando för att skapa en administratörstoken som anropas admin-token med hjälp av Azure CLI. Roll-GUID är ID för administratörsrollen i alla IoT Central-program:

$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"}]}'

Anteckna administratörstoken som kommandot returnerar. Du använder den senare i självstudien. Token ser ut som SharedAccessSignature sr=2....

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

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:

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"

Anteckna värdena idScope och primaryKey som kommandot returnerar. Du använder dem senare i självstudien.

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.

Skärmbild som visar QR-koden som du använder för att ansluta enheten.

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:

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"

Anteckna värdet template som kommandot returnerar. Du använder det senare i självstudien.

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

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"

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:

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"

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:

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"

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:

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}'

Rensa resurser

Om du har slutfört IoT Central-programmet som du använde i den här självstudien kan du ta bort det:

appName=<the app name generated previously>

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

Dela via