Taken op meerdere apparaten plannen

  • Artikel

Azure IoT Hub maakt een aantal bouwstenen mogelijk, zoals eigenschappen van apparaatdubbels 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 ermee te communiceren. Taken voeren updates van apparaatdubbels uit en leiden methoden op een gepland tijdstip uit op een set apparaten. 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 werking van het gebouw niet zou verstoren.

Notitie

De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie Choose the right IoT Hub tier for your solution (De juiste IoT Hub laag voor uw oplossing kiezen) voor meer informatie over de lagen Basic en Standard/free IoT Hub.

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 taak

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 de voortgang van een uitgevoerde taak opvragen via een servicegerichte URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Als u de status van actieve taken wilt vernieuwen zodra een taak is gestart, voert u een taakquery uit. Er is geen expliciete opschoning van de taakgeschiedenis, maar ze hebben een TTL van 30 dagen. 

Notitie

Wanneer u een taak start, kunnen eigenschapsnamen en -waarden alleen us-ASCII-afdrukbare alfanumeriek bevatten, met uitzondering van waarden in de volgende set: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Notitie

Het jobId veld moet maximaal 64 tekens bevatten en mag alleen US-ASCII-letters, cijfers en het streepje (-) bevatten.

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 ook op één apparaat-id of in een lijst met apparaat-id's staan, zoals wordt weergegeven in de volgende voorbeelden:

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

IoT Hub Querytaal bevat meer informatie over IoT Hub querytaal.

Het volgende codefragment toont 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 apparaatdubbels

In het volgende fragment ziet u de HTTPS 1.1-aanvraagdetails voor het bijwerken van eigenschappen van apparaatdubbels 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": "scheduleUpdateTwin",
    "updateTwin": <patch>                 // Valid JSON object
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

Notitie

Voor de eigenschap updateTwin is een geldige etag-overeenkomst vereist; bijvoorbeeld etag="*".

In het volgende codefragment ziet u de aanvraag en het antwoord voor een taak die is gepland om eigenschappen van apparaatdubbels bij te werken 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"}

Query's uitvoeren op de voortgang van taken

In het volgende fragment ziet u de HTTPS 1.1-aanvraagdetails voor het uitvoeren van query's op taken:

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 continuationToken wordt opgegeven vanuit het antwoord.

U kunt de taakuitvoeringsstatus op elk apparaat opvragen 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.

Eigenschap Beschrijving
jobId De toepassing heeft de id voor de taak opgegeven.
Starttime De toepassing heeft de begintijd (ISO-8601) voor de taak opgegeven.
Eindtijd IoT Hub opgegeven datum (ISO-8601) waarop de taak is voltooid. Alleen geldig nadat de taak de status 'voltooid' heeft bereikt.
type Typen taken:
scheduleUpdateTwin: een taak die wordt gebruikt om een set gewenste eigenschappen of tags bij te werken.
scheduleDeviceMethod: een taak die wordt gebruikt om een apparaatmethode aan te roepen op een set apparaatdubbels.
status Huidige status van de taak. Mogelijke waarden voor status:
in behandeling: gepland en wachtend om te worden opgehaald door de taakservice.
gepland: gepland voor een tijdstip in de toekomst.
wordt uitgevoerd: Momenteel actieve taak.
geannuleerd: taak is geannuleerd.
mislukt: taak is mislukt.
voltooid: taak is voltooid.
deviceJobStatistics Statistieken over de uitvoering van de taak.
eigenschappen van deviceJobStatistics :
deviceJobStatistics.deviceCount: aantal apparaten in de taak.
deviceJobStatistics.failedCount: het aantal apparaten waarop de taak is mislukt.
deviceJobStatistics.succeededCount: het aantal apparaten waarop de taak is geslaagd.
deviceJobStatistics.runningCount: het aantal apparaten waarop de taak momenteel wordt uitgevoerd.
deviceJobStatistics.pendingCount: het aantal apparaten dat in behandeling is om de taak uit te voeren.

Aanvullend referentiemateriaal

Andere naslagonderwerpen in de IoT Hub ontwikkelaarshandleiding zijn:

Volgende stappen

Zie de volgende IoT Hub zelfstudie om enkele van de concepten uit te proberen die in dit artikel worden beschreven: