IoT Hub REST
De REST API's voor IoT Hub bieden programmatische toegang tot het apparaat, berichten en taakservices, evenals de resourceprovider, in IoT Hub. U hebt toegang tot berichtenservices vanuit een IoT-service die in Azure wordt uitgevoerd, of rechtstreeks via internet vanuit elke toepassing die een HTTPS-aanvraag kan verzenden en een HTTPS-antwoord kan ontvangen.
Service
- Gebruik deze API om de apparaattweeling IoT Hub beheren. U kunt dubbele eigenschappen van apparaten ophalen en bijwerken en directe methoden op apparaten aanroepen.
- Gebruik deze API's voor het beheren van apparaat-id's in het identiteitsregister van een IoT-hub.
- Gebruik deze API voor het beheren van taken in IoT Hub. U kunt een taak plannen, annuleren of krijgen.
Alle taakbewerkingen voldoen aan de HTTP/1.1-protocolspecificatie en elke bewerking retourneert een header die kan worden gebruikt om informatie over de x-ms-request-id aanvraag te verkrijgen. U dient ervoor te zorgen dat de aanvragen die naar deze resources worden verzonden, beveiligd zijn. Zie voor meer informatie IoT Hub Developer Guide – Security (Ontwikkelaarshandleiding : beveiliging) voor specifieke informatie over het maken van beveiligingstokens.
Apparaatberichten
Gebruik deze API's vanaf een apparaat om apparaat-naar-cloud-berichten te verzenden naar een IoT-hub en cloud-naar-apparaat-berichten te ontvangen van een IoT-hub. Alle taakbewerkingen voldoen aan de HTTP/1.1-protocolspecificatie. U dient ervoor te zorgen dat de aanvragen die naar deze resources worden verzonden, beveiligd zijn. Zie voor meer informatie IoT Hub Ontwikkelaarshandleiding - Beveiliging voor specifieke informatie over het maken van beveiligingstokens.
Resourceprovider
Gebruik deze API's om de implementatie van uw IoT Hub beheren. Zie Azure REST API Reference voor meer informatie over het beveiligen REST API aanvragen.
Algemene parameters en headers
De volgende informatie is gebruikelijk voor alle taken met betrekking tot IoT Hub:
Vervang {api-version} door '2018-06-30' in de URI.
Vervang {subscription-id} door uw abonnements-id in de URI.
Vervang {resourceGroupName} door de naam van de resourcegroep die uw IoT-hub bevat (of zal bevatten).
Vervang {IoTHubName} door de naam van uw IoT-hub.
Stel de Content-Type-header in op application/json.
Stel de Autorisatie-header in op een SAS-token dat is gemaakt zoals opgegeven in de sectie beveiligingstokens van Using IoT Hub security tokens.
De Etag-header wordt geretourneerd in alle aanvragen die zijn beperkt tot één apparaat-id, volgens RFC7232.
Voor alle PUT/PATCH-bewerkingen moeten de volgende headers worden opgegeven:
If-Match = [*|<etag from get>]DELETE-bewerkingen kunnen de volgende header bevatten:
If-Match = [*|<etag from get>]
Het gedrag voor ETags is hieronder te zien:
| PUT | Resource bestaat niet | Resource bestaat |
| If-Match = "" / niet aanwezig | 201 Gemaakt | 200 OK |
| If-Match = "*" | 412 Voorwaarde is mislukt | 200 OK |
| If-Match = "xyz" | 412 Voorwaarde is mislukt | 200 OK / 412 Voorwaarde is mislukt |
| If-None-Match = "*" | 201 Gemaakt | 412 Voorwaarde is mislukt |
| DELETE | Resource bestaat niet | Resource bestaat |
| If-Match = "" / niet aanwezig | 204 Geen inhoud | 200 OK |
| If-Match = "*" | 204 Geen inhoud | 200 OK |
| If-Match = "xyz" | 204 Geen inhoud | 200 OK / 412 Voorwaarde is mislukt |
Voor asynchrone aanroepen:
PUT reageert met 201 Gemaakt met Azure-AsyncOperation header voor alle bewerkingen die asynchroon zijn. Alle synchrone bewerkingen (updates) retourneren 200 OK.
DELETE retourneert 202 Geaccepteerd met Location en Retry-After headers, evenals Azure-AsyncOperation header voor resources die bestaan.
De locatieheader bevat de URL voor het resultaat van de bewerking
Retry-After header bevat het juiste interval voor opnieuw proberen in seconden
Azure-AsyncOperation header bevat de URL voor de resultaatstatus van de Async-bewerking
Na voltooiing genereert de GET naar de RESULTAAT-URL van de bewerking precies hetzelfde resultaat als wanneer de oorspronkelijke bewerking synchroon is voltooid