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.

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 assinará automaticamente os 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 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. 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 thingName no tópico da mensagem recebida se aplica ao nome do objeto do cliente antes que o cliente aja na mensagem.

nota

As mensagens que o AWS IoT envia em resposta às mensagens de comando da API MQTT do serviço Jobs são cobradas em sua conta, independentemente de você tê-las assinado 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.

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.

Carga da resposta:


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

Onde inProgressJobs e queuedJobs retornam uma lista de objetos JobExecutionSummary que têm status de IN_PROGRESS ou QUEUED.

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).

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.

Carga da resposta:


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

Onde execution é um objeto JobExecution. 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,
}

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.

Carga da resposta:


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

Onde execution é um objeto JobExecution.

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 ouREJECTED). 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 Jobs do AWS IoT não corresponder, a atualização será rejeitada com um erro de VersionMismatch. Um ErrorResponse 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.

Carga da resposta:


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

executionState: Um objeto JobExecutionState.
jobDocument: Um objeto documento de trabalho.
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:

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": [ JobExecutionSummary ... ]
         },
    "timestamp": timestamp
}

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 DescribeJobExecution 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" : JobExecution,
"timestamp": timestamp,
}

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Tipos de dados e operações da API MQTT e HTTPS do dispositivo de trabalhos

API HTTP do dispositivo do Jobs