Operaciones de la API MQTT de dispositivos de Jobs

Puede emitir comandos de dispositivos de Jobs publicando los mensajes MQTT en los Temas reservados utilizados para comandos de Jobs.

El cliente del dispositivo debe estar suscrito a los temas de los mensajes de respuesta de estos comandos. Si utiliza el cliente de dispositivo de AWS IoT, el dispositivo se suscribirá automáticamente a los temas de respuesta. Esto significa que el agente de mensajes publicará los temas de los mensajes de respuesta en el cliente que publicó el mensaje de comando, independientemente de que su cliente se haya suscrito o no a los temas de los mensajes de respuesta. Estos mensajes de respuesta no pasan por el agente de mensajes y otros clientes o reglas no pueden suscribirse a ellos.

Al suscribirse al trabajo y a los temas de eventos jobExecution de su solución de monitoreo de flota, primero habilite los eventos de trabajos y ejecución de trabajos para recibir cualquier evento en la nube. Los mensajes de progreso del trabajo que se procesan a través del agente de mensajes y que las reglas de AWS IoT pueden utilizar se publican como Eventos de trabajos. Como el agente de mensajes publica los mensajes de respuesta, incluso sin una suscripción explícita a ellos, el cliente debe estar configurado para recibir e identificar los mensajes que recibe. El cliente también debe confirmar que el thingName del tema del mensaje entrante se aplica al nombre de su objeto del cliente antes de actuar conforme a dicho mensaje.

nota

Los mensajes que AWS IoT envía en respuesta a los mensajes de comando de la API MQTT Jobs se cargan a su cuenta, independientemente de que se haya suscrito a ellos de forma explícita o no.

A continuación se muestran las operaciones de la API MQTT y su sintaxis de solicitud y respuesta. Todas las operaciones de la API MQTT presentan los siguientes parámetros:

clientToken: Un token de cliente opcional utilizado para correlacionar solicitudes y respuestas. Introduzca un valor arbitrario aquí y se reflejará en la respuesta.
timestamp: El tiempo, en segundos, desde la fecha de inicio, cuando se envió el mensaje.

Obtiene la lista de todos los trabajos que no están en un estado terminal, respecto de un objeto especificado.

Para invocar esta API, publique un mensaje en $aws/things/thingName/jobs/get.

Carga de solicitud:


{ "clientToken": "string" }

El agente de mensajes publicará $aws/things/thingName/jobs/get/accepted e $aws/things/thingName/jobs/get/rejected incluso sin una suscripción específica a ellos. Sin embargo, para que su cliente reciba los mensajes, debe estar escuchándolos. Para obtener más información, consulte la nota sobre los mensajes de la API de trabajos.

Carga de respuesta:


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

Donde inProgressJobs y queuedJobs devuelven una lista de objetos JobExecutionSummary cuyo estado es IN_PROGRESS o QUEUED.

Obtiene y comienza la siguiente ejecución de trabajos pendientes de un objeto (estado IN_PROGRESS o QUEUED).

Las ejecuciones de trabajo con el estado IN_PROGRESS se devuelven en primer lugar.
Las ejecuciones de trabajo se devuelven en el orden en el que se pusieron en cola. Cuando añada o elimine algo del grupo de destino de su trabajo, confirme el orden de despliegue de las ejecuciones de trabajos nuevos en comparación con las ejecuciones de trabajos existentes.
Si la siguiente ejecución de trabajo pendiente es QUEUED, su estado cambia a IN_PROGRESS y los detalles del estado de la ejecución de trabajo se establecen según se haya especificado.
Si la siguiente ejecución de trabajo pendiente está ya en IN_PROGRESS, los detalles del estado no cambiarán.
Si no hay ejecuciones de trabajo pendientes, la respuesta no incluirá el campo execution.
Opcionalmente, puede crear un temporizador de pasos estableciendo un valor para la propiedad stepTimeoutInMinutes. Si no actualiza el valor de esta propiedad mediante la ejecución de UpdateJobExecution, la ejecución del trabajo agotará el tiempo de espera cuando venza el temporizador de pasos.

Para invocar esta API, publique un mensaje en $aws/things/thingName/jobs/start-next.

Carga de solicitud:


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

statusDetails: Un conjunto de pares nombre-valor que describen el estado de ejecución del trabajo. Si no se especifica, statusDetails no se modifica.
stepTimeOutInMinutes: Especifica la cantidad de tiempo que tiene este dispositivo para finalizar la ejecución de este trabajo. Si el estado de ejecución del trabajo no se ha establecido en un estado terminal antes de que este temporizador venza o antes de que se restablezca el temporizador (llamando a UpdateJobExecution, estableciendo el estado en IN_PROGRESS y especificando un valor de tiempo de espera nuevo en el campo stepTimeoutInMinutes) el estado de ejecución se establece automáticamente en TIMED_OUT. Configurar este tiempo de espera no tiene ningún efecto en el tiempo de espera de la ejecución de ese trabajo que se pueda haber especificado cuando se creó el trabajo (CreateJob con el campo timeoutConfig).

El agente de mensajes publicará $aws/things/thingName/jobs/start-next/accepted e $aws/things/thingName/jobs/start-next/rejected incluso sin una suscripción específica a ellos. Sin embargo, para que su cliente reciba los mensajes, debe estar escuchándolos. Para obtener más información, consulte la nota sobre los mensajes de la API de trabajos.

Carga de respuesta:


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

Donde execution es un objeto JobExecution. Por ejemplo:


{
"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,
}

Obtiene información detallada acerca de una ejecución de trabajo.

Puede establecer jobId en $next para devolver la siguiente ejecución de trabajo pendiente para un objeto (estado IN_PROGRESS o QUEUED).

Para invocar esta API, publique un mensaje en $aws/things/thingName/jobs/jobId/get.

Carga de solicitud:


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

thingName

El nombre del objeto asociado con el dispositivo.

jobId

El identificador único asignado a este trabajo cuando se creó.

También puede usar $next para devolver la siguiente ejecución de trabajo pendiente para un objeto (estado IN_PROGRESS o QUEUED). En este caso, las ejecuciones de trabajo con el estado IN_PROGRESS se devuelven en primer lugar. Las ejecuciones de trabajo se devuelven en el orden en el que se crearon.

executionNumber

(Opcional) Un número que identifica la ejecución de un trabajo en un dispositivo. Si no se especifica, se devuelve la ejecución de trabajo más reciente.

includeJobDocument

(Opcional) Cuando no se establece en false, la respuesta contiene el documento de trabajo. El valor predeterminado es true.

El agente de mensajes publicará $aws/things/thingName/jobs/jobId/get/accepted e $aws/things/thingName/jobs/jobId/get/rejected incluso sin una suscripción específica a ellos. Sin embargo, para que su cliente reciba los mensajes, debe estar escuchándolos. Para obtener más información, consulte la nota sobre los mensajes de la API de trabajos.

Carga de respuesta:


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

Donde execution es un objeto JobExecution.

Actualiza el estado de una ejecución de trabajo. Si lo prefiere, puede crear un temporizador de pasos estableciendo un valor para la propiedad stepTimeoutInMinutes. Si no actualiza el valor de esta propiedad ejecutando UpdateJobExecution otra vez, la ejecución del trabajo agotará el tiempo de espera cuando venza el temporizador de pasos.

Para invocar esta API, publique un mensaje en $aws/things/thingName/jobs/jobId/update.

Carga de solicitud:


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

status: El nuevo estado de ejecución del trabajo (IN_PROGRESS, FAILED, SUCCEEDED o REJECTED). Debe especificarse en cada actualización.
statusDetails: Un conjunto de pares nombre-valor que describen el estado de ejecución del trabajo. Si no se especifica, statusDetails no se modifica.
expectedVersion: La versión actual esperada de la ejecución de trabajos. Cada vez que actualiza la ejecución de trabajos, aumenta su versión. Si la versión de la ejecución del trabajo almacenada en el servicio de Jobs de AWS IoT no coincide, la actualización se rechaza con un error VersionMismatch. También se devuelve una ErrorResponse que contiene los datos del estado actual de ejecución del trabajo. (Esto hace que no sea necesario realizar una solicitud DescribeJobExecution aparte para obtener los datos de estado de ejecución del trabajo).
executionNumber: (Opcional) Un número que identifica la ejecución de un trabajo en un dispositivo. Si no se especifica, se utiliza la ejecución de trabajo más reciente.
includeJobExecutionState: (Opcional) Cuando se incluye y establece en true, la respuesta contiene el campo JobExecutionState. El valor predeterminado es false.
includeJobDocument: (Opcional) Cuando se incluye y establece en true, la respuesta contiene el JobDocument. El valor predeterminado es false.
stepTimeoutInMinutes: Especifica la cantidad de tiempo que tiene este dispositivo para finalizar la ejecución de este trabajo. Si el estado de ejecución del trabajo no se ha establecido en un estado terminal antes de que este temporizador venza, o antes de que se restablezca, el estado de ejecución del trabajo se establece en TIMED_OUT. Configurar o restablecer este tiempo de espera no tiene ningún efecto en el tiempo de espera de la ejecución del trabajo que se pueda haber especificado cuando se creó el trabajo.

El agente de mensajes publicará $aws/things/thingName/jobs/jobId/update/accepted e $aws/things/thingName/jobs/jobId/update/rejected incluso sin una suscripción específica a ellos. Sin embargo, para que su cliente reciba los mensajes, debe estar escuchándolos. Para obtener más información, consulte la nota sobre los mensajes de la API de trabajos.

Carga de respuesta:


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

executionState: Un objeto JobExecutionState.
jobDocument: Un objeto documento de trabajo.
timestamp: El tiempo, en segundos, desde la fecha de inicio, cuando se envió el mensaje.
clientToken: Un token de cliente utilizado para correlacionar solicitudes y respuestas.

Al utilizar el protocolo MQTT, también puede realizar las siguientes actualizaciones:

Se envía cuando se añade una ejecución de trabajo a la lista de ejecuciones de trabajo pendientes para un objeto, o cuando se quita de dicha lista.

Utilice el tema :

$aws/things/thingName/jobs/notify

Carga útil de mensaje:


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

Se envía cuando se produce un cambio en el que la ejecución de trabajo es la siguiente en la lista de ejecuciones de trabajo pendientes para un objeto, como se define para DescribeJobExecution con jobId $next. Este mensaje no se envía cuando cambian los detalles de ejecución del siguiente trabajo, solo cuando el siguiente trabajo que devolvería DescribeJobExecution con jobId $next ha cambiado. Considere las ejecuciones de trabajo J1 y J2 con el estado QUEUED. J1 es el siguiente elemento de la lista de ejecuciones de trabajo pendientes. Si el estado de J2 cambia a IN_PROGRESS mientras el estado de J1 permanece invariable, se envía esta notificación y contiene los detalles de J2.

Utilice el tema :

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

Carga útil de mensaje:


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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Operaciones y tipos de datos de las API MQTT y HTTPS de dispositivos de Jobs

API HTTP de dispositivos de Jobs