Pianificare processi in più dispositivi
L'hub IoT di Azure abilita un numero di blocchi predefiniti, ad esempio tag e proprietà di dispositivi gemelli e metodi diretti. In genere, le app back-end consentono agli amministratori dei dispositivi e agli operatori di aggiornare i dispositivi IoT in blocco e a un'ora pianificata e di interagirvi. I processi eseguono l'aggiornamento di dispositivi gemelli e metodi diretti rispetto a un set di dispositivi a un'ora pianificata. Ad esempio, un operatore usa un'app back-end avviata e tiene traccia di un processo per riavviare un set di dispositivi al terzo piano dell'edificio 43 in un orario opportuno per non interrompere le attività dell'edificio.
Nota
Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT standard e standard, vedere Scegliere il livello di hub IoT appropriato per la soluzione.
È consigliabile usare i processi quando è necessario pianificare e tenere traccia dell'avanzamento di una qualsiasi delle attività seguenti in un set di dispositivi:
- Aggiornare le proprietà desiderate
- Aggiornare i tag
- Richiamare metodi diretti
Ciclo di vita dei processi
I processi vengono avviati dal back-end della soluzione e mantenuti dall'hub IoT. È possibile avviare un processo tramite un URI del servizio (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) ed eseguire query riguardo allo stato di avanzamento in un processo in esecuzione tramite un URI del servizio (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Per aggiornare lo stato dei processi in esecuzione dopo l'avvio, eseguire query sui processi. Non esiste alcuna eliminazione esplicita della cronologia dei processi, ma hanno un TTL di 30 giorni.
Nota
Quando si avvia un processo, i valori e i nomi di proprietà possono contenere solo caratteri alfanumerici US-ASCII stampabili, ad eccezione dei seguenti: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT
Nota
Il jobId campo deve avere un massimo di 64 caratteri e può contenere solo lettere, numeri e trattini- () US-ASCII.
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 tramite 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 ID dispositivo singolo o in un elenco di ID dispositivo, come illustrato negli esempi seguenti:
"queryCondition" = "deviceId = 'MyDevice1'"
"queryCondition" = "deviceId IN ['MyDevice1','MyDevice2']"
"queryCondition" = "deviceId IN ['MyDevice1']"
Linguaggio di query dell'hub IoT illustra il linguaggio di query dell'hub IoT in maggiore dettaglio.
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
Nel frammento di codice seguente sono riportati i dettagli della richiesta HTTPS 1.1 per l'aggiornamento delle proprietà dei dispositivi gemelli tramite 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>
}
Nota
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 il dispositivo di test 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 sull'avanzamento dei processi
Nel frammento di codice seguente sono riportati i dettagli della richiesta HTTPS 1.1 per l'esecuzione di query sui 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 risposta fornisce continuationToken.
È possibile eseguire query sullo stato di esecuzione del processo in ogni dispositivo usando il linguaggio di query hub IoT per dispositivi gemelli, processi e routing dei messaggi.
Proprietà dei processi
Di seguito è riportato un elenco di proprietà e corrispondenti descrizioni che è possibile usare quando si eseguono query sui processi o sui relativi risultati.
| Proprietà | Descrizione |
|---|---|
| jobId | ID fornito dall'applicazione per il processo. |
| startTime | Ora di inizio fornita dall'applicazione (ISO 8601) per il processo. |
| endTime | Data fornita dall'hub IoT (ISO 8601) per il completamento del processo. È valida solo quando il processo raggiunge lo stato di completamento. |
| type | Tipi di processi: |
| scheduleUpdateTwin: processo usato per aggiornare un set di proprietà o tag desiderati. | |
| scheduleDeviceMethod: processo usato per richiamare un metodo di dispositivo in un set di dispositivi gemelli. | |
| Stato | Stato corrente del processo. Valori possibili per lo stato: |
| pending: processo pianificato e in attesa del prelievo da parte del servizio del 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 eseguire il processo. |
Materiale di riferimento
Di seguito sono indicati altri argomenti di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:
Endpoint dell'hub IoT illustra i diversi endpoint esposti da ogni hub IoT per operazioni della fase di esecuzione e di gestione.
Quote e limitazioni descrive le quote applicabili al servizio Hub IoT e il comportamento di limitazione previsto quando si usa il servizio.
Azure IoT SDK per dispositivi e servizi elenca gli SDK nei diversi linguaggi che è possibile usare quando si sviluppano app per dispositivi e servizi che interagiscono con l'hub IoT.
Linguaggio di query dell'hub IoT per dispositivi gemelli, processi e routing di messaggi descrive il linguaggio di query di hub IoT. Usare questo linguaggio di query per recuperare dall'hub IoT informazioni sui dispositivi gemelli e sui processi.
Supporto di MQTT nell'hub IoT offre altre informazioni sul supporto dell'hub IoT per il protocollo MQTT.
Passaggi successivi
Per provare alcuni dei concetti descritti in questo articolo, vedere l'esercitazione sull'hub IoT seguente: