Schemalägga jobb på flera enheter

  • Artikel

Azure IoT Hub möjliggör ett antal byggstenar, till exempel egenskaper för enhetstvillingar, taggar och direktmetoder. Vanligtvis gör serverdelsappar det möjligt för enhetsadministratörer och operatörer att uppdatera och interagera med IoT-enheter samtidigt och vid en schemalagd tidpunkt. Jobb kör uppdateringar av enhetstvillingar och direkta metoder 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 vid en tidpunkt som inte skulle störa byggnadens drift.

Anteckning

Funktionerna som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om nivåerna basic och standard/kostnadsfri IoT Hub finns i Välja rätt IoT Hub nivå för din lösning.

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

  • Uppdatera önskade egenskaper
  • Uppdatera taggar
  • Anropa direktmetoder

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 förloppet för ett jobb som körs via en tjänstinriktad URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Om du vill uppdatera statusen för jobb som körs när ett jobb har initierats kör du en jobbfråga. Det finns ingen explicit rensning av jobbhistoriken, men de har ett TTL-värde på 30 dagar. 

Anteckning

När du initierar ett jobb kan egenskapsnamn och värden endast innehålla alfanumeriskt utskrivbart US-ASCII, förutom något i följande uppsättning: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Anteckning

Fältet jobId får innehålla högst 64 tecken och får bara innehålla US-ASCII-bokstäver, siffror och bindestreck (-).

Jobb för att köra direktmetoder

Följande kodfragment visar information om HTTPS 1.1-begäran för att köra en direktmetod på en uppsättning enheter 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": "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 Frågespråk beskriver IoT Hub frågespråk i 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 egenskaper för enhetstvillingar

Följande kodfragment visar information om HTTPS 1.1-begäran 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>
}

Anteckning

Egenskapen updateTwin kräver en giltig etag-matchning. till exempel etag="*".

Följande kodfragment visar begäran och svar för ett jobb som schemalagts för att uppdatera egenskaper för enhetstvillingar för test-device 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 information om HTTPS 1.1-begäran 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 IoT Hub frågespråk för enhetstvillingar, jobb och meddelanderoutning.

Egenskaper för jobb

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

Egenskap Beskrivning
jobId Programmets ID har angetts för jobbet.
Starttime Programmet angav starttid (ISO-8601) för jobbet.
Endtime IoT Hub angivet datum (ISO-8601) för när jobbet slutfördes. Gäller endast när jobbet har nått tillståndet "slutfört".
typ Typer av jobb:
scheduleUpdateTwin: Ett jobb som används för att uppdatera en uppsättning önskade egenskaper eller taggar.
scheduleDeviceMethod: Ett jobb som används för att anropa en enhetsmetod på en uppsättning enhetstvillingar.
Status Jobbets aktuella tillstånd. Möjliga värden för status:
väntande: Schemalagd och väntar på att hämtas av jobbtjänsten.
schemalagd: Schemalagd för en tid i framtiden.
körs: För närvarande aktivt jobb.
avbrutet: Jobbet har avbrutits.
misslyckades: Jobbet misslyckades.
slutförd: Jobbet har slutförts.
deviceJobStatistics Statistik om jobbets körning.
deviceJobStatistics-egenskaper :
deviceJobStatistics.deviceCount: Antal enheter i jobbet.
deviceJobStatistics.failedCount: Antalet enheter där jobbet misslyckades.
deviceJobStatistics.succeededCount: Antalet enheter där jobbet lyckades.
deviceJobStatistics.runningCount: Antalet enheter som för närvarande kör jobbet.
deviceJobStatistics.pendingCount: Antalet enheter som väntar på att köra jobbet.

Ytterligare referensmaterial

Andra referensämnen i IoT Hub utvecklarguiden är:

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: