Schemalägga jobb på flera enheter
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
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 (-
).
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"}
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"}
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.
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. |
Andra referensämnen i IoT Hub utvecklarguiden ä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 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 innehåller mer information om IoT Hub stöd för MQTT-protokollet.
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: