Taken op meerdere apparaten plannen

Azure IoT Hub maakt een aantal bouwstenen mogelijk, zoals eigenschappen en tags van apparaattwee en directe methoden. Normaal gesproken kunnen apparaatbeheerders en operators met back-end-apps IoT-apparaten bulksgewijs en op een gepland tijdstip bijwerken en gebruiken. Met taken worden updates van apparaattwee en directe methoden op een gepland tijdstip uitgevoerd op een set apparaten. Een operator zou bijvoorbeeld een back-end-app gebruiken die een taak initieert en bij houdt om een set apparaten in gebouw 43 en verdieping 3 op een tijdstip opnieuw op te starten die niet verstorend zou zijn voor de bewerkingen van het gebouw.

Notitie

De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Raadpleeg How to choose the right IoT Hub tier (De juiste IoT Hub-prijscategorie kiezen) voor meer informatie over de Basic- en Standard/gratis-prijscategorieën van IoT Hub.

Overweeg het gebruik van taken wanneer u een van de volgende activiteiten op een set apparaten moet plannen en volgen:

  • Gewenste eigenschappen bijwerken
  • Tags bijwerken
  • Directe methoden aanroepen

Levenscyclus van de taak

Taken worden geïnitieerd door de back-end van de oplossing en onderhouden door IoT Hub. U kunt een taak initiëren via een service-gerichte URI ( ) en een query uitvoeren voor de voortgang van een uitvoerbare taak via een PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2018-06-30 service-gerichte URI ( GET https://<iot hub>/jobs/v2/<jobID?api-version=2018-06-30 ). Voer een taakquery uit om de status van het uitvoeren van taken te vernieuwen zodra een taak is gestart.

Notitie

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

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=2018-06-30

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

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

IoT Hub querytaal wordt IoT Hub querytaal uitgebreid behandeld.

In het volgende fragment ziet u de aanvraag en het antwoord voor een taak die is gepland voor het aanroepen van een directe methode met de naam testMethod op alle apparaten op contoso-hub-1:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job01?api-version=2018-06-30 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 apparaattwee

In het volgende fragment ziet u de HTTPS 1.1-aanvraagdetails voor het bijwerken van eigenschappen van apparaattwee met behulp van een taak:

PUT /jobs/v2/<jobId>?api-version=2018-06-30

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

De eigenschap updateTwin vereist een geldige etag-overeenkomst; bijvoorbeeld etag="*" .

In het volgende codefragment ziet u de aanvraag en het antwoord voor een taak die is gepland om de eigenschappen van de apparaattweeling bij te werken voor test-device op contoso-hub-1:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job02?api-version=2018-06-30 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 voortgang van taken

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

GET /jobs/v2/query?api-version=2018-06-30[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

Het continuationToken wordt geleverd vanuit het antwoord.

U kunt de uitvoeringsstatus van de taak op elk apparaat opvragen met behulp van de IoT Hub querytaal voor apparaattweelingen, taken en berichtroutering.

Eigenschappen van taken

De volgende lijst bevat de eigenschappen en bijbehorende beschrijvingen, die kunnen worden gebruikt bij het opvragen van taken of taakresultaten.

Eigenschap Beschrijving
jobId Door de toepassing opgegeven id voor de taak.
Starttime De toepassing heeft de begintijd (ISO-8601) voor de taak opgegeven.
Eindtijd IoT Hub opgegeven datum (ISO-8601) voor wanneer 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 voor een set apparaattweelingen.
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 tijd in de toekomst.
wordt uitgevoerd: momenteel actieve taak.
geannuleerd: de taak is geannuleerd.
mislukt: taak is mislukt.
voltooid: de taak is voltooid.
deviceJobStatistics Statistieken over de uitvoering van de taak.
eigenschappen deviceJobStatistics:
deviceJobStatistics.deviceCount: het aantal apparaten in de taak.
deviceJobStatistics.failedCount: aantal apparaten waarop de taak is mislukt.
deviceJobStatistics.succeededCount: aantal apparaten waarop de taak is geslaagd.
deviceJobStatistics.runningCount: het aantal apparaten met de taak.
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

Als u enkele concepten wilt uitproberen die in dit artikel worden beschreven, bekijkt u de volgende IoT Hub zelfstudie: