Planen Sie Azure IoT Hub Jobs auf mehreren Geräten

Azure IoT Hub ermöglicht viele Bausteine wie Geräte-Twin-Eigenschaften und Tags und direkte Methoden. Mit Back-End-Apps können Geräteadministratoren und -bediener in der Regel IoT-Geräte mithilfe eines Massenvorgangs und zu einem geplanten Zeitpunkt aktualisieren und mit ihnen interagieren. Aufträge führen Updates von Gerätezwillingen und direkten Methoden für eine Gruppe von Geräten zu einem geplanten Zeitpunkt aus. Beispielsweise würde ein Betreiber eine Back-End-App verwenden, die einen Auftrag initiiert und verfolgt, um eine Reihe von Geräten in Gebäude 43 und Stock 3 zu einem Zeitpunkt neu zu starten, die nicht störend für die Vorgänge des Gebäudes wären.

Erwägen Sie das Arbeiten mit Aufträgen, wenn Sie den Fortschritt der folgenden Aktivitäten für eine Gruppe von Geräten planen und nachverfolgen müssen:

• Aktualisieren gewünschter Eigenschaften
• Aktualisieren von Tags
• Aufrufen direkter Methoden

Auftragslebenszyklus

Aufträge werden vom Lösungs-Back-End eingeleitet und vom IoT Hub verwaltet. Sie können einen Auftrag über einen dienstseitigen URI (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) auslösen und den Fortschritt eines in der Ausführung befindlichen Auftrags über einen dienstseitigen URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12) abfragen. Um den Status der zurzeit ausgeführten Aufträge nach der Initiierung eines Auftrags zu aktualisieren, führen Sie eine Auftragsabfrage aus. Es gibt keine explizite Löschung der Historie von Jobs, aber sie haben eine TTL von 30 Tagen. 

Aufträge zum Ausführen direkter Methoden

Der folgende Ausschnitt enthält die HTTPS 1.1-Anforderungsdetails, um eine direkte Methode für eine Gruppe von Geräten mithilfe eines Auftrags auszuführen:

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "<methodName>",
        "payload": <payload>,
        "responseTimeoutInSeconds": methodTimeoutInSeconds
    },
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

Die Abfragebedingung kann auch wie unten dargestellt für eine einzelne Geräte-ID oder eine Liste mit Geräte-IDs gelten. Im Folgenden werden einige Beispiele vorgestellt:

"queryCondition" = "deviceId = 'MyDevice1'"
"queryCondition" = "deviceId IN ['MyDevice1','MyDevice2']"
"queryCondition" = "deviceId IN ['MyDevice1']"

Weitere Informationen zur IoT Hub-Abfragesprache finden Sie in der IoT Hub-Abfragesprache für Geräte- und Modul-Twins, Aufträge und Nachrichtenrouting.

Der folgende Codeschnipsel zeigt die Anforderung und Antwort für einen Auftrag, der zum Aufrufen einer direkten Methode namens „testMethod“ auf allen Geräten auf „contoso-hub-1“ geplant ist:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job01?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=68iv------------------------------------v8Hxalg%3D&se=1556849884&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
Content-Length: 317

{
    "jobId": "job01",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "testMethod",
        "payload": {},
        "responseTimeoutInSeconds": 30
    },
    "queryCondition": "*",
    "startTime": "2019-05-04T15:53:00.077Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 65
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 01:46:18 GMT

{"jobId":"job01","type":"scheduleDeviceMethod","status":"queued"}

Aufträge zum Aktualisieren von Gerätezwillingseigenschaften

Der folgende Codeschnipsel enthält die HTTPS 1.1-Anforderungsdetails, um die Gerätezwillingseigenschaften mithilfe eines Auftrags zu aktualisieren:

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleUpdateTwin",
    "updateTwin": <patch>                 // Valid JSON object
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

Der folgende Codeschnipsel zeigt die Anforderung und Antwort für einen Auftrag, der zum Aktualisieren der Gerätezwillingseigenschaften für „test-device“ auf „contoso-hub-1“ geplant wurde:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job02?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=BN0U-------------------------------------RuA%3D&se=1556925787&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
Content-Length: 339

{
    "jobId": "job02",
    "type": "scheduleUpdateTwin",
    "updateTwin": {
      "properties": {
        "desired": {
          "test1": "value1"
        }
      },
     "etag": "*"
     },
    "queryCondition": "deviceId = 'test-device'",
    "startTime": "2019-05-08T12:19:56.868Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 63
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 22:45:13 GMT

{"jobId":"job02","type":"scheduleUpdateTwin","status":"queued"}

Abfragen des Status von Aufträgen

Der folgende Ausschnitt enthält die HTTPS 1.1-Anforderungsdetails für das Abfragen von Aufträgen:

GET /jobs/v2/query?api-version=2021-04-12[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

Das „continuationToken“ wird aus der Antwort bereitgestellt.

Sie können den Auftragsausführungsstatus auf jedem Gerät mithilfe der IoT Hub-Abfragesprache für Geräte- und Modul-Twins, Aufträge und Nachrichtenrouting abfragen.

Eigenschaften von Aufträgen

Die folgende Liste enthält die Eigenschaften und entsprechenden Beschreibungen, die beim Abfragen von Aufträgen oder Auftragsergebnissen verwendet werden können.

Sonstiges Referenzmaterial

Weitere Referenzartikel im IoT Hub-Entwicklerhandbuch:

• Unter IoT Hub-Endpunkte werden die verschiedenen Endpunkte beschrieben, die jeder IoT Hub für Laufzeit- und Verwaltungsvorgänge verfügbar macht.

• IoT Hub-Kontingente und Drosselung beschreibt die Kontingente, die für den IoT Hub-Dienst gelten, sowie das erwartete Drosselungsverhalten bei der Nutzung des Dienstes.

• Azure IoT Hub-SDKs listet die verschiedenen Sprach-SDKs auf, die Sie verwenden können, wenn Sie Geräte- und Dienst-Apps entwickeln, die mit IoT Hub interagieren.

• Die IoT Hub-Abfragesprache für Geräte- und Modul-Zwillinge, Aufträge und Nachrichtenrouting beschreibt die IoT Hub-Abfragesprache. Verwenden Sie diese Abfragesprache, um aus IoT Hub Informationen zu Gerätezwillingen und Aufträgen abzurufen.

• Die Kommunikation mit einem IoT-Hub mit dem MQTT-Protokoll bietet weitere Informationen zur IoT Hub-Unterstützung für das MQTT-Protokoll.

Nächste Schritte

Informationen zu den in diesem Artikel beschriebenen Konzepten finden Sie im folgenden IoT Hub-Artikel:

• Zuverlässigkeit im Azure IoT Hub