As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Operações da API MQTT do dispositivo de trabalhos
Você pode emitir comandos do dispositivo de trabalhos publicando mensagens MQTT nos [Tópicos reservados usados para comandos de trabalhos](reserved-topics.md#reserved-topics-job).
Seu cliente do lado do dispositivo deve estar inscrito nos tópicos das mensagens de resposta desses comandos. Se você usar o AWS IoT Device Client, seu dispositivo se inscreverá automaticamente nos tópicos de resposta. Isso indica que agente de mensagens publicará tópicos da mensagem de resposta para o cliente que publicou a mensagem de comando, independentemente de seu cliente ter assinado ou não os tópicos da mensagem de resposta. Essas mensagens de resposta não passam pelo agente de mensagens e não podem ser assinadas por outros clientes ou regras.
Ao assinar os tópicos de trabalhos e tópicos do evento `jobExecution` de sua solução de monitoramento de frota, primeiro habilite os [eventos de trabalho e execução de trabalhos](iot-events.md) para receber quaisquer eventos no lado da nuvem. As mensagens de progresso do trabalho que são processadas por meio do agente de mensagens e podem ser usadas pelas regras de AWS IoT são publicadas como [Eventos de trabalho](events-jobs.md). Como o agente de mensagens publica mensagens de resposta, mesmo sem uma assinatura explícita, seu cliente deve estar configurado para receber e identificar as mensagens que recebe. Seu cliente também deve confirmar que o tópico *thingName* na mensagem recebida se aplica ao nome da coisa do cliente antes que o cliente aja na mensagem.
**nota**
As mensagens AWS IoT enviadas em resposta às mensagens de comando da API MQTT Jobs são cobradas em sua conta, independentemente de você ter se inscrito ou não explicitamente.
Veja a seguir as operações da API MQTT e sua sintaxe de solicitação e resposta. Todas as operações da API MQTT têm os seguintes parâmetros:
clientToken
Um token do cliente opcional usado para correlacionar solicitações e respostas. Insira um valor arbitrário aqui e ele será refletido na resposta.
`timestamp`
O tempo, em segundos, desde a epoch em que a mensagem foi enviada.
## GetPendingJobExecutions
Obtém a lista de todos os trabalhos que não estão em um status terminal, para um objeto específica.
Para invocar essa API, publique uma mensagem em `$aws/things/thingName/jobs/get`.
Carga da solicitação:
```
{ "clientToken": "string" }
```
O agente de mensagens publicará `$aws/things/thingName/jobs/get/accepted` e `$aws/things/thingName/jobs/get/rejected` mesmo sem uma assinatura específica. No entanto, para que seu cliente receba as mensagens, ele deve estar ouvindo. Para obter mais informações, consulte a [observação sobre mensagens de API do Jobs](#jobs-mqtt-note).
Carga da resposta:
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}
```
Onde `inProgressJobs` e `queuedJobs` retornam uma lista de objetos [JobExecutionSummary](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-summary) que têm status de `IN_PROGRESS` ou `QUEUED`.
## StartNextPendingJobExecution
Obtém e começa a próxima execução de trabalho pendente para um objeto (status `IN_PROGRESS` ou `QUEUED`).
+ Todas as execuções de trabalho com o status `IN_PROGRESS` são retornadas primeiro.
+ As execuções de trabalho são retornadas na ordem em que foram colocadas em fila. Quando um objeto for adicionada ou removida do grupo de destino do seu trabalho, confirme a ordem de distribuição de qualquer nova execução de trabalho em comparação com as execuções de trabalhos existentes.
+ Se a execução do próximo trabalho pendente for `QUEUED`, seu estado será alterado para `IN_PROGRESS` e os detalhes do status da execução do trabalho serão definidos conforme especificado.
+ Se a execução do próximo trabalho pendente já for `IN_PROGRESS`, os detalhes de seu status não serão alterados.
+ Se nenhuma execução de trabalho estiver pendente, a resposta não incluirá o campo `execution`.
+ Se desejar, você pode criar um temporizador de etapa definindo um valor para a propriedade `stepTimeoutInMinutes`. Se você não atualizar o valor dessa propriedade executando `UpdateJobExecution`, a execução do trabalho atingirá o tempo limite quando o temporizador de etapa expirar.
Para invocar essa API, publique uma mensagem em `$aws/things/thingName/jobs/start-next`.
Carga da solicitação:
```
{
"statusDetails": {
"string": "job-execution-state"
...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
```
`statusDetails`
Uma coleção de pares nome e valor que descrevem o status da execução do trabalho. Se não especificado, o `statusDetails` não será alterado.
`stepTimeOutInMinutes`
Especifica o tempo que este dispositivo tem para concluir a execução do trabalho. Se o status de execução do trabalho não estiver definido como um estado terminal antes que o temporizador expire ou seja redefinido (ao chamar `UpdateJobExecution`, definir o status como `IN_PROGRESS` e especificar um novo valor de tempo limite no campo `stepTimeoutInMinutes`), o status de execução do trabalho será definido como `TIMED_OUT`. A configuração do tempo limite não tem efeito sobre o tempo limite de execução desse trabalho, que pode ter sido especificado quando o trabalho foi criado (`CreateJob` usando o campo `timeoutConfig`).
Os valores válidos para este parâmetro variam de 1 a 10.080 (1 minuto a 7 dias). Um valor de -1 também é válido e cancelará o cronômetro da etapa atual (criado por um uso anterior do UpdateJobExecutionRequest).
O agente de mensagens publicará `$aws/things/thingName/jobs/start-next/accepted` e `$aws/things/thingName/jobs/start-next/rejected` mesmo sem uma assinatura específica. No entanto, para que seu cliente receba as mensagens, ele deve estar ouvindo. Para obter mais informações, consulte a [observação sobre mensagens de API do Jobs](#jobs-mqtt-note).
Carga da resposta:
```
{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}
```
Onde `execution` é um objeto [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data). Por exemplo:
```
{
"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
Obtém informações detalhadas sobre uma execução de trabalho.
Você pode definir `jobId` como `$next` para retornar a próxima execução de trabalho pendente para um objeto (com status `IN_PROGRESS` ou `QUEUED`).
Para invocar essa API, publique uma mensagem em `$aws/things/thingName/jobs/jobId/get`.
Carga da solicitação:
```
{
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string"
}
```
`thingName`
O nome do objeto associada ao dispositivo.
`jobId`
O identificador exclusivo atribuído a este trabalho quando ele foi criado.
Ou usar `$next` para retornar a próxima execução de trabalho pendente para um objeto (com status `IN_PROGRESS` ou `QUEUED`). Nesse caso, todas as execuções de trabalho com o status `IN_PROGRESS` são retornadas primeiro. As execuções de trabalho são retornadas na ordem em que foram criadas.
`executionNumber`
(Opcional) Um número que identifica a execução de um trabalho em um dispositivo. Se não especificado, a execução do trabalho mais recente será retornada.
`includeJobDocument`
(Opcional) A menos que definido como `false`, a resposta conterá o documento de trabalho. O padrão é `true`.
O agente de mensagens publicará `$aws/things/thingName/jobs/jobId/get/accepted` e `$aws/things/thingName/jobs/jobId/get/rejected` mesmo sem uma assinatura específica. No entanto, para que seu cliente receba as mensagens, ele deve estar ouvindo. Para obter mais informações, consulte a [observação sobre mensagens de API do Jobs](#jobs-mqtt-note).
Carga da resposta:
```
{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}
```
Onde `execution` é um objeto [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data).
## UpdateJobExecution
Atualiza o status de uma execução de trabalho. Você pode criar um temporizador de etapa. Para isso, defina um valor para a propriedade `stepTimeoutInMinutes`. Se você não atualizar o valor dessa propriedade executando `UpdateJobExecution` novamente, a execução do trabalho atingirá o tempo limite quando o temporizador de etapa expirar.
Para invocar essa API, publique uma mensagem em `$aws/things/thingName/jobs/jobId/update`.
Carga da solicitação:
```
{
"status": "job-execution-state",
"statusDetails": {
"string": "string"
...
},
"expectedVersion": "number",
"executionNumber": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
```
`status`
O novo status da execução do trabalho (`IN_PROGRESS`, `FAILED`, `SUCCEEDED` ou`REJECTED`). Isso deve ser especificado em todas as atualizações.
`statusDetails`
Uma coleção de pares nome e valor que descrevem o status da execução do trabalho. Se não especificado, o `statusDetails` não será alterado.
`expectedVersion`
A versão esperada atual da execução do trabalho. Cada vez que você atualiza a execução do trabalho, sua versão é incrementada. Se a versão da execução do trabalho armazenada no serviço AWS IoT Jobs não corresponder, a atualização será rejeitada com um `VersionMismatch` erro. Um [ErrorResponse](jobs-api.md#jobs-mqtt-error-response) que contém os dados atuais do status de execução do trabalho também é retornado. Isso torna desnecessário executar uma solicitação `DescribeJobExecution` separada para obter os dados do status da execução do trabalho.
`executionNumber`
(Opcional) Um número que identifica a execução de um trabalho em um dispositivo. Se não especificado, a execução do trabalho mais recente será usada.
`includeJobExecutionState`
(Opcional) Quando incluído e definido como `true`, a resposta conterá o campo `JobExecutionState`. O padrão é `false`.
`includeJobDocument`
(Opcional) Quando incluído e definido como `true`, a resposta conterá o `JobDocument`. O padrão é `false`.
`stepTimeoutInMinutes`
Especifica o tempo que este dispositivo tem para concluir a execução do trabalho. Se o status de execução do trabalho não for definido como um estado terminal antes que o temporizador expire ou antes que o temporizador seja redefinido, o status da execução do trabalho será definido como `TIMED_OUT`. A configuração ou a reconfiguração do tempo limite não tem efeito sobre o tempo limite de execução do trabalho que pode ter sido especificado quando o trabalho foi criado.
O agente de mensagens publicará `$aws/things/thingName/jobs/jobId/update/accepted` e `$aws/things/thingName/jobs/jobId/update/rejected` mesmo sem uma assinatura específica. No entanto, para que seu cliente receba as mensagens, ele deve estar ouvindo. Para obter mais informações, consulte a [observação sobre mensagens de API do Jobs](#jobs-mqtt-note).
Carga da resposta:
```
{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}
```
`executionState`
Um objeto [JobExecutionState](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-state).
`jobDocument`
Um objeto [documento de trabalho](key-concepts-jobs.md).
Nas respostas do MQTT, o campo `jobDocument` é um objeto JSON. Nas respostas HTTP, é uma representação de string do objeto JSON.
`timestamp`
O tempo, em segundos, desde a epoch em que a mensagem foi enviada.
`clientToken`
Um token do cliente usado para correlacionar solicitações e respostas.
Ao usar o protocolo MQTT, você também pode realizar as seguintes atualizações:
## JobExecutionsChanged
Enviado sempre que uma execução de trabalho é adicionada ou removida da lista de execuções de trabalhos pendentes para um objeto.
Use o tópico :
`$aws/things/thingName/jobs/notify`
Carga da mensagem:
```
{
"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
Enviado sempre que houver uma alteração em qual execução de trabalho é a seguinte na lista de execuções de trabalhos pendentes para um objeto, conforme definido para [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) com o `jobId` `$next`. Essa mensagem não é enviada quando os detalhes da próxima execução de trabalho são alterados, apenas quando o próximo trabalho que seria retornado por `DescribeJobExecution` com o `jobId` `$next` tiver sido alterado. Considere as execuções de trabalho J1 e J2 com status `QUEUED`. J1 é a próxima na lista de execuções de trabalhos pendentes. Se o status de J2 for alterado para `IN_PROGRESS` enquanto o estado de J1 permanecer inalterado, essa notificação será enviada e conterá os detalhes do J2.
Use o tópico :
`$aws/things/thingName/jobs/notify-next`
Carga da mensagem:
```
{
"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,
}
```