Zelfstudie: De REST API gebruiken om een Azure IoT Central-toepassing te beheren

Artikel
11/09/2024

In deze zelfstudie leert u hoe u de Azure IoT Central REST API gebruikt om een IoT Central-toepassing te maken en ermee te werken. In deze zelfstudie wordt de REST API gebruikt om veel van de stappen uit te voeren die u hebt voltooid met behulp van de webgebruikersinterface in de quickstarts. Deze stappen omvatten het gebruik van een app op uw smartphone als een IoT-apparaat dat verbinding maakt met IoT Central.

In deze zelfstudie leert u het volgende:

Autoriseren van de REST API.
Een IoT Central-toepassing maken.
Voeg een apparaat toe aan uw toepassing.
Query's uitvoeren en het apparaat beheren.
Gegevensexport instellen.
Een toepassing verwijderen.

Vereisten

Voor het voltooien van de stappen in deze zelfstudie hebt u het volgende nodig:

Een actief Azure-abonnement. Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.
Een Android- of iOS-smartphone waarop u een gratis app kunt installeren vanuit een van de officiële app stores.

Azure-CLI

U gebruikt de Azure CLI om de REST API-aanroepen uit te voeren en de bearer-tokens te genereren die door sommige REST API's worden gebruikt voor autorisatie.

Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.
Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.
- Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.
- Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.
- Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

De REST API autoriseren

Voordat u de REST API kunt gebruiken, moet u de autorisatie configureren. De REST API-aanroepen in deze zelfstudie gebruiken een van de twee autorisatietypen:

Een bearer-token dat toegang toekent tot https://apps.azureiotcentral.com. U gebruikt dit Bearer-token om de API-tokens te maken in de IoT Central-toepassing.
API-tokens voor beheerders en operatoren die toegang tot mogelijkheden in uw IoT Central-toepassing autoriseren. U gebruikt deze tokens voor de meeste API-aanroepen in deze zelfstudie. Deze tokens autoriseren alleen toegang tot één specifieke IoT Central-toepassing.

Voer de volgende Azure CLI-opdrachten uit om een Bearer-token te genereren waarmee toegang wordt https://apps.azureiotcentral.comtoegestaan:

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

Tip

Als u een nieuw exemplaar van uw shell hebt gestart, voert u deze opnieuw uit az login .

Noteer de waarde, u gebruikt deze accessToken later in de zelfstudie.

Notitie

Bearer-tokens verlopen na een uur. Als ze verlopen, voert u dezelfde opdrachten uit om nieuwe Bearer-tokens te genereren.

Een brongroep maken

Gebruik de Azure CLI om een resourcegroep te maken die de IoT Central-toepassing bevat die u in deze zelfstudie maakt:

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

Een Azure IoT Central-toepassing maken

Gebruik de volgende opdracht om een IoT Central-toepassing te genereren met een willekeurige naam die u in deze zelfstudie kunt gebruiken:

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

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

Noteer de naam van de toepassing. U gebruikt deze later in deze zelfstudie.

De API-tokens maken

Gebruik de volgende gegevensvlakaanvragen om de API-tokens voor de toepassing te maken in uw IoT Central-toepassing. Voor sommige aanvragen in deze zelfstudie is een API-token met beheerdersmachtigingen vereist, maar de meerderheid kan operatormachtigingen gebruiken:

Voer de volgende opdracht uit om een operatortoken te maken dat wordt aangeroepen operator-token met behulp van de Azure CLI. De rol-GUID is de id van de operatorrol in alle IoT Central-toepassingen:

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

Noteer het operatortoken dat door de opdracht wordt geretourneerd. U gebruikt dit later in de zelfstudie. Het token ziet er als SharedAccessSignature sr=2...volgt uit.

Voer de volgende opdracht uit om een beheertoken te maken dat wordt aangeroepen admin-token met behulp van de Azure CLI. De rol-GUID is de id van de beheerdersrol in alle IoT Central-toepassingen:

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

Noteer het beheertoken dat door de opdracht wordt geretourneerd. U gebruikt dit later in de zelfstudie. Het token ziet er als SharedAccessSignature sr=2...volgt uit.

Als u deze tokens in uw IoT Central-toepassing wilt zien, opent u de toepassing en gaat u naar API-tokens voor beveiligingsmachtigingen > >.

Een apparaat registreren

U moet een apparaat registreren bij IoT Central voordat het verbinding kan maken. Gebruik de volgende aanvragen om uw apparaat in uw toepassing te registreren en de apparaatreferenties op te halen. Met de eerste aanvraag maakt u een apparaat met telefoon-001 als apparaat-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"

Noteer de idScope waarden die primaryKey door de opdracht worden geretourneerd. U gebruikt deze later in de zelfstudie.

Een apparaat inrichten en verbinden

Om te voorkomen dat u de apparaatreferenties handmatig op uw smartphone moet invoeren, kunt u een QR-code gebruiken die is gegenereerd door IoT Central. De QR-code codeert de apparaat-id, het id-bereik, de primaire sleutel. De QR-code weergeven:

Open uw IoT Central-toepassing met behulp van de toepassings-URL die u eerder hebt genoteerd.
Navigeer in uw IoT Central-toepassing naar De QR-code voor apparaten > mijn telefoon-app > Verbinden>. Houd deze pagina open totdat het apparaat is verbonden.

Schermopname van de QR-code die u gebruikt om het apparaat te verbinden.

Ter vereenvoudiging van de installatie maakt dit artikel gebruik van de IoT Plug en Play smartphone-app als een IoT-apparaat. De app verzendt telemetrie die is verzameld van de sensoren van de smartphone, reageert op opdrachten die vanuit IoT Central worden aangeroepen en rapporteert eigenschapswaarden aan IoT Central.

Installeer de app op uw smartphone vanuit een van de app stores:

De IoT Plug en Play-app verbinden met uw Iot Central-toepassing:

Open de IoT PnP-app op uw smartphone.
Selecteer QR-code scannen op de welkomstpagina. Wijs de camera van de smartphone aan bij de QR-code. Wacht vervolgens een paar seconden terwijl de verbinding tot stand is gebracht.
Op de telemetriepagina in de app ziet u de gegevens die de app naar IoT Central verzendt. Op de logboekpagina ziet u het apparaat dat verbinding maakt en verschillende initialisatieberichten.

Als u wilt controleren of het apparaat nu is ingericht, kunt u de REST API gebruiken:

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"

Noteer de waarde die template de opdracht retourneert. U gebruikt deze later in de zelfstudie.

U kunt de REST API gebruiken om apparaatsjablonen in de toepassing te beheren. Als u bijvoorbeeld de apparaatsjablonen in de toepassing wilt weergeven:

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"

Het apparaat opvragen en beheren

U kunt de REST API gebruiken om een query uit te voeren op telemetrie van uw apparaten. De volgende aanvraag retourneert de accelerometergegevens van alle apparaten die een specifieke apparaatsjabloon-id delen:

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"

U kunt de REST API gebruiken om apparaateigenschappen te lezen en in te stellen. Met de volgende aanvraag worden alle eigenschapswaarden van het onderdeel Apparaatgegevens geretourneerd die door het apparaat worden geïmplementeerd:

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"

U kunt de REST API gebruiken om apparaatopdrachten aan te roepen. De volgende aanvraag roept een opdracht aan waarmee je smartphonelicht twee keer twee keer wordt ingeschakeld gedurende drie seconden. Om de opdracht uit te voeren, moet uw smartphonescherm zijn ingeschakeld met de IoT Plug en Play-app zichtbaar:

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

Resources opschonen

Als u klaar bent met de IoT Central-toepassing die u in deze zelfstudie hebt gebruikt, kunt u deze verwijderen:

appName=<the app name generated previously>

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

Delen via