Condividi tramite

Pianificare processi dell'hub IoT di Azure in più dispositivi

L'hub IoT di Azure consente diversi blocchi predefiniti, ad esempio le proprietà e i tag dei dispositivi gemelli e imetodi diretti. In genere, le app back-end consentono agli amministratori e agli operatori dei dispositivi di aggiornare e interagire con i dispositivi IoT in blocco e in un orario pianificato. I processi eseguono gli aggiornamenti dei dispositivi gemelli e i metodi diretti su un set di dispositivi in un orario pianificato. Ad esempio, un operatore userà un'app back-end che avvia e tiene traccia di un processo per riavviare un set di dispositivi nell'edificio 43 e al piano 3 alla volta che non comporterebbe interruzioni delle operazioni dell'edificio.

Annotazioni

Le funzionalità descritte in questo articolo sono disponibili solo nel livello standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT di base e standard/gratuiti, vedere Scegliere il livello e le dimensioni dell'hub IoT corretti per la soluzione.

È consigliabile usare i processi quando è necessario pianificare e tenere traccia dello stato di avanzamento di una delle attività seguenti in un set di dispositivi:

  • Aggiornare le proprietà desiderate
  • Aggiornare i tag
  • Richiamare metodi diretti

Ciclo di vita del processo

I processi vengono avviati dal back-end della soluzione e gestiti dall'hub IoT. È possibile avviare un processo tramite un URI rivolto al servizio (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) e eseguire una query sullo stato di avanzamento di un processo in esecuzione tramite un URI rivolto al servizio (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Per aggiornare lo stato dei processi in esecuzione dopo l'avvio di un processo, eseguire una query di processo. Non esiste alcuna eliminazione esplicita della cronologia dei processi, ma hanno un TTL di 30 giorni. 

Annotazioni

Quando si avvia un processo, i nomi e i valori delle proprietà possono contenere solo US-ASCII alfanumerico stampabile, ad eccezione di qualsiasi nel set seguente: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Annotazioni

Il jobId campo deve contenere almeno 64 caratteri e può contenere solo US-ASCII lettere, numeri e il trattino (-).

Processi per eseguire metodi diretti

Il frammento di codice seguente mostra i dettagli della richiesta HTTPS 1.1 per l'esecuzione di un metodo diretto in un set di dispositivi usando un processo:

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

La condizione di query può anche trovarsi in un singolo ID dispositivo o in un elenco di ID dispositivo, come illustrato negli esempi seguenti:

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

Il linguaggio di query dell'hub IoT illustra in dettaglio il linguaggio di query dell'hub IoT.

Il frammento di codice seguente mostra la richiesta e la risposta per un processo pianificato per chiamare un metodo diretto denominato testMethod in tutti i dispositivi in 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"}

Processi per aggiornare le proprietà dei dispositivi gemelli

Il frammento di codice seguente mostra i dettagli della richiesta HTTPS 1.1 per aggiornare le proprietà dei dispositivi gemelli usando un processo:

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

Annotazioni

La proprietà updateTwin richiede una corrispondenza etag valida; ad esempio . etag="*"

Il frammento di codice seguente mostra la richiesta e la risposta per un processo pianificato per aggiornare le proprietà del dispositivo gemello per test-device in 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"}

Esecuzione di query sullo stato di avanzamento dei processi

Il frammento di codice seguente mostra i dettagli della richiesta HTTPS 1.1 per l'esecuzione di query per i processi:

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

La proprietà continuationToken viene fornita dalla risposta.

È possibile eseguire query sullo stato di esecuzione del processo in ogni dispositivo usando il linguaggio di query dell'hub IoT per dispositivi gemelli, processi e routing dei messaggi.

Proprietà dei processi

L'elenco seguente mostra le proprietà e le descrizioni corrispondenti, che possono essere usate durante l'esecuzione di query per i processi o i risultati del processo.

Proprietà Description
jobId ID fornito dall'applicazione per il processo.
startTime Ora di inizio fornita dall'applicazione (ISO-8601) per il processo.
endTime Data specificata dell'hub IoT (ISO-8601) per il completamento del processo. Valido solo dopo che il processo raggiunge lo stato "completato".
maxExecutionTimeInSeconds L'applicazione ha fornito il tempo totale massimo consentito dall'avvio del processo fino al completamento.
type Tipi di processi:
scheduleUpdateTwin: processo usato per aggiornare un set di proprietà o tag desiderati.
scheduleDeviceMethod: processo usato per richiamare un metodo del dispositivo in un set di dispositivi gemelli.
stato Stato corrente del processo. Valori possibili per lo stato:
in sospeso: pianificato e in attesa di essere prelevato dal servizio di processo.
pianificato: pianificato per un'ora in futuro.
running: processo attualmente attivo.
annullata: il processo è stato annullato.
failed: processo non riuscito.
completato: il processo è stato completato.
deviceJobStatistics Statistiche sull'esecuzione del processo.
proprietà deviceJobStatistics :
deviceJobStatistics.deviceCount: numero di dispositivi nel processo.
deviceJobStatistics.failedCount: numero di dispositivi in cui il processo non è riuscito.
deviceJobStatistics.succeededCount: numero di dispositivi in cui il processo è riuscito.
deviceJobStatistics.runningCount: numero di dispositivi che attualmente eseguono il processo.
deviceJobStatistics.pendingCount: numero di dispositivi in sospeso per l'esecuzione del processo.

Materiale di riferimento aggiuntivo

Altri argomenti di riferimento nella guida per sviluppatori dell'hub IoT includono:

Passaggi successivi

Per provare alcuni dei concetti descritti in questo articolo, vedere l'esercitazione seguente sull'hub IoT:

  • Last updated on