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

Artikel
03/04/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 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.

Postman

In deze zelfstudie gebruikt u Postman om de REST API-aanroepen uit te voeren. Als u Postman liever niet downloadt en installeert, kunt u de onlineversie gebruiken. U kunt alle stappen in de zelfstudie uitvoeren met behulp van de gratis versie van Postman.

In de zelfstudie wordt een vooraf gedefinieerde Postman-verzameling gebruikt die enkele scripts bevat om u te helpen bij het voltooien van de stappen.

De Postman-verzameling importeren

Als u de verzameling wilt importeren, opent u Postman en selecteert u Importeren. Selecteer Koppeling in het dialoogvenster Importeren en plak de volgende URL en selecteer Doorgaan.

Uw werkruimte bevat nu de ioT Central REST-zelfstudieverzameling . Deze verzameling bevat alle API's die u in de zelfstudie gebruikt.

De verzameling maakt gebruik van variabelen om de REST API-aanroepen te parameteriseren. Als u de variabelen wilt zien, selecteert u de ... volgende zelfstudie over IoT Central REST en selecteert u Bewerken. Selecteer vervolgens Variabelen. Veel van de variabelen worden automatisch ingesteld wanneer u de API-aanroepen uitvoert of vooraf ingestelde waarden hebben.

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 drie autorisatietypen:

Een bearer-token dat toegang toekent tot https://management.azure.com. U gebruikt dit Bearer-token wanneer u een IoT Central-toepassing maakt en verwijdert. Een IoT Central-toepassing is een Azure-resource.
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.
Beheer istrator- en operator-API-tokens die toegang verlenen tot mogelijkheden in uw IoT Central-toepassing. U gebruikt deze tokens voor de meeste API-aanroepen in deze zelfstudie. Deze tokens autoriseren alleen toegang tot één specifieke IoT Central-toepassing.

Wijs waarden toe aan de volgende variabelen in de Postman-verzameling:

bearerToken: voer de volgende Azure CLI-opdrachten uit om een Bearer-token te genereren waarmee toegang wordt https://management.azure.comtoegestaan:
```
az login
az account get-access-token --resource https://management.azure.com
```
Tip

Mogelijk moet u ook worden uitgevoerd az login als u de Cloud Shell gebruikt.

Kopieer de accessToken waarde naar de kolom Huidige waarde voor bearerToken in de verzamelingsvariabelen.
bearerTokenApp: voer de volgende Azure CLI-opdrachten uit om een Bearer-token te genereren waarmee toegang wordt toegestaan https://apps.azureiotcentral.com:
```
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 .

Kopieer de accessToken waarde naar de kolom Huidige waarde voor bearerTokenApp in de verzamelingsvariabelen.
subscriptionId: uw abonnements-id is opgenomen in de uitvoer van de twee vorige opdrachten. Kopieer de subscription waarde naar de kolom Huidige waarde voor subscriptionId in de verzamelingsvariabelen.

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

Sla de wijzigingen in de Postman-verzameling op.

Notitie

Bearer-tokens verlopen na een uur.

Een app maken

Gebruik de besturingsvlakaanvragen om IoT Central-toepassingen te maken en te beheren. Gebruik de volgende PUT-aanvraag om de toepassing te maken die u in deze zelfstudie gebruikt. De aanvraag maakt gebruik van een bearer-token om een willekeurige toepassingsnaam te autoriseren en te genereren.

Open in Postman de zelfstudieverzameling ioT Central REST en selecteer de aanvraag Een IoT Central-toepassing maken.
Selecteer Verzenden.
Controleer of de aanvraag is geslaagd. Als dit mislukt, controleert u of u de waarden van de bearerToken - en subscriptionId-variabele hebt ingevoerd in de Postman-verzameling.
Selecteer Visualiseren om de URL van uw nieuwe IoT Central-toepassing te zien. Noteer deze URL. U hebt deze later in deze zelfstudie nodig.

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

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:

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de aanvraag Een operatortoken maken.
Selecteer Verzenden.
Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de aanvraag Een beheertoken maken.
Selecteer Verzenden.

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

Notitie

Met een script in Postman worden deze API-tokens automatisch toegevoegd aan de lijst met verzamelingsvariabelen voor u.

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:

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de aanvraag Een apparaat toevoegen.
Selecteer Verzenden. In het antwoord ziet u dat het apparaat niet is ingericht.
Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de aanvraag apparaatreferenties ophalen.
Selecteer Verzenden.
Op het tabblad Visualiseren ziet u de waarden van het id-bereik en de primaire sleutel die het apparaat nodig heeft om verbinding te kunnen maken.

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 Apparaten > mijn telefoon-app > Verbinding maken > QR-code. Houd deze pagina open totdat het apparaat is verbonden.

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

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:

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de aanvraag Een apparaat ophalen.
Selecteer Verzenden. In het antwoord ziet u dat het apparaat nu is ingericht. IoT Central heeft ook een apparaatsjabloon toegewezen aan het apparaat op basis van de model-id die door het apparaat wordt verzonden.

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

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de aanvraag voor apparaatsjablonen weergeven.
Selecteer Verzenden.

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:

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de queryaanvraag uitvoeren .
Selecteer Verzenden.

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:

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de eigenschappen ophalen uit een onderdeelaanvraag .
Selecteer Verzenden.

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:

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de opdrachtaanvraag Aanroepen.
Selecteer Verzenden.

Telemetrie exporteren

U kunt de REST API gebruiken om uw IoT Central-toepassing te configureren en te beheren. In de volgende stappen ziet u hoe u gegevensexport configureert om telemetriewaarden naar een webhook te verzenden. Ter vereenvoudiging van de installatie gebruikt dit artikel een RequestBin-webhook als bestemming. RequestBin is een niet-Microsoft-service.

Uw testeindpunt maken voor het doel van de gegevensexport:

Navigeer naar RequestBin.
Selecteer Een RequestBin maken.
Meld u aan met een van de beschikbare methoden.
Kopieer de URL van uw RequestBin-eindpunt.
Open in Postman de ioT Central REST-zelfstudieverzameling en navigeer naar de verzamelingsvariabelen.
Plak de URL van uw RequestBin-eindpunt in de kolom Huidige waarde voor webHookURL in de verzamelingsvariabelen.
De wijzigingen opslaan.

De exportbestemming configureren in uw IoT Central-toepassing met behulp van de REST API:

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de aanvraag Een webhook-exportbestemming maken.
Selecteer Verzenden.

De exportdefinitie configureren in uw IoT Central-toepassing met behulp van de REST API:

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de aanvraag voor het maken van een telemetrie-exportdefinitie .
Selecteer Verzenden. U ziet dat de status niet is gestart.

Het kan enkele minuten duren voordat de export is gestart. De status van de export controleren met behulp van de REST API:

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de export op id-aanvraag ophalen.
Selecteer Verzenden. Wanneer de status in orde is, verzendt IoT Central telemetrie naar uw webhook.

De app op uw smartphone verzendt geen telemetrie, tenzij het scherm is ingeschakeld en de IoT Plug en Play-app zichtbaar is.

Wanneer uw smartphone-app telemetrie verzendt, gaat u naar uw RequestBin om de geëxporteerde telemetrie weer te geven.

Resources opschonen

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

Open in Postman de ioT Central REST-zelfstudieverzameling en selecteer de aanvraag Een IoT Central-toepassing verwijderen.
Selecteer Verzenden.

Tip

Deze aanvraag maakt gebruik van een Bearer-token dat u aan het begin van de zelfstudie hebt gegenereerd. Bearer-tokens verlopen na uur. Mogelijk moet u een nieuw Bearer-token genereren waarmee toegang wordt toegestaan https://apps.azureiotcentral.com.

Volgende stappen

Als u liever wilt doorgaan met de set zelfstudies over IoT Central en meer wilt leren over het bouwen van een IoT Central-oplossing, raadpleegt u:

Een gateway-apparaatsjabloon maken