Schemalägga Azure IoT Hub-jobb på flera enheter

Azure IoT Hub tillhandahåller ett antal byggstenar som enhetstvillingars egenskaper och taggar och direkta metoder. Vanligtvis gör serverdelsappar det möjligt för enhetsadministratörer och operatörer att uppdatera och interagera med IoT-enheter i grupp och vid en schemalagd tidpunkt. Uppdrag kör enhetstvillinguppdateringar och direktmetoder mot en uppsättning enheter vid en schemalagd tidpunkt. En operatör skulle till exempel använda en serverdelsapp som initierar och spårar ett jobb för att starta om en uppsättning enheter i byggnad 43 och våning 3 i taget som inte skulle störa byggnadens drift.

Överväg att använda jobb när du behöver schemalägga och spåra förloppet någon av följande aktiviteter på en uppsättning enheter:

• Uppdatera önskade egenskaper
• Uppdatera taggar
• Anropa direkta metoder

Jobblivscykel

Jobb initieras av lösningens serverdel och underhålls av IoT Hub. Du kan initiera ett jobb via en tjänstinriktad URI (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) och fråga efter status för ett körningsjobb via en serviceorienterad URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). För att uppdatera statusen för pågående jobb när ett jobb har startats, kör en sökning efter jobb. Det finns ingen explicit rensning av jobbhistoriken, men de har en TTL på 30 dagar. 

Jobb för att köra direkta metoder

Följande kodfragment visar information om en HTTPS 1.1-begäran för körningen av en direktmetod på en uppsättning enheter genom ett jobb.

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>
}

Frågevillkoret kan också finnas på ett enda enhets-ID eller i en lista över enhets-ID:n enligt följande exempel:

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

IoT Hub Query Language omfattar IoT Hub-frågespråket i ytterligare detalj.

Följande kodfragment visar begäran och svar för ett jobb som schemalagts för att anropa en direktmetod med namnet testMethod på alla enheter på contoso-hub-1:

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"}

Jobb för att uppdatera enhetstvillingars egenskaper

Följande kodfragment visar HTTPS 1.1-begärandeinformationen för uppdatering av egenskaper för enhetstvillingar med hjälp av ett jobb:

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>
}

Följande kodfragment visar begäran och svar för ett jobb som schemalagts för att uppdatera enhetstvillingens egenskaper för test-enhet på contoso-hub-1.

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"}

Fråga efter förlopp för jobb

Följande kodfragment visar HTTPS 1.1-begärandeinformationen för frågor om jobb:

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

continuationToken tillhandahålls från svaret.

Du kan fråga efter jobbets körningsstatus på varje enhet med hjälp av frågespråket IoT Hub för enhetstvillingar, jobb och meddelanderoutning

Jobbegenskaper

I följande lista visas egenskaper och motsvarande beskrivningar, som kan användas när du frågar efter jobb eller jobbresultat.

Ytterligare referensmaterial

Andra referensämnen i utvecklarguiden för IoT Hub är:

• IoT Hub-slutpunkter beskriver de olika slutpunkter som varje IoT-hubb exponerar för körnings- och hanteringsåtgärder.

• Begränsning och kvoter beskriver de kvoter som gäller för IoT Hub-tjänsten och det begränsningsbeteende som du kan förvänta dig när du använder tjänsten.

• Azure IoT-enhets- och tjänst-SDK:er visar de olika språk-SDK:er som du kan använda när du utvecklar både enhets- och tjänstappar som interagerar med IoT Hub.

• IoT Hub-frågespråk för enhetstvillingar, jobb och meddelanderoutning beskriver IoT Hub:s frågespråk. Använd det här frågespråket för att hämta information från IoT Hub om dina enhetstvillingar och jobb.

• IoT Hub MQTT-stöd ger mer information om IoT Hub-stöd för MQTT-protokollet.

Nästa steg

Om du vill prova några av de begrepp som beskrivs i den här artikeln kan du läsa följande IoT Hub-självstudie:

• Schemalägga och sända jobb