Condividi tramite

Pianificare processi in più dispositivi

  • Articolo

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:

Passaggi successivi

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