Operazioni API MQTT del dispositivo dei processi

Puoi inviare i comandi del dispositivo di processi pubblicando i messaggi MQTT negli Argomenti riservati utilizzati per i comandi Jobs.

Il client lato dispositivo deve disporre della sottoscrizione agli argomenti del messaggio di risposta di questi comandi. Se utilizzi il client del dispositivo AWS IoT, il dispositivo sottoscrive automaticamente gli argomenti di risposta. Il che significa che il broker di messaggi pubblica gli argomenti dei messaggi di risposta nel client che ha pubblicato il messaggio di comando, a prescindere che il client abbia effettuato la sottoscrizione agli argomenti del messaggio di risposta. Questi messaggi di risposta non passano attraverso il broker di messaggi e non possono essere sottoscritti da altri client o regole.

Durante la sottoscrizione agli argomenti di processo ed evento jobExecution per la tua soluzione di monitoraggio del parco istanze, per prima cosa abilita gli eventi di processo e di esecuzione di processi per ricevere eventi sul lato cloud. Messaggi di avanzamento del processo che vengono elaborati tramite il broker di messaggi e possono essere utilizzati dalle regole di AWS IoT sono pubblicate come Eventi del servizio Jobs. Poiché il broker di messaggi pubblica i messaggi di risposta, anche senza una sottoscrizione esplicita, il client deve essere configurato per ricevere e identificare i messaggi ricevuti. Il cliente deve inoltre confermare che il thingName del messaggio in arrivo si applica al nome della cosa del client prima che il client agisca sul messaggio.

Nota

I messaggi che AWS IoT invia in risposta ai messaggi di comando MQTT Jobs API vengono addebitati sull’account, indipendentemente dal fatto che sia stato sottoscritto esplicitamente o meno.

Di seguito vengono illustrate le operazioni API MQTT e la relativa sintassi di richiesta e risposta. Tutte le operazioni API MQTT hanno i seguenti parametri:

clientToken: Un token client opzionale utilizzato per mettere in relazione richieste e risposte. Inserisci un valore arbitrario, che viene riportato nella risposta.
timestamp: Periodo di tempo, in secondi, dall'epoca all'invio del messaggio.

Ottiene l'elenco di tutti i processi che non si trovano in uno stato terminale, per un oggetto specifico.

Per richiamare quest'API, pubblica un messaggio in $aws/things/thingName/jobs/get.

Payload della richiesta:


{ "clientToken": "string" }

Il broker dei messaggi pubblicherà $aws/things/thingName/jobs/get/accepted e $aws/things/thingName/jobs/get/rejected anche senza un abbonamento specifico. Tuttavia, affinché il client riceva i messaggi, deve essere in ascolto. Per ulteriori informazioni, consulta la nota sui messaggi dell'API Jobs.

Payload della risposta:


{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}

Dove inProgressJobs e queuedJobs restituiscono un elenco di oggetti JobExecutionSummary che hanno lo stato IN_PROGRESS o QUEUED.

Recupera e avvia la successiva esecuzione del processo in sospeso per un oggetto (stato IN_PROGRESS o QUEUED).

Le esecuzioni di un processo con stato IN_PROGRESS vengono restituite per prime.
Le esecuzioni di un processo vengono restituite in base all'ordine di coda. Quando un elemento viene aggiunto o rimosso dal gruppo target per il tuo processo, conferma l'ordine di implementazione di eventuali nuove esecuzioni di processi rispetto alle esecuzioni di processi esistenti.
Se lo stato della successiva esecuzione del processo in sospeso è QUEUED, il relativo stato viene modificato in IN_PROGRESS e i dettagli dello stato dell'esecuzione del processo vengono impostati come specificato.
Se la successiva esecuzione del processo in sospeso è già nello stato IN_PROGRESS, i dettagli dello stato non vengono modificati.
Se non sono presenti esecuzioni in sospeso, la risposta non include il campo execution.
Facoltativamente, puoi creare un timer della fase impostando un valore per la proprietà stepTimeoutInMinutes. Se non aggiorni il valore di questa proprietà eseguendo UpdateJobExecution, il timeout dell'esecuzione del processo si verifica alla scadenza del timer della fase.

Per richiamare quest'API, pubblica un messaggio in $aws/things/thingName/jobs/start-next.

Payload della richiesta:


{ 
"statusDetails": {
    "string": "job-execution-state"
    ...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}

statusDetails: Raccolta di coppie nome-valore che descrivono lo stato dell'esecuzione del processo. Se non è specificato, statusDetails resta invariato.
stepTimeOutInMinutes: Specifica l'intervallo di tempo a disposizione di ciascun dispositivo per terminare l'esecuzione di questo processo. Se lo stato di esecuzione del processo non è impostato su uno stato terminale prima del timeout o prima della reimpostazione del timer (chiamando UpdateJobExecution, impostando lo stato su IN_PROGRESS e specificando un nuovo valore di timeout nel campo stepTimeoutInMinutes), lo stato di esecuzione del processo viene impostato su TIMED_OUT. L'impostazione di questo timeout non ha alcun effetto sul timeout dell'esecuzione del processo, che potresti avere specificato al momento della creazione del processo (CreateJob utilizzando il campo timeoutConfig).

Il broker dei messaggi pubblicherà $aws/things/thingName/jobs/start-next/accepted e $aws/things/thingName/jobs/start-next/rejected anche senza un abbonamento specifico. Tuttavia, affinché il client riceva i messaggi, deve essere in ascolto. Per ulteriori informazioni, consulta la nota sui messaggi dell'API Jobs.

Payload della risposta:


{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}

Dove execution è un oggetto JobExecution. Ad esempio:


{
"execution" : {
    "jobId" : "022",
    "thingName" : "MyThing",
    "jobDocument" : "< contents of job document >",
    "status" : "IN_PROGRESS",
    "queuedAt" : 1489096123309,
    "lastUpdatedAt" : 1489096123309,
    "versionNumber" : 1,
    "executionNumber" : 1234567890
},
"clientToken" : "client-1",
"timestamp" : 1489088524284,
}

Ottiene informazioni dettagliate sull'esecuzione di un processo.

Puoi impostare jobId su $next per restituire la successiva esecuzione del processo in sospeso per un oggetto (stato IN_PROGRESS o QUEUED).

Per richiamare quest'API, pubblica un messaggio in $aws/things/thingName/jobs/jobId/get.

Payload della richiesta:


{ 
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string" 
}

thingName

Nome dell'oggetto associato al dispositivo.

jobId

Identificatore univoco assegnato al processo al momento della creazione.

In alternativa, utilizza $next per restituire la successiva esecuzione del processo in sospeso per un oggetto (stato IN_PROGRESS o QUEUED). In questo caso, le esecuzioni del processo con stato IN_PROGRESS vengono restituite per prime. Le esecuzioni di un processo vengono restituite in base all'ordine di creazione.

executionNumber

(Facoltativo) Numero che identifica l'esecuzione di un processo in un dispositivo. Se non è specificato, viene restituita l'ultima esecuzione del processo.

includeJobDocument

(Facoltativo) A meno che non sia impostato su false, la risposta contiene il documento del processo. Il valore predefinito è true.

Il broker dei messaggi pubblicherà $aws/things/thingName/jobs/jobId/get/accepted e $aws/things/thingName/jobs/jobId/get/rejected anche senza un abbonamento specifico. Tuttavia, affinché il client riceva i messaggi, deve essere in ascolto. Per ulteriori informazioni, consulta la nota sui messaggi dell'API Jobs.

Payload della risposta:


{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}

Dove execution è un oggetto JobExecution.

Aggiorna lo stato dell'esecuzione di un processo. Se lo desideri, puoi creare un timer della fase impostando un valore per la proprietà stepTimeoutInMinutes. Se non aggiorni il valore di questa proprietà eseguendo nuovamente UpdateJobExecution, il timeout dell'esecuzione del processo si verifica alla scadenza del timer della fase.

Per richiamare quest'API, pubblica un messaggio in $aws/things/thingName/jobs/jobId/update.

Payload della richiesta:


{
"status": "job-execution-state",
"statusDetails": { 
    "string": "string"
    ...
},
"expectedVersion": "number",
"executionNumber": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"clientToken": "string"
}

status: Il nuovo stato per l'esecuzione del processo (IN_PROGRESS, FAILED, SUCCEEDED o REJECTED). Questo valore deve essere specificato per ogni aggiornamento.
statusDetails: Raccolta di coppie nome-valore che descrivono lo stato dell'esecuzione del processo. Se non è specificato, statusDetails resta invariato.
expectedVersion: Versione corrente prevista dell'esecuzione del processo. Ogni volta che aggiorni l'esecuzione del processo, la versione viene incrementata. Se la versione dell'esecuzione del processo archiviata nel servizio AWS IoT Jobs non corrisponde, l'aggiornamento viene rifiutato restituendo un errore VersionMismatch. Viene restituito anche un file ErrorResponse contenente i dati sullo stato di esecuzione del processo attuale. Questo comportamento rende inutile una richiesta DescribeJobExecution separata per ottenere i dati sullo stato dell'esecuzione del processo.
executionNumber: (Facoltativo) Numero che identifica l'esecuzione di un processo in un dispositivo. Se non è specificato, viene usata l'ultima esecuzione del processo.
includeJobExecutionState: (Facoltativo) Quando è incluso e impostato su true, la risposta contiene il campo JobExecutionState. Il valore predefinito è false.
includeJobDocument: (Facoltativo) Quando è incluso e impostato su true, la risposta contiene JobDocument. Il valore predefinito è false.
stepTimeoutInMinutes: Specifica l'intervallo di tempo a disposizione di ciascun dispositivo per terminare l'esecuzione di questo processo. Lo stato di esecuzione del processo è impostato su TIMED_OUT, a meno che non venga impostato su uno stato terminale prima del timeout o prima che il timer venga reimpostato. L'impostazione o la reimpostazione di questo timeout non ha alcun effetto su quello dell'esecuzione del processo che potresti avere specificato al momento della creazione del processo.

Il broker dei messaggi pubblicherà $aws/things/thingName/jobs/jobId/update/accepted e $aws/things/thingName/jobs/jobId/update/rejected anche senza un abbonamento specifico. Tuttavia, affinché il client riceva i messaggi, deve essere in ascolto. Per ulteriori informazioni, consulta la nota sui messaggi dell'API Jobs.

Payload della risposta:


{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}

executionState: Oggetto JobExecutionState.
jobDocument: Un oggetto documento del processo.
timestamp: Periodo di tempo, in secondi, dall'epoca all'invio del messaggio.
clientToken: Token client usato per mettere in relazione richieste e risposte.

Quando si utilizza il protocollo MQTT, è anche possibile eseguire i seguenti aggiornamenti:

Inviato ogni volta che un'esecuzione di un processo viene aggiunta o rimossa dall'elenco di esecuzioni del processo in sospeso per un oggetto.

Utilizza l'argomento :

$aws/things/thingName/jobs/notify

Payload del messaggio:


{
"jobs" : {
    "JobExecutionState": [ JobExecutionSummary ... ]
         },
    "timestamp": timestamp
}

Inviato ogni volta che c'è una modifica a cui segue l'esecuzione del processo nell'elenco delle esecuzioni di processi in sospeso per qualcosa, come definito per DescribeJobExecution jobId con $next. Questo messaggio non viene inviato quando cambiano i dettagli della successiva esecuzione del processo, ma solo quando cambia il processo successivo che verrebbe restituito da DescribeJobExecution con jobId $next. Considera le esecuzioni di processo J1 e J2 con stato QUEUED. J1 è l'esecuzione successiva nell'elenco di esecuzioni del processo in sospeso. Se lo stato di J2 viene modificato in IN_PROGRESS, mentre lo stato di J1 rimane invariato, questa notifica viene inviata e contiene i dettagli di J2.

Utilizza l'argomento :

$aws/things/thingName/jobs/notify-next

Payload del messaggio:


{
"execution" : JobExecution,
"timestamp": timestamp,
}

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Tipi di dati e operazioni API MQTT e HTTPS per i dispositivi per il servizio Jobs

API HTTP del dispositivo di processi