IoT Hub REST

  • Artikel

De REST API's voor IoT Hub bieden programmatische toegang tot het apparaat, de 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 IoT Hub apparaatdubbels te beheren. U kunt eigenschappen van apparaatdubbels ophalen en bijwerken en directe methoden op apparaten aanroepen.
  • Gebruik deze API's om apparaatidentiteiten te beheren in het identiteitsregister van een IoT-hub.
  • Gebruik deze API om taken in IoT Hub te beheren. U kunt een baan plannen, annuleren of een baan krijgen.

Alle taakbewerkingen voldoen aan de HTTP/1.1-protocolspecificatie en elke bewerking retourneert een x-ms-request-id header die kan worden gebruikt om informatie over de aanvraag te verkrijgen. U dient ervoor te zorgen dat de aanvragen die naar deze resources worden verzonden, beveiligd zijn. Zie IoT Hub Developer Guide - Security (Handleiding voor ontwikkelaars: beveiliging) voor meer informatie over het maken van beveiligingstokens.

Apparaatberichten

Gebruik deze API's van 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 IoT Hub Developer Guide - Security voor specifieke informatie over het maken van beveiligingstokens voor meer informatie.

Resourceprovider

Gebruik deze API's om de implementatie van uw IoT Hub resources te beheren. Zie Naslaginformatie over Azure REST API voor informatie over het beveiligen van deze aanvragen.

Algemene parameters en headers

De volgende informatie is gemeenschappelijk 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 gaat bevatten).

  • Vervang {IoTHubName} door de naam van uw IoT-hub.

  • Stel de header Content-Type in op application/json.

  • Stel de autorisatieheader in op een SAS-token dat is gemaakt zoals opgegeven in de sectie beveiligingstokens van IoT Hub beveiligingstokens gebruiken.

  • De Etag-header wordt geretourneerd in alle aanvragen die zijn gericht op éé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>]

Hieronder ziet u het gedrag voor ETags:

PUT Resource bestaat niet Resource bestaat
If-Match = "" / afwezig 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 = "" / afwezig 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 asynchrone bewerkingen. Alle synchrone bewerkingen (updates) retourneren 200 OK.

  • DELETE retourneert 202 Geaccepteerd met locatie- en Retry-After-headers, evenals Azure-AsyncOperation koptekst voor bestaande resources.

  • Locatiekoptekst bevat URL voor het bewerkingsresultaat

  • Retry-After header bevat het juiste interval voor opnieuw proberen in seconden

  • Azure-AsyncOperation-header bevat URL voor de resultaatstatus van de Asynchrone bewerking

  • Na voltooiing genereert de GET naar de URL van het bewerkingsresultaat precies hetzelfde resultaat als wanneer de oorspronkelijke bewerking synchroon is voltooid