Verstehen und Aufrufen direkter Methoden von IoT Hub

  • Artikel

IoT Hub gibt Ihnen die Möglichkeit, direkte Methoden auf Geräten von der Cloud aus aufzurufen. Direkte Methoden stellen eine Anforderung-Antwort-Interaktion mit einem Gerät dar, die einem HTTP-Aufruf darin ähnelt, dass sie unverzüglich (nach einem vom Benutzer angegebenen Timeout) zu einem Erfolg oder Fehler führt. Dieser Ansatz eignet sich für Szenarien, in denen die Vorgehensweise bei sofortigen Aktionen unterschiedlich ist, je nachdem, ob das Gerät reagieren konnte oder nicht.

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.

Jedes Gerätemethode hat ein einzelnes Gerät als Ziel. Aufträge auf mehreren Geräten planen bietet eine Möglichkeit zum Aufrufen von direkten Methoden auf mehreren Geräten und zum Planen von Methodenaufrufen für nicht verbundene Geräte.

Jeder Benutzer mit der Berichtigung Dienstverbindung für IoT Hub kann eine Methode auf einem Gerät aufrufen.

Direkte Methoden entsprechen einem Anforderung/Antwort-Schema und sind für Kommunikation bestimmt, die sofortige Bestätigung ihres Ergebnisses erfordert. Ein Beispiel hierfür ist die interaktive Steuerung des Geräts, wie das Einschalten eines Lüfters.

Falls Sie weitere Informationen dazu benötigen, was die Verwendung von gewünschten Eigenschaften, direkten Methoden oder C2D-Nachrichten betrifft, hilft Ihnen der Leitfaden zur C2D-Kommunikation weiter.

Methodenlebenszyklus

Direkte Methoden werden auf dem Gerät implementiert und können für eine ordnungsgemäße Instanziierung null oder mehr Eingaben in der Methodennutzlast erfordern. Sie rufen eine direkte Methode über einen dienstseitigen URI ({iot hub}/twins/{device id}/methods/) auf. Ein Gerät empfängt direkte Methoden über ein gerätespezifisches MQTT-Thema ($iothub/methods/POST/{method name}/) oder über AMQP-Links (die Anwendungseigenschaften IoThub-methodname und IoThub-status).

Hinweis

Wenn Sie eine direkte Methode auf einem Gerät aufrufen, können Eigenschaftennamen und -werte nur druckbare alphanumerische US-ASCII-Zeichen mit Ausnahme der folgenden enthalten: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

Direkte Methoden sind synchron und werden nach dem Zeitlimit (Standardwert: 30 Sekunden, einstellbar zwischen 5 und 300 Sekunden). Direkte Methoden sind hilfreich bei interaktiven Szenarios, in denen ein Gerät genau dann agieren soll, wenn es online ist und Befehle empfängt. Beispiel: Einschalten von Beleuchtung über ein Telefon. In diesen Szenarios soll der Erfolg oder Misserfolg unmittelbar erkennbar sein, damit der Clouddienst so schnell wie möglich auf das Ergebnis reagieren kann. Das Gerät kann einen Nachrichtentext als Ergebnis der Methode zurückgeben, dies ist für die Methode aber nicht erforderlich. Es gibt keine Garantie für die Sortierung oder eine Parallelitätssemantik für Methodenaufrufe.

Direkte Methoden erfolgen von der Cloudseite nur über HTTPS und von der Geräteseite über MQTT, AMQP, MQTT über WebSockets oder AMQP über WebSockets.

Die Nutzlast für Methodenanforderungen und -antworten ist ein JSON-Dokument mit bis zu 128 KB.

Aufrufen einer direkten Methode aus einer Back-End-App

Wenn Sie eine direkte Methode aus einer Back-End-App aufrufen möchten, verwenden Sie die REST-API Gerätemethode aufrufen oder deren Entsprechung in einem der IoT Hub Dienst-SDKs.

Methodenaufruf

Direkte Methodenaufrufe auf einem Gerät sind HTTPS-Aufrufe, die aus den folgenden Elementen bestehen:

  • Der spezifischen Anforderungs-URI für das Gerät zusammen mit der API-Version:

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

  • Die POST-Methode

  • Headern mit der Autorisierung, dem Inhaltstyp und der Inhaltscodierung.

  • Einen transparenten JSON-Haupttext im folgenden Format:

    {
    "connectTimeoutInSeconds": 200,
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

Der als responseTimeoutInSeconds in der Anforderung angegebene Wert ist die Zeitspanne, die der IoT Hub-Dienst auf den Abschluss der Ausführung einer direkten Methode auf einem Gerät warten muss. Legen Sie diesen Timeoutwert mindestens auf die erwartete Ausführungszeit einer direkten Methode durch ein Gerät fest. Wenn Sie keinen Timeoutwert angeben, wird der Standardwert von 30 Sekunden verwendet. Die Mindest- und Höchstwerte für responseTimeoutInSeconds betragen 5 bzw. 300 Sekunden.

Der als connectTimeoutInSeconds in der Anforderung angegebene Wert ist die Zeitspanne nach dem Aufrufen einer direkten Methode, die der IoT Hub-Dienst darauf warten muss, dass ein getrenntes Gerät online geschaltet wird. Der Standardwert ist 0 (Null). Das bedeutet, dass Geräte beim Aufrufen einer direkten Methode bereits online sein müssen. Der Höchstwert für connectTimeoutInSeconds beträgt 300 Sekunden.

Beispiel

In diesem Beispiel können Sie eine Anforderung zum Aufrufen einer direkten Methode auf einem IoT-Gerät, das bei einem Azure IoT-Hub registriert wurde, auf sichere Weise initiieren.

Verwenden Sie zuerst die Microsoft Azure IoT-Erweiterung für Azure CLI, um eine SharedAccessSignature zu erstellen.

az iot hub generate-sas-token -n <iothubName> --du <duration>

Ersetzen Sie als Nächstes den Authorization-Header durch Ihre neu generierte SharedAccessSignature, und ändern Sie dann die Parameter iothubName, deviceId, methodName und payload so, dass Sie Ihrer Implementierung im curl-Beispielbefehl unten entsprechen.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

Führen Sie den geänderten Befehl aus, um die angegebene direkte Methode aufzurufen. Bei erfolgreichen Anforderungen wird der HTTP-Statuscode „200“ zurückgegeben.

Hinweis

Im vorstehenden Beispiel wird das Aufrufen einer direkten Methode auf einem Gerät gezeigt. Wenn Sie in einem IoT Edge-Modul eine direkte Methode aufrufen möchten, müssen Sie die URL-Anforderung wie unten gezeigt ändern:

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

Antwort

Die Back-End-App empfängt eine Antwort, die aus den folgenden Elementen besteht:

  • HTTP-Statuscode:

    • 200 gibt die erfolgreiche Ausführung der direkten Methode an.
    • 404 gibt an, dass entweder die Geräte-ID ungültig ist oder das Gerät nach dem Aufruf einer direkten Methode und connectTimeoutInSeconds danach nicht online war (die Grundursache können Sie mithilfe der zugehörigen Fehlermeldung ermitteln).
    • 504 gibt an, dass ein Gatewaytimeout ausgelöst wurde, da das Gerät nicht innerhalb von responseTimeoutInSeconds auf den Aufruf einer direkten Methode geantwortet hat.

  • Headern mit der Anforderungs-ID, dem Inhaltstyp und der Inhaltscodierung.

  • Einen JSON-Haupttext im folgenden Format:

    {
    "status" : 201,
    "payload" : {...}
}

    status und payload werden vom Gerät bereitgestellt und zum Antworten mit dem eigenen Statuscode und der Methodenantwort des Geräts verwendet.

Methodenaufruf für IoT Edge-Module

Das Aufrufen direkter Methoden für ein Modul wird von der REST-API Modulmethode aufrufen oder deren Entsprechung in einem der IoT Hub Dienst-SDKs unterstützt.

Die moduleId wird zusammen mit der deviceId im Anforderungs-URI (bei Verwendung der REST-API) oder als ein Parameter (bei Verwendung eines Dienst-SDKs) übergeben. Beispiel: https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. Der Anforderungstext und die Antwort ähneln direkten Methoden, die auf dem Gerät aufgerufen werden.

Behandeln einer direkten Methode auf einem Gerät

Auf einem IoT-Gerät können direkte Methoden über MQTT, AMQP oder eines dieser Protokolle über WebSockets empfangen werden. Die IoT Hub-Geräte-SDKs helfen Ihnen, direkte Methoden auf Geräten zu empfangen und darauf zu reagieren, ohne sich Gedanken über die zugrunde liegenden Protokolldetails machen zu müssen.

MQTT

Der nachstehende Abschnitt erläutert das MQTT-Protokoll. Weitere Informationen zur Verwendung des MQTT-Protokolls direkt zusammen mit IoT Hub finden Sie unter MQTT-Protokollunterstützung.

Methodenaufruf

Geräte empfangen direkte Methodenanforderungen zum MQTT-Thema: $iothub/methods/POST/{method name}/?$rid={request id}. Die request id wird jedoch von IoT Hub generiert und kann nicht vorab bekannt sein. Abonnieren Sie deshalb $iothub/methods/POST/#, und filtern Sie dann die übermittelten Nachrichten basierend auf den von Ihrem Gerät unterstützten Methodennamen. (Zum Antworten verwenden Sie die request id.)

Der vom Gerät empfangene Text weist das folgende Format auf:

{
    "input1": "someInput",
    "input2": "anotherInput"
}

Methodenanforderungen sind QoS 0.

Antwort

Das Gerät sendet Antworten an $iothub/methods/res/{status}/?$rid={request id}, wobei Folgendes gilt:

  • Die status-Eigenschaft ist der vom Gerät bereitgestellte Status der Methodenausführung.

  • Die $rid-Eigenschaft ist die Anforderungs-ID des von IoT Hub empfangenen Methodenaufrufs. Die Anforderungs-ID ist ein hexadezimal formatierter Wert.

Der Haupttext wird durch das Gerät festgelegt und kann jeden beliebigen Status aufweisen.

AMQP

Der nachstehende Abschnitt erläutert das AMQP-Protokoll. Weitere Informationen zur Verwendung des AMQP-Protokolls direkt zusammen mit IoT Hub finden Sie unter AMQP-Protokollunterstützung.

Methodenaufruf

Das Gerät empfängt Anforderungen direkter Methoden durch Erstellen eines Empfangslinks für die Adresse amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Die AMQP-Nachricht geht bei dem Empfangslink ein, der die Methodenanforderung darstellt. Sie enthält die folgenden Abschnitte:

  • Die Korrelations-ID-Eigenschaft mit einer Anforderungs-ID, die mit der entsprechenden Methodenantwort zurückgegeben werden soll

  • Eine Anwendungseigenschaft namens IoThub-methodname, die den Namen der aufgerufenen Methode enthält

  • Den AMQP-Nachrichtentext mit der Methodennutzlast im JSON-Format

Antwort

Das Gerät erstellt einen Sendelink, um die Methodenantwort an der Adresse amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound zurückzugeben.

Die Antwort der Methode wird für den Sendelink zurückgegeben und enthält Folgendes:

  • Die Korrelations-ID-Eigenschaft mit der Anforderungs-ID, die in der Anforderungsnachricht der Methode übergeben wurde

  • Eine Anwendungseigenschaft namens IoThub-status, die den vom Benutzer angegebenen Methodenstatus enthält

  • Den AMQP-Nachrichtentext mit der Methodenantwort im JSON-Format

Weiteres Referenzmaterial

Weitere Referenzthemen im IoT Hub-Entwicklerhandbuch:

Nächste Schritte

Nachdem Sie erfahren haben, wie Sie direkte Methoden verwenden, sind möglicherweise die folgenden Themen im IoT Hub-Entwicklerhandbuch für Sie interessant:

Wenn Sie einige der in diesem Artikel beschriebenen Konzepte ausprobieren möchten, ist möglicherweise das folgende IoT Hub-Tutorial für Sie interessant: