Pianificare processi in più dispositiviSchedule jobs on multiple devices

L'hub IoT di Azure abilita un numero di blocchi predefiniti, ad esempio tag e proprietà di dispositivi gemelli e metodi diretti.Azure IoT Hub enables a number of building blocks like device twin properties and tags and direct methods. 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.Typically, back-end apps enable device administrators and operators to update and interact with IoT devices in bulk and at a scheduled time. I processi eseguono l'aggiornamento di dispositivi gemelli e metodi diretti rispetto a un set di dispositivi a un'ora pianificata.Jobs execute device twin updates and direct methods against a set of devices at a scheduled time. 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.For example, an operator would use a back-end app that initiates and tracks a job to reboot a set of devices in building 43 and floor 3 at a time that would not be disruptive to the operations of the building.

È consigliabile usare i processi quando è necessario pianificare e tenere traccia dell'avanzamento di una qualsiasi delle attività seguenti in un set di dispositivi:Consider using jobs when you need to schedule and track progress any of the following activities on a set of devices:

  • Aggiornare le proprietà desiderateUpdate desired properties
  • Aggiornare i tagUpdate tags
  • Richiamare metodi direttiInvoke direct methods

Ciclo di vita dei processiJob lifecycle

I processi vengono avviati dal back-end della soluzione e mantenuti dall'hub IoT.Jobs are initiated by the solution back end and maintained by IoT Hub. È 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).You can initiate a job through a service-facing URI ({iot hub}/jobs/v2/{device id}/methods/<jobID>?api-version=2016-11-14) and query for progress on an executing job through a service-facing URI ({iot hub}/jobs/v2/<jobId>?api-version=2016-11-14). Per aggiornare lo stato dei processi in esecuzione dopo l'avvio, eseguire query sui processi.To refresh the status of running jobs once a job is initiated, run a job query.

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.When you initiate a job, property names and values can only contain US-ASCII printable alphanumeric, except any in the following set: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT.

Processi per eseguire metodi direttiJobs to execute direct methods

Nel frammento di codice seguente sono riportati i dettagli della richiesta HTTPS 1.1 per l'esecuzione di un metodo diretto in un set di dispositivi tramite un processo:The following snippet shows the HTTPS 1.1 request details for executing a direct method on a set of devices using a job:

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 negli esempi seguenti:The query condition can also be on a single device ID or on a list of device IDs as shown in the following examples:

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.IoT Hub Query Language covers IoT Hub query language in additional detail.

Processi per aggiornare le proprietà dei dispositivi gemelliJobs to update device twin properties

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:The following snippet shows the HTTPS 1.1 request details for updating device twin properties using a job:

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 processiQuerying for progress on jobs

Nel frammento di codice seguente sono riportati i dettagli della richiesta HTTPS 1.1 per l'esecuzione di query sui processi:The following snippet shows the HTTPS 1.1 request details for querying for jobs:

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.The continuationToken is provided from the response.

Proprietà dei processiJobs Properties

Di seguito è riportato un elenco di proprietà e corrispondenti descrizioni che è possibile usare quando si eseguono query sui processi o sui relativi risultati.The following list shows the properties and corresponding descriptions, which can be used when querying for jobs or job results.

ProprietàProperty DescriptionDescription
jobIdjobId ID fornito dall'applicazione per il processo.Application provided ID for the job.
startTimestartTime Ora di inizio fornita dall'applicazione (ISO 8601) per il processo.Application provided start time (ISO-8601) for the job.
endTimeendTime Data fornita dall'hub IoT (ISO 8601) per il completamento del processo.IoT Hub provided date (ISO-8601) for when the job completed. È valida solo quando il processo raggiunge lo stato di completamento.Valid only after the job reaches the 'completed' state.
typetype Tipi di processi:Types of jobs:
scheduledUpdateTwin: un processo usato per aggiornare un set di proprietà o tag desiderati.scheduledUpdateTwin: A job used to update a set of desired properties or tags.
scheduledDeviceMethod: un processo usato per richiamare un metodo di dispositivo in un set di dispositivi gemelli.scheduledDeviceMethod: A job used to invoke a device method on a set of device twins.
Statostatus Stato corrente del processo.Current state of the job. Valori possibili per lo stato:Possible values for status:
pending: processo pianificato e in attesa del prelievo da parte del servizio del processo.pending: Scheduled and waiting to be picked up by the job service.
scheduled: processo pianificato per un'ora futura.scheduled: Scheduled for a time in the future.
running: processo attualmente attivo.running: Currently active job.
canceled: il processo è stato annullato.canceled: Job has been canceled.
failed: processo non riuscito.failed: Job failed.
completed: processo completato.completed: Job has completed.
deviceJobStatisticsdeviceJobStatistics Statistiche sull'esecuzione del processo.Statistics about the job's execution.
Proprietà deviceJobStatistics:deviceJobStatistics properties:
deviceJobStatistics.deviceCount: numero di dispositivi nel processo.deviceJobStatistics.deviceCount: Number of devices in the job.
deviceJobStatistics.deviceCount: numero di dispositivi in cui il processo non è riuscito.deviceJobStatistics.failedCount: Number of devices where the job failed.
deviceJobStatistics.succeededCount: numero di dispositivi in cui il processo è riuscito.deviceJobStatistics.succeededCount: Number of devices where the job succeeded.
deviceJobStatistics.runningCount: numero di dispositivi in cui il processo è in esecuzione.deviceJobStatistics.runningCount: Number of devices that are currently running the job.
deviceJobStatistics.pendingCount: numero di dispositivi in cui il processo è in sospeso.deviceJobStatistics.pendingCount: Number of devices that are pending to run the job.

Materiale di riferimentoAdditional reference material

Di seguito sono indicati altri argomenti di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:Other reference topics in the IoT Hub developer guide include:

Passaggi successiviNext steps

Per provare alcuni dei concetti descritti in questo articolo, può essere utile l'esercitazione seguente sull'hub IoT:If you would like to try out some of the concepts described in this article, you may be interested in the following IoT Hub tutorial: