Pianificare processi in più dispositivi

Panoramica

Come descritto in articoli precedenti, l'hub IoT di Azure consente un numero di blocchi predefiniti (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 incapsulano l'esecuzione di aggiornamenti dei dispositivi gemelli e i metodi diretti rispetto a un set di dispositivi a un'ora pianificata. Ad esempio, un operatore userà un'app back-end avviata e terrà 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.

Quando usare le autorizzazioni

È consigliabile usare processi quando il back-end di una soluzione deve 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 ({iot hub}/jobs/v2/{device id}/methods/<jobID>?api-version=2016-11-14) ed eseguire query riguardo allo stato di avanzamento in un processo in esecuzione tramite un URI del servizio ({iot hub}/jobs/v2/<jobId>?api-version=2016-11-14). Dopo l'avvio del processo, l'esecuzione di query relative ai processi consente all'app back-end aggiornare lo stato dei processi in esecuzione.

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

Argomenti di riferimento:

Gli argomenti di riferimento seguenti offrono altre informazioni sull'uso dei processi.

Processi per eseguire metodi diretti

Di seguito sono riportati i dettagli di una richiesta HTTP 1.1 per eseguire un metodo diretto in un set di dispositivi tramite un processo:

```
PUT /jobs/v2/<jobId>?api-version=2016-11-14

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8
Request-Id: <guid>
User-Agent: <sdk-name>/<sdk-version>

{
    jobId: '<jobId>',
    type: 'scheduleDirectRequest', 
    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 di seguito.

esempi

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.

Processi per aggiornare le proprietà dei dispositivi gemelli

Di seguito sono riportati i dettagli di una richiesta HTTP 1.1 per aggiornare le proprietà dei dispositivi gemelli tramite un processo:

```
PUT /jobs/v2/<jobId>?api-version=2016-11-14
Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8
Request-Id: <guid>
User-Agent: <sdk-name>/<sdk-version>

{
    jobId: '<jobId>',
    type: 'scheduleTwinUpdate', 
    updateTwin: <patch>                 // Valid JSON object
    queryCondition: '<queryOrDevices>', // query condition
    startTime: <jobStartTime>,          // as an ISO-8601 date string
    maxExecutionTimeInSeconds: <maxExecutionTimeInSeconds>        // format TBD
}
```

Esecuzione di query sull'avanzamento dei processi

Di seguito sono riportati i dettagli di una richiesta HTTP 1.1 per eseguire query sui processi:

```
GET /jobs/v2/query?api-version=2016-11-14[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8
Request-Id: <guid>
User-Agent: <sdk-name>/<sdk-version>
```

La risposta fornisce continuationToken.

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à Description
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:
scheduledUpdateTwin: un processo usato per aggiornare un set di proprietà o tag desiderati.
scheduledDeviceMethod: un 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.
scheduled: processo pianificato per un'ora futura.
running: processo attualmente attivo.
cancelled: processo annullato.
failed: processo non riuscito.
completed: processo completato.
deviceJobStatistics Statistiche sull'esecuzione del processo.

Proprietà deviceJobStatistics.

Proprietà Description
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 in cui il processo è in esecuzione.
deviceJobStatistics.pendingCount Numero di dispositivi in cui il processo è in attesa.

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, può essere utile l'esercitazione seguente sull'hub IoT: