Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# 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](reserved-topics.md#reserved-topics-job).
El cliente del dispositivo debe estar suscrito a los temas de los mensajes de respuesta de estos comandos. Si utiliza el cliente de AWS IoT dispositivo, su 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](iot-events.md) 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](events-jobs.md). 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* tema del mensaje entrante se aplica al nombre del cliente antes de que el cliente actúe en función del mensaje.
**nota**
Los mensajes que se AWS IoT envían en respuesta a los comandos 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.
## GetPendingJobExecutions
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](#jobs-mqtt-note).
Carga de respuesta:
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}
```
Donde `inProgressJobs` y `queuedJobs` devuelven una lista de objetos [JobExecutionSummary](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-summary) cuyo estado es `IN_PROGRESS` o `QUEUED`.
## StartNextPendingJobExecution
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`).
Los valores válidos para este parámetro están comprendidos entre 1 y 10 080 (1 minuto a 7 días). El valor -1 también es válido y cancelará el temporizador de pasos actual (creado por el uso anterior de UpdateJobExecutionRequest).
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](#jobs-mqtt-note).
Carga de respuesta:
```
{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}
```
Donde `execution` es un objeto [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data). 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,
}
```
## DescribeJobExecution
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](#jobs-mqtt-note).
Carga de respuesta:
```
{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}
```
Donde `execution` es un objeto [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data).
## UpdateJobExecution
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 AWS IoT Jobs no coincide, la actualización se rechaza con un `VersionMismatch` error. También se devuelve una [ErrorResponse](jobs-api.md#jobs-mqtt-error-response) 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](#jobs-mqtt-note).
Carga de respuesta:
```
{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}
```
`executionState`
Un objeto [JobExecutionState](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-state).
`jobDocument`
Un objeto [documento de trabajo](key-concepts-jobs.md).
En las respuestas de MQTT, el campo `jobDocument` es un objeto JSON. En las respuestas de HTTP, es una representación de cadena del objeto JSON.
`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:
## JobExecutionsChanged
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": [ [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) ... ]
},
"timestamp": timestamp
}
```
## NextJobExecutionChanged
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 [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) 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" : [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html),
"timestamp": timestamp,
}
```