Freigeben über

Verstehen und Aufrufen direkter Methoden von IoT Hub

Mit direkten IoT Hub-Methoden können Sie Remoteaufrufe auf Geräten aus der Cloud aufrufen. Direkte Methoden folgen einem Anforderungsantwortmuster und sind für Kommunikationen vorgesehen, die eine sofortige Bestätigung ihres Ergebnisses erfordern. Beispielsweise die interaktive Steuerung eines Geräts, z. B. das Aktivieren eines Lüfters. Diese Funktionalität ist nützlich für Szenarien, in denen sich der Verlauf der sofortigen Aktion unterscheidet, je nachdem, ob das Gerät reagieren konnte.

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den grundlegenden und standardmäßigen/kostenlosen IoT Hub-Ebenen finden Sie unter Auswählen der richtigen IoT Hub-Ebene und -Größe für Ihre Lösung.

Jede Gerätemethode zielt auf ein einzelnes Gerät ab. Wenn Sie direkte Methoden auf mehreren Geräten aufrufen oder Methoden für getrennte Geräte planen möchten, lesen Sie " Planen von Aufträgen auf mehreren Geräten".

Jeder Benutzer mit Dienstverbindungsberechtigungen auf IoT Hub kann eine Methode auf einem Gerät aufrufen.

Weitere Informationen finden Sie im Kommunikationsleitfaden für Cloud-zu-Gerät, wenn Sie unsicher sind, ob Sie gewünschte Eigenschaften, direkte Methoden oder Cloud-zu-Gerät-Nachrichten verwenden sollen.

Methodenlebenszyklus

Direkte Methoden werden auf dem Gerät implementiert und erfordern möglicherweise null oder mehr Eingaben in der Methodennutzlast, um ordnungsgemäß instanziieren zu können. Sie rufen eine direkte Methode über einen dienstorientierten 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 IoThub-methodname und IoThub-status Anwendungseigenschaften).

Hinweis

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

Direkte Methoden sind synchron und entweder erfolgreich oder schlagen nach dem Timeoutzeitraum fehl (Standard 30 Sekunden; zwischen 5 und 300 Sekunden festgelegt). Direkte Methoden sind in interaktiven Szenarien hilfreich, in denen ein Gerät reagieren soll, wenn und nur, wenn das Gerät online ist und Befehle empfängt. Aktivieren Sie z. B. ein Licht von einem Telefon. In diesen Szenarien möchten Sie einen sofortigen Erfolg oder Fehler sehen, damit der Clouddienst so schnell wie möglich auf das Ergebnis reagieren kann. Das Gerät gibt möglicherweise einen Nachrichtentext als Ergebnis der Methode zurück, ist aber nicht erforderlich. Es gibt keine Garantie für die Sortierung oder parallele Semantik bei Methodenaufrufen.

Direkte Methoden sind auf der Cloud-Seite nur über HTTPS verfügbar und auf der Geräteseite über MQTT, AMQP, MQTT über WebSockets oder AMQP über WebSockets.

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

Aufrufen einer direkten Methode aus einer Back-End-App

Um eine direkte Methode aus einer Back-End-App aufzurufen, verwenden Sie die Devices - Invoke Method REST-API oder dessen 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 Anforderungs-URI, der für das Gerät spezifisch ist, sowie die API-Version.

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

  • Die POST-Methode

  • Header , die die Autorisierung, den Inhaltstyp und die Inhaltscodierung enthalten.

  • Ein transparenter JSON-Textkörper im folgenden Format:

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

Der in der Anforderung angegebene responseTimeoutInSeconds Wert ist die Zeitspanne, die der IoT Hub-Dienst für den Abschluss einer direkten Methodenausführung auf einem Gerät erwarten muss. Legen Sie dieses Timeout auf mindestens so lange fest, wie die erwartete Ausführungszeit einer direkten Methode durch ein Gerät. Wenn kein Timeoutwert angegeben wird, wird der Standardwert von 30 Sekunden verwendet. Die Mindest- und Höchstwerte für responseTimeoutInSeconds sind 5 beziehungsweise 300 Sekunden.

Der in der Anforderung angegebene connectTimeoutInSeconds Wert ist die Zeitspanne, die beim Aufruf einer direkten Methode erforderlich ist, auf die der IoT Hub-Dienst warten muss, damit ein nicht verbundenes Gerät online ist. Der Standardwert ist 0, d. h., dass Geräte bereits online sein müssen, wenn eine direkte Methode aufgerufen wird. Der Maximalwert beträgt connectTimeoutInSeconds 300 Sekunden.

Beispiel

In diesem Beispiel wird eine Anforderung initiiert, um eine direkte Methode auf einem IoT-Gerät aufzurufen, das auf einem Azure IoT-Hub registriert ist.

Verwenden Sie zunächst die Microsoft Azure IoT-Erweiterung für Azure CLI , um ein SharedAccessSignature zu erstellen.

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

Ersetzen Sie als Nächstes den Autorisierungsheader durch Ihren neu generierten SharedAccessSignature. Ändern Sie dann die iothubName, deviceId, methodName und payload Parameter, um Ihre Implementierung im folgenden Beispielbefehl curl abzugleichen.

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. Erfolgreiche Anforderungen geben einen HTTP 200-Statuscode zurück.

Hinweis

Im vorherigen Beispiel wird das Aufrufen einer direkten Methode auf einem Gerät veranschaulicht. Wenn Sie eine direkte Methode in einem IoT Edge-Modul aufrufen möchten, ändern Sie die URL-Anforderung, um /modules/<moduleName> einzuschließen, wie im folgenden Beispiel gezeigt:

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 weist auf eine erfolgreiche Ausführung der direkten Methode hin;
    • 404 gibt an, dass entweder die Geräte-ID ungültig ist oder dass das Gerät bei der Ausführung einer direkten Methode und danach nicht online war (verwenden Sie die begleitende Fehlermeldung, um die Ursache zu verstehen);
    • 504 zeigt ein Gateway-Timeout an, das dadurch verursacht wird, dass das Gerät nicht innerhalb von responseTimeoutInSeconds auf einen direkten Methodenaufruf reagiert.

  • Header, die die Anforderungs-ID, den Inhaltstyp und die Inhaltscodierung enthalten.

  • Ein JSON-Textkörper im folgenden Format:

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

    Sowohl status als auch payload werden vom Gerät bereitgestellt und verwendet, um mit dem Statuscode des Geräts und der Methodenantwort zu antworten.

Methodenaufruf für IoT Edge-Module

Um eine direkte Methode für ein Modul aufzurufen, verwenden Sie die Modules - Invoke Method REST API oder dessen Entsprechung in einem der IoT Hub-Dienst-SDKs.

Die moduleId wird zusammen mit dem deviceId im Request-URI übergeben, wenn Sie die REST-API verwenden, oder als Parameter, wenn Sie ein Dienst-SDK nutzen. Beispiel: https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. Der Anforderungstext und die Antwort ähneln der 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 folgende Abschnitt unterliegt dem MQTT-Protokoll. Weitere Informationen zur direkten Verwendung des MQTT-Protokolls mit IoT Hub finden Sie unter Kommunizieren mit einem IoT-Hub mithilfe des MQTT-Protokolls.

Methodenaufruf

Geräte erhalten direkte Methodenanforderungen im MQTT-Thema: $iothub/methods/POST/{method name}/?$rid={request id}. Es kann jedoch nicht im Voraus bekannt sein, da IoT Hub sie generiert. Abonnieren Sie daher $iothub/methods/POST/# und filtern Sie dann die übermittelten Nachrichten basierend auf den von Ihrem Gerät unterstützten Methodennamen. (Sie verwenden die generierte request id zur Beantwortung.)

Der Textkörper, den das Gerät empfängt, 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:

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

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

Das Gerät legt den Status fest und kann jeden beliebigen Zustand annehmen.

AMQP

Der folgende Abschnitt unterliegt dem AMQP-Protokoll. Weitere Informationen zur direkten Verwendung des AMQP-Protokolls mit IoT Hub finden Sie unter "Kommunizieren mit Ihrem IoT-Hub mithilfe des AMQP-Protokolls".

Methodenaufruf

Das Gerät empfängt direkte Methodenanforderungen durch Erstellen eines Empfangslinks auf Adresse amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Die AMQP-Nachricht wird auf dem Empfangslink eingetroffen, der die Methodenanforderung darstellt. Sie enthält die folgenden Abschnitte:

  • Die Korrelations-ID-Eigenschaft, die eine Anforderungs-ID enthält, die mit der entsprechenden Methodenantwort zurückgegeben werden soll.

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

  • Der AMQP-Nachrichtentext, der die Methodennutzlast als JSON enthält.

Antwort

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

Die Antwort der Methode wird auf dem Sendelink zurückgegeben und ist wie folgt strukturiert:

  • Die Korrelations-ID-Eigenschaft, die die Anforderungs-ID enthält, die in der Anforderungsnachricht der Methode übergeben wird.

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

  • Der AMQP-Nachrichtentext, der die Methodenantwort als JSON enthält.

Nächste Schritte

Nachdem Sie nun wissen, wie Sie direkte Methoden verwenden können, sind Sie möglicherweise an den folgenden Artikeln des IoT Hub-Entwicklerhandbuchs interessiert:

  • Last updated on