IoT Hub REST

  • Artikel

Die REST-APIs für IoT Hub bieten programmgesteuerten Zugriff auf das Gerät, die Nachrichten- und Auftragsdienste sowie den Ressourcenanbieter in IoT Hub. Sie können aus einem IoT-Dienst, der in Azure ausgeführt wird, auf Messagingdienste zugreifen. Der Zugriff kann auch direkt über das Internet aus einer beliebigen Anwendung erfolgen, die eine HTTPS-Anforderung senden und eine HTTPS-Antwort empfangen kann.

Dienst

  • Verwenden Sie diese API, um IoT Hub Gerätezwille zu verwalten. Sie können Gerätezwillungseigenschaften abrufen und aktualisieren und direkte Methoden auf Geräten aufrufen.
  • Verwenden Sie diese APIs, um Geräteidentitäten in der Identitätsregistrierung eines IoT Hubs zu verwalten.
  • Verwenden Sie diese API, um Aufträge in IoT Hub zu verwalten. Sie können einen Auftrag planen, abbrechen oder erhalten.

Alle Vorgangsvorgänge entsprechen der HTTP/1.1-Protokollspezifikation, und jeder Vorgang gibt einen x-ms-request-id Header zurück, der zum Abrufen von Informationen über die Anforderung verwendet werden kann. Sie müssen sicherstellen, dass Anforderungen, die an diese Ressourcen gesendet werden, sicher sind. Weitere Informationen zum Erstellen von Sicherheitstoken finden Sie unter IoT Hub Entwicklerhandbuch – Sicherheit.

Gerätemessaging

Verwenden Sie diese APIs von einem Gerät, um Device-to-Cloud-Nachrichten an einen IoT Hub zu senden und Cloud-zu-Gerät-Nachrichten von einem IoT Hub zu empfangen. Alle Aufgabenvorgänge entsprechen der HTTP/1.1-Protokollspezifikation. Sie müssen sicherstellen, dass Anforderungen, die an diese Ressourcen gesendet werden, sicher sind. Weitere Informationen finden Sie unter IoT Hub Entwicklerhandbuch – Sicherheit, um spezifische Informationen zum Erstellen von Sicherheitstoken zu erhalten.

Ressourcenanbieter

Verwenden Sie diese APIs, um die Bereitstellung Ihrer IoT Hub-Ressourcen zu verwalten. Informationen zum Schützen dieser Anforderungen finden Sie in der Azure-REST-API-Referenz.

Allgemeine Parameter und Header

Die folgenden Informationen gelten für alle Aufgaben im Zusammenhang mit IoT Hub:

  • Ersetzen Sie {api-version} im URI durch "2018-06-30".

  • Ersetzen Sie im URI {subscription-id} durch Ihre Abonnement-ID.

  • Ersetzen Sie {resourceGroupName} durch den Ressourcengruppennamen, der Ihren IoT Hub enthält (oder enthalten wird).

  • Ersetzen Sie {IoTHubName} durch den Namen Ihres IoT-Hubs.

  • Legen Sie den Inhaltstyp auf „application/json“ fest.

  • Legen Sie den Autorisierungsheader auf ein SAS-Token fest, das wie im Abschnitt Sicherheitstoken unter Verwenden von IoT Hub Sicherheitstoken angegeben erstellt wurde.

  • Der Etag-Header wird in allen Anforderungen zurückgegeben, die auf eine einzelne Geräteidentität gemäß RFC7232 ausgerichtet sind.

  • Für alle PUT/PATCH-Vorgänge müssen die folgenden Header angegeben werden: If-Match = [*|<etag from get>]

  • DELETE-Vorgänge können den folgenden Header enthalten: If-Match = [*|<etag from get>]

Das Verhalten für ETags ist unten zu sehen:

PUT Ressource ist nicht vorhanden Ressource vorhanden
If-Match = "" / abwesend 201 – Erstellt 200 – OK
If-Match = "*" 412 Precondition Failed 200 – OK
If-Match = "xyz" 412 Precondition Failed 200 OK/Fehler bei 412 Vorbedingung
If-None-Match = "*" 201 – Erstellt 412 Precondition Failed
Delete Ressource ist nicht vorhanden Ressource vorhanden
If-Match = "" / abwesend 204 Kein Inhalt 200 – OK
If-Match = "*" 204 Kein Inhalt 200 – OK
If-Match = "xyz" 204 Kein Inhalt 200 OK/Fehler bei 412 Vorbedingung

Für asynchrone Aufrufe:

  • PUT antwortet mit 201 Created with Azure-AsyncOperation header for any operations that are asynchron. Alle synchronen Vorgänge (Updates) geben 200 OK zurück.

  • DELETE gibt 202 Accepted with Location and Retry-After headers sowie Azure-AsyncOperation header for resources that exists zurück.

  • Der Speicherortheader enthält die URL für das Vorgangsergebnis.

  • Retry-After-Header enthält das entsprechende Wiederholungsintervall in Sekunden.

  • Azure-AsyncOperation Header enthält die URL für das Ergebnis des Asynchronen Vorgangs status

  • Nach Abschluss generiert die GET to the operation result URL genau dasselbe Ergebnis, als ob der ursprüngliche Vorgang synchron abgeschlossen wäre.