Azure IoT Hub-taken plannen op meerdere apparaten

Azure IoT Hub maakt een aantal bouwstenen mogelijk, zoals eigenschappen van digitale tweelingen en tags, en directe methoden. Normaal gesproken stellen back-end-apps apparaatbeheerders en -operators in staat om IoT-apparaten bulksgewijs en op een gepland tijdstip bij te werken en te gebruiken. Taken voeren updates van digitale tweelingen van apparaten en directe methodes uit op een set apparaten op een gepland tijdstip. Een operator zou bijvoorbeeld een back-end-app gebruiken die een taak initieert en bijhoudt om een set apparaten in gebouw 43 en verdieping 3 opnieuw op te starten op een moment dat de bewerkingen van het gebouw niet verstoren.

Overweeg het gebruik van taken wanneer u de voortgang van een van de volgende activiteiten op een set apparaten wilt plannen en bijhouden:

• Gewenste eigenschappen bijwerken
• Tags bijwerken
• Directe methoden aanroepen

Levenscyclus van een baan

Taken worden gestart door de back-end van de oplossing en onderhouden door IoT Hub. U kunt een taak initiëren via een servicegerichte URI (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) en een query uitvoeren op de voortgang van een taak via een servicegerichte URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Als u de status van lopende taken wilt vernieuwen zodra een taak is gestart, voert u een query voor taken uit. Er is geen expliciete opschoning van de taakgeschiedenis, maar ze hebben een tijdslimiet (TTL) van 30 dagen. 

Taken voor het uitvoeren van directe methoden

In het volgende fragment ziet u de https 1.1-aanvraagdetails voor het uitvoeren van een directe methode op een set apparaten met behulp van een taak:

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

De queryvoorwaarde kan zich ook op één apparaat-id of in een lijst met apparaat-id's bevinden, zoals wordt weergegeven in de volgende voorbeelden:

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

IoT Hub Query Language behandelt de Querytaal van IoT Hub in meer detail.

In het volgende codefragment ziet u de aanvraag en het antwoord voor een taak die is gepland om een directe methode met de naam testMethod aan te roepen op alle apparaten op 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"}

Taken voor het bijwerken van eigenschappen van apparaat-tweelingen

In het volgende fragment ziet u de HTTPS 1.1-aanvraagdetails voor het bijwerken van eigenschappen van apparaat-tweelingen om een taak uit te voeren.

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

In het volgende fragment ziet u de aanvraag en het antwoord voor een taak die is gepland voor het bijwerken van apparaatdubbeleigenschappen voor testapparaat op 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"}

Queries uitvoeren naar voortgang van werkzaamheden

In het volgende fragment ziet u de details van de HTTPS 1.1-aanvraag voor het opvragen van banen.

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

Het vervolgtoken wordt meegegeven in het antwoord.

U kunt op elk apparaat een query uitvoeren op de uitvoeringsstatus van de taak met behulp van de IoT Hub-querytaal voor apparaatdubbels, taken en berichtroutering.

Eigenschappen van taken

De volgende lijst bevat de eigenschappen en bijbehorende beschrijvingen, die kunnen worden gebruikt bij het uitvoeren van query's op taken of taakresultaten.

Aanvullend referentiemateriaal

Andere naslagonderwerpen in de ontwikkelaarshandleiding voor IoT Hub zijn:

• IoT Hub-eindpunten beschrijven de verschillende eindpunten die elke IoT-hub beschikbaar maakt voor runtime- en beheerbewerkingen.

• Regulering en quota beschrijft de quota die van toepassing zijn op de IoT Hub-service en het reguleringsgedrag dat u kunt verwachten bij gebruik van de service.

• Azure IoT-apparaat- en service-SDK's bevat de verschillende taal-SDK's die u kunt gebruiken wanneer u zowel apparaat- als service-apps ontwikkelt die communiceren met IoT Hub.

• IoT Hub-querytaal voor apparaat tweelingen, taken en berichtroutering beschrijft de IoT Hub-querytaal. Gebruik deze querytaal om informatie op te halen uit IoT Hub over uw apparaatdubbels en -taken.

• IoT Hub MQTT-ondersteuning biedt meer informatie over IoT Hub-ondersteuning voor het MQTT-protocol.

Volgende stappen

Raadpleeg de volgende IoT Hub-zelfstudie om een aantal van de concepten uit te proberen die in dit artikel worden beschreven:

• Taken plannen en uitvoeren