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á.
# AWS IoT Device Management comandos
**Importante**
Esta documentação descreve como você pode usar o [recurso de comandos no AWS IoT Device Management](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#command-iot-namespace). Para acessar informações sobre o uso desse recurso para AWS IoT FleetWise, consulte [Comandos remotos](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html).
Você é o único responsável por implantar comandos de forma segura e compatível com as leis aplicáveis. Para ter mais informações sobre suas responsabilidades, consulte os [Termos de Serviço da AWS para Serviços da AWS IoT](https://aws.amazon.com/service-terms/).
Use AWS IoT Device Management Comandos para enviar uma instrução da nuvem para um dispositivo conectado AWS IoT a. Os comandos têm como alvo um dispositivo por vez e podem ser usados para aplicativos de baixa latência e alto rendimento, como recuperar registros do lado do dispositivo ou iniciar uma alteração no estado do dispositivo.
O *comando* é um recurso reutilizável gerenciado pelo. AWS IoT Device Management Ele contém configurações que são aplicadas antes de serem publicadas no dispositivo. Você pode predefinir um conjunto de comandos para casos de uso específicos, como acender uma lâmpada ou destrancar a porta de um veículo.
O recurso AWS IoT Comandos permite que você:
+ Crie modelos de comando reutilizáveis com cargas estáticas ou dinâmicas e execute-os em dispositivos específicos.
+ Dispositivos de destino registrados como AWS IoT itens ou clientes MQTT não registrados.
+ Execute vários comandos simultaneamente no mesmo dispositivo.
+ Ative as notificações de eventos e acompanhe o status da execução à medida que os dispositivos processam os comandos.
Os tópicos a seguir mostram como criar comandos, enviá-los ao seu dispositivo e recuperar o status informado pelo dispositivo.
**Topics**
+ [Início rápido](iot-commands-quickstart.md)
+ [Conceitos e status de comandos](iot-remote-command-concepts.md)
+ [Fluxo de trabalho de comandos de alto nível](iot-remote-command-workflow.md)
+ [Criar e gerenciar comandos](iot-remote-command-create-manage.md)
+ [Iniciar e monitorar execuções de comando](iot-remote-command-execution-start-monitor.md)
+ [Suspender um recurso de comando](iot-remote-command-deprecate.md)
# Início rápido
Conclua estas etapas para enviar seu primeiro comando:
1. **Pré-requisitos** - Certifique-se de estar integrado ao IoT Core, a um dispositivo conectado ao IoT Core, às permissões do IAM para operações da API Commands e a uma biblioteca de cliente MQTT instalada em seu dispositivo.
1. **Crie um comando** - Defina um comando com uma carga estática ou um modelo de carga que especifique as ações do dispositivo. Consulte [Criar um recurso de comando](iot-remote-command-create-manage.md#iot-remote-command-create).
1. **Identifique seu dispositivo** - Registre seu dispositivo como uma coisa de IoT ou anote o ID do cliente MQTT. Consulte [Considerações sobre dispositivos de destino](iot-remote-command-execution-start-monitor.md#iot-command-execution-target).
1. **Configurar permissões** — configure políticas do IAM para que seu dispositivo receba comandos e publique respostas.
1. **Inscrever-se em tópicos** - configure seu dispositivo para assinar tópicos de solicitação e resposta de comandos. Consulte [Escolher o dispositivo de destino para os comandos e assinar os tópicos do MQTT](iot-remote-command-workflow.md#command-choose-target).
1. **Execute o comando** - Inicie a execução do comando no dispositivo de destino. Consulte [Iniciar uma execução de comandoIniciar uma execução de comando (console)Iniciar uma execução de comando (AWS CLI)](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-start).
**Casos de uso comuns:**
+ *Diagnóstico remoto* - recupere registros, execute diagnósticos, verifique a integridade do dispositivo
+ *Atualizações de configuração* - Alterar configurações, atualizar parâmetros, alternar recursos
+ *Controle do dispositivo* -Lock/unlock, power on/off, mudanças de modo
# Conceitos e status de comandos
Use AWS IoT Comandos para enviar instruções da nuvem para os dispositivos conectados. Para usar esse atributo:
1. Crie um comando com uma carga contendo as configurações necessárias para execução no dispositivo.
1. Especifique o dispositivo de destino que receberá a carga e executará as ações.
1. Execute o comando no dispositivo de destino e recupere as informações de status. Para solucionar problemas, consulte CloudWatch os registros.
Para obter mais informações sobre esse fluxo de trabalho, consulte [Fluxo de trabalho de comandos de alto nível](iot-remote-command-workflow.md).
**Topics**
+ [Conceitos de chaves de comandos](#iot-command-concepts)
+ [Estados de comando](#iot-command-states)
+ [Status de execução do comando](#iot-command-execution-status)
## Conceitos de chaves de comandos
Os conceitos-chave a seguir ajudam você a entender o recurso Comandos. Os termos são usados de forma consistente em toda esta documentação:
+ *Comando* - Um modelo reutilizável que define as instruções do dispositivo
+ *Execução* - Uma instância de um comando em execução em um dispositivo
+ *Nome da coisa* - Identificador para dispositivos registrados no registro de IoT
+ *ID do cliente* - identificador MQTT para dispositivos não registrados
+ *Carga útil* - Os dados da instrução enviados aos dispositivos
+ *Tópico* - Canal MQTT para comunicação de comando
**Comandos**
Os comandos são instruções enviadas da nuvem para seus dispositivos de IoT como mensagens MQTT. Depois de receber a carga, os dispositivos processam as instruções e realizam as ações correspondentes, como modificar as configurações, transmitir leituras do sensor ou carregar registros. Os dispositivos então retornam os resultados para a nuvem, permitindo monitoramento e controle remotos.
**Namespace**
Ao criar um comando, especifique seu namespace. Para AWS IoT Device Management comandos, use o `AWS-IoT` namespace padrão e forneça uma carga ou um payloadTemplate. Para AWS IoT FleetWise comandos, use o `AWS-IoT-FleetWise` namespace. Para obter mais informações, consulte [Comandos remotos](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) no *Guia do AWS IoT FleetWise desenvolvedor*.
**Carga útil**
Ao criar um comando, forneça uma carga estática que defina as ações que o dispositivo deve realizar. A carga pode usar qualquer formato compatível. Para garantir que os dispositivos interpretem corretamente a carga, recomendamos especificar o tipo de formato da carga útil. Os dispositivos que usam o MQTT5 protocolo podem seguir o padrão MQTT para identificar o formato. Os indicadores de formato para JSON ou CBOR estão disponíveis no tópico de solicitação de comandos.
**Modelo de carga**
Um modelo de carga útil define uma carga de comando com espaços reservados que geram cargas diferentes em tempo de execução com base nos valores de parâmetros fornecidos por você. Por exemplo, em vez de criar cargas separadas para diferentes valores de temperatura, crie um modelo com um espaço reservado de temperatura e especifique o valor durante a execução. Isso elimina a manutenção de várias cargas úteis semelhantes.
**Dispositivo de destino**
Para executar um comando, especifique um dispositivo de destino usando o nome do item (para dispositivos registrados com AWS IoT) ou o ID do cliente MQTT (para dispositivos não registrados). O ID do cliente é um identificador exclusivo definido no [MQTT](mqtt.md) protocolo usado para conectar dispositivos AWS IoT a. Para obter detalhes, consulte [Considerações sobre dispositivos de destino](iot-remote-command-execution-start-monitor.md#iot-command-execution-target).
**Tópicos de comandos**
Antes de executar um comando, os dispositivos devem se inscrever no tópico de solicitação de comandos. Quando você executa um comando, a carga útil é enviada para o dispositivo neste tópico. Após a execução, os dispositivos publicam os resultados e o status no tópico de resposta dos comandos. Para obter mais informações, consulte [Tópicos de comandos](reserved-topics.md#reserved-topics-commands).
**Execução de comandos**
Uma execução é uma instância de um comando em execução em um dispositivo de destino. Quando você inicia uma execução, a carga é entregue ao dispositivo e uma ID de execução exclusiva é gerada. O dispositivo executa o comando e relata o progresso para AWS IoT. A lógica do lado do dispositivo determina o comportamento de execução e os relatórios de status para tópicos reservados.
### Condições de valor do parâmetro
Ao criar comandos com modelos de carga útil, defina as condições de valor para validar os valores dos parâmetros antes da execução. As condições de valor garantem que os parâmetros atendam aos requisitos, evitando execuções inválidas.
**Operadores suportados por [CommandParameterValue](https://docs.aws.amazon.com//iot/latest/apireference/API_CommandParameterValue.html)tipo**
**Tipos numéricos (INTEGER, LONG, DOUBLE, UNSIGNEDLONG)**
+ `EQUALS`- O valor deve ser igual ao número especificado
+ `NOT_EQUALS`- O valor não deve ser igual ao número especificado
+ `GREATER_THAN`- O valor deve ser maior que o número especificado
+ `GREATER_THAN_EQUALS`- O valor deve ser maior ou igual ao número especificado
+ `LESS_THAN`- O valor deve ser menor que o número especificado
+ `LESS_THAN_EQUALS`- O valor deve ser menor ou igual ao número especificado
+ `IN_RANGE`- O valor deve estar dentro do intervalo especificado (inclusive)
+ `NOT_IN_RANGE`- O valor deve estar fora do intervalo especificado (inclusive)
+ `IN_SET`- O valor deve corresponder a um dos números especificados
+ `NOT_IN_SET`- O valor não deve corresponder a nenhum dos números especificados
**Tipo de string (STRING)**
+ `EQUALS`- O valor deve ser igual à string especificada
+ `NOT_EQUALS`- O valor não deve ser igual à string especificada
+ `IN_SET`- O valor deve corresponder a uma das cadeias de caracteres especificadas
+ `NOT_IN_SET`- O valor não deve corresponder a nenhuma das strings especificadas
**Tipo booleano**
+ As condições de valor não são suportadas
**Tipo binário**
+ As condições de valor não são suportadas
**Exemplo: comando de controle de temperatura**
```
{
"commandId": "SetTemperature",
"namespace": "AWS-IoT",
"payloadTemplate": "{\"temperature\": \"${aws:iot:commandexecution::parameter:temperature}\"}",
"parameters": [
{
"name": "temperature",
"type": "INTEGER",
"valueConditions": [
{
"comparisonOperator": "IN_RANGE",
"operand": {
"numberRange": {
"min": "60",
"max": "80"
}
}
}
]
}
]
}
```
Neste exemplo, o `temperature` parâmetro deve estar entre 60 e 80 (inclusive). Solicitações de execução com valores fora desse intervalo falham na validação.
**nota**
[As condições de valor são avaliadas na invocação da StartCommandExecution API.](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartCommandExecution.html) As validações com falha retornam um erro e impedem a criação da execução.
### Prioridade e avaliação do valor do parâmetro
Ao iniciar as execuções de comandos com modelos de carga útil, os valores dos parâmetros são resolvidos usando a seguinte prioridade:
1. **Parâmetros da solicitação de execução** - Os valores fornecidos na `StartCommandExecution` solicitação têm a maior prioridade
1. **Valores padrão do comando** - Se um parâmetro não for fornecido na solicitação de execução, o parâmetro `defaultValue` será usado
1. **Sem valor** - Se nenhum for fornecido, a execução falhará como parâmetro necessário para gerar a solicitação de execução
As condições de valor são avaliadas no valor final do parâmetro derivado acima na prioridade e antes da criação da execução. Se a validação falhar, a solicitação de execução retornará um erro.
**Exemplo: SetTemperature comando com `defaultValue`**
```
{
"parameters": [
{
"name": "temperature",
"type": "INTEGER",
"defaultValue": {"I": 72},
"valueConditions": [
{
"comparisonOperator": "IN_RANGE",
"operand": {"numberRange": {"min": "60", "max": "80"}}
}
]
}
]
}
```
Ao iniciar a execução:
+ Se você fornecer `"temperature": {"I": 75}` na solicitação, 75 será usado
+ Se você omitir o parâmetro de temperatura, o valor padrão 72 será usado
+ Ambos os valores são validados em relação à condição de intervalo [60,80]
## Estados de comando
*Os comandos no seu Conta da AWS podem estar em um dos três estados: *Disponível, *Obsoleto** ou Exclusão pendente.*
**Disponível**
Após a criação bem-sucedida, um comando fica no estado Disponível e pode ser executado em dispositivos.
**Preterido**
Marque comandos para suspensão de uso quando não forem mais necessários. Comandos obsoletos não podem iniciar novas execuções, mas as execuções pendentes continuam sendo concluídas. Para habilitar novas execuções, restaure o comando para o estado Disponível.
**Exclusão pendente**
Quando você marca um comando para exclusão, ele é excluído automaticamente se for descontinuado por mais tempo do que o tempo limite máximo (padrão: 12 horas). Essa ação é permanente. Se não for preterido ou for preterido por menos do que o tempo limite, o comando entrará no estado de exclusão pendente e será removido após o tempo limite expirar.
## Status de execução do comando
Quando você inicia uma execução em um dispositivo de destino, ela entra no `CREATED` status e pode fazer a transição para outros status com base nos relatórios do dispositivo. Você pode recuperar informações de status e acompanhar as execuções.
**nota**
Você pode executar vários comandos simultaneamente em um dispositivo. Use o controle de concorrência para limitar as execuções por dispositivo e evitar sobrecargas. Para obter o máximo de execuções simultâneas por dispositivo, consulte cotas de [AWS IoT Device Management comandos](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits).
A tabela a seguir mostra os status de execução e suas transições com base no progresso da execução.
**Status e origem da execução do comando**
| Status de execução do comando | Iniciado pelo dispositivo/nuvem? | Execução do terminal? | Transições de status permitidas |
| --- | --- | --- | --- |
| CREATED | Nuvem | Não | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/iot-remote-command-concepts.html) |
| IN\$1PROGRESS | Dispositivo | Não | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/iot-remote-command-concepts.html) |
| TIMED\$1OUT | Dispositivo e nuvem | Não | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/iot-remote-command-concepts.html) |
| SUCCEEDED | Dispositivo | Sim | Não aplicável |
| FAILED | Dispositivo | Sim | Não aplicável |
| REJECTED | Dispositivo | Sim | Não aplicável |
Os dispositivos podem publicar atualizações de status e resultados a qualquer momento usando comandos reservados aos tópicos do MQTT. Para fornecer contexto adicional, os dispositivos podem usar `reasonCode` `reasonDescription` campos no `statusReason` objeto.
O diagrama a seguir mostra as transições de status de execução.
![\[Imagem mostrando como o status de execução de um comando muda entre vários status.\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/images/command-execution-status-transitions.png)
**nota**
Quando não AWS IoT detecta nenhuma resposta do dispositivo dentro do período de tempo limite, ele é definido `TIMED_OUT` como um status temporário, permitindo novas tentativas e alterações de estado. Se o seu dispositivo reportar explicitamente`TIMED_OUT`, isso se tornará um status de terminal sem mais transições. Para obter mais informações, consulte [Execuções de comandos não terminais](#iot-command-execution-status-nonterminal).
As seções a seguir descrevem as execuções terminais e não terminais e seus status.
**Topics**
+ [Execuções de comandos não terminais](#iot-command-execution-status-nonterminal)
+ [Execuções de comandos terminais](#iot-command-execution-status-terminal)
### Execuções de comandos não terminais
Uma execução não é terminal se puder aceitar atualizações de dispositivos. *As execuções não terminais são consideradas ativas.* Os seguintes status não são terminais:
+
**CREATED**
Quando você inicia uma execução no AWS IoT console ou usa a `StartCommandExecution` API, as solicitações bem-sucedidas mudam o status para`CREATED`. A partir desse status, as execuções podem passar para qualquer outro status não terminal ou terminal.
+
**IN\$1PROGRESS**
Depois de receber a carga, os dispositivos podem começar a executar instruções e realizar ações especificadas. Durante a execução, os dispositivos podem publicar respostas ao tópico de resposta dos comandos e atualizar o status para`IN_PROGRESS`. A partir de`IN_PROGRESS`, as execuções podem fazer a transição para qualquer status terminal ou não terminal, exceto. `CREATED`
**nota**
A `UpdateCommandExecution` API pode ser invocada várias vezes com `IN_PROGRESS` status. Especifique detalhes adicionais de execução usando o `statusReason` objeto.
+
**TEMPORIZADO\$1LIMITE**
Tanto a nuvem quanto o dispositivo podem acionar esse status. As execuções `CREATED` ou `IN_PROGRESS` o status podem mudar `TIMED_OUT` para pelos seguintes motivos:
+ Depois de enviar o comando, um cronômetro é iniciado. Se o dispositivo não responder dentro do período especificado, o status da nuvem mudará para`TIMED_OUT`. Nesse caso, a execução não é terminal.
+ O dispositivo pode substituir o status de qualquer terminal ou relatar um tempo limite e definir o status como. `TIMED_OUT` Nesse caso, o status permanece`TIMED_OUT`, mas os campos do `StatusReason` objeto mudam com base nas informações do dispositivo. A execução se torna terminal.
Para obter mais informações, consulte [Valor do tempo limite e status de execução `TIMED_OUT`](iot-remote-command-execution-start-monitor.md#iot-command-execution-timeout-status).
### Execuções de comandos terminais
Uma execução se torna terminal quando não aceita mais atualizações de dispositivos. Os status a seguir são terminais. As execuções podem fazer a transição para status de terminal a partir de qualquer status que não seja terminal:`CREATED`,, `IN_PROGRESS` ou. `TIMED_OUT`
+
**SUCCEEDED**
Se o dispositivo concluir com êxito a execução, ele poderá publicar uma resposta ao tópico de resposta do comando e atualizar o status para`SUCCEEDED`.
+
**FAILED**
Quando um dispositivo não consegue concluir a execução, ele pode publicar uma resposta ao tópico de resposta do comando e atualizar o status para`FAILED`. Use os `reasonDescription` campos `reasonCode` e no `statusReason` objeto, ou CloudWatch registros, para solucionar falhas.
+
**REJEITADA**
Quando um dispositivo recebe uma solicitação inválida ou incompatível, ele pode invocar a `UpdateCommandExecution` API com status. `REJECTED` Use os `reasonDescription` campos `reasonCode` e no `statusReason` objeto, ou CloudWatch registros, para solucionar problemas.
# Fluxo de trabalho de comandos de alto nível
Esse fluxo de trabalho mostra como os dispositivos interagem com AWS IoT Device Management os comandos. Todas as solicitações da API HTTP usam [credenciais Sigv4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) para assinatura.
![\[Visão geral do fluxo de trabalho de alto nível do comando do AWS IoT Device Management dispositivo.\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/images/device-command-workflow.png)
**Topics**
+ [Criar e gerenciar comandos](#command-create-command)
+ [Escolher o dispositivo de destino para os comandos e assinar os tópicos do MQTT](#command-choose-target)
+ [Iniciar e monitorar as execuções de comando para o dispositivo de destino](#command-command-executions)
+ [(Opcional) Habilitar notificações para eventos de comandos](#iot-remote-command-commands-notifications)
## Criar e gerenciar comandos
Para criar e gerenciar comandos para seus dispositivos, realize as etapas a seguir.
1.
**Criar um recurso de comando**
Crie um [comando no Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) ou usando a [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html)API.
1.
**Especificar a carga útil**
Forneça uma carga em qualquer formato. Especifique o tipo de conteúdo para garantir a interpretação correta do dispositivo.
Para comandos dinâmicos com modelos de carga útil, a carga útil final é gerada em tempo de execução usando os parâmetros fornecidos. Os modelos oferecem suporte somente ao formato JSON, mas a carga gerada pode ser enviada como JSON ou CBOR.
1.
**(Opcional) Gerenciar os comandos criados**
Atualize o nome de exibição e a descrição após a criação. Marque os comandos como obsoletos quando não forem mais necessários ou exclua-os permanentemente. Para modificar as informações do Payload, crie um novo Comando.
## Escolher o dispositivo de destino para os comandos e assinar os tópicos do MQTT
Escolha seu dispositivo de destino e configure os tópicos do MQTT para receber comandos e publicar respostas.
1.
**Escolher o dispositivo de destino para o comando**
Escolha um dispositivo de destino para receber e executar o Comando. Use um nome Thing para dispositivos registrados ou uma ID de cliente para dispositivos não registrados. Para obter mais informações, consulte [Considerações sobre dispositivos de destino](iot-remote-command-execution-start-monitor.md#iot-command-execution-target).
1.
**Configurar a política AWS IoT do dispositivo**
Configure uma política do IAM concedendo permissões para receber execuções e publicar atualizações. Consulte [Exemplo de política do IAM](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-update-policy) para obter exemplos de políticas.
1.
**Estabelecer uma conexão do MQTT**
Conecte dispositivos ao agente de mensagens e assine os tópicos de solicitação e resposta. Os dispositivos precisam de `iot:Connect` permissão. Encontre seu endpoint do plano de dados usando o comando da `DescribeEndpoint` API ou da `describe-endpoint` CLI:
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
A execução desse comando exibe o endpoint do plano de dados específico da conta, conforme mostrado abaixo.
```
account-specific-prefix.iot.region.amazonaws.com
```
1.
**Inscreva-se nos tópicos de comandos**
Inscreva-se no tópico de solicitação de comandos. Quando você inicia uma execução, o agente de mensagens publica a carga neste tópico. Seu dispositivo recebe e processa o Comando.
(Opcional) Inscreva-se nos tópicos de resposta (`accepted`ou`rejected`) para receber a confirmação se o serviço de nuvem aceitou ou rejeitou a resposta do dispositivo.
Neste exemplo, substitua:
+ *``* por `thing` ou `client` dependendo de o dispositivo que você está considerando ter sido registrado como uma coisa da IoT ou especificado como um cliente do MQTT.
+ *``* pelo identificador exclusivo do seu dispositivo de destino. Esse ID pode ser o exclusivo do cliente do MQTT ou o nome de uma coisa.
**nota**
Se o tipo de carga não for JSON ou CBOR, o ** campo pode não estar presente no tópico de solicitação de comandos. Para obter o formato da carga útil, recomendamos que você use MQTT5 para obter as informações de formato dos cabeçalhos das mensagens do MQTT. Para obter mais informações, consulte [Tópicos de comandos](reserved-topics.md#reserved-topics-commands).
```
$aws/commands///executions/+/request/
$aws/commands///executions/+/response/accepted/
$aws/commands///executions/+/response/rejected/
```
## Iniciar e monitorar as execuções de comando para o dispositivo de destino
Depois de criar os comandos e especificar os destinos deles, você pode iniciar a execução no dispositivo de destino realizando as etapas a seguir.
1.
**Iniciar a execução do comando no dispositivo de destino**
Inicie a execução no [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) ou usando a `StartCommandExecution` API com o endpoint específico da sua conta. Use `iot:Data-ATS` para pilha dupla (IPv4/IPv6) ou `iot:Jobs` somente para. IPv4
A API publica a carga no tópico de solicitação de comandos.
**nota**
Se o dispositivo estiver off-line e usar sessões persistentes do MQTT, o Comando aguarda no agente de mensagens. Quando o dispositivo se reconecta antes do tempo limite, ele pode processar o Comando e publicar os resultados. Se o tempo limite expirar, a execução expirará e a carga será descartada.
1.
**Atualizar o resultado da execução do comando**
O dispositivo recebe a carga, processa o comando, executa as ações especificadas e publica os resultados no tópico de resposta dos comandos usando a API baseada em `UpdateCommandExecution` MQTT. Se estiver inscrito em tópicos aceitos e rejeitados, o dispositivo receberá a confirmação se o serviço de nuvem aceitou ou rejeitou a resposta.
Dependendo do que você especificou no tópico da solicitação, ** podem ser coisas ou clientes, e ** pode ser o nome do seu AWS IoT item ou o ID do cliente MQTT.
**nota**
Só ** pode ser JSON ou CBOR no tópico de resposta dos comandos.
```
$aws/commands///executions//response/
```
1.
**(Opcional) Recuperar o resultado da execução do comando**
Recupere os resultados da execução do AWS IoT console ou usando`GetCommandExecution`. O dispositivo deve publicar os resultados no tópico de resposta dos comandos para obter as informações mais recentes. Veja detalhes adicionais, incluindo hora da última atualização, resultado e hora de conclusão.
## (Opcional) Habilitar notificações para eventos de comandos
Inscreva-se nos eventos de Commands para receber notificações quando o status de execução mudar. Para obter informações detalhadas sobre eventos de execução de comandos, incluindo o formato da mensagem do evento e os atributos da carga útil, consulte[Eventos de execução de comandos](command-events.md).
1.
**Criar uma regra de tópico**
Inscreva-se no tópico de eventos de Comandos para receber notificações de mudança de status. Crie uma regra de tópico para rotear dados do dispositivo para outros AWS IoT serviços AWS Lambda, como Amazon SQS e AWS Step Functions, usando o AWS IoT console ou. [Criação de uma AWS IoT regra](iot-create-rule.md)
Neste exemplo, substitua `` pelo identificador do comando para o qual você deseja receber notificações e `` pelo status da execução do comando.
```
$aws/events/commandExecution//
```
**nota**
Para receber notificações de todos os comandos e os status de execução deles, você pode usar caracteres curinga e assinar o tópico a seguir.
```
$aws/events/commandExecution/+/#
```
1.
**Receber e processar eventos de comandos**
Gerencie as notificações push de comandos e crie aplicativos usando os eventos inscritos.
O código a seguir mostra um exemplo de carga útil para as notificações de eventos de comandos que você receberá.
```
{
"executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554",
"status":"FAILED",
"statusReason": {
"reasonCode": "DEVICE_TOO_BUSY",
"reasonDescription": ""
},
"eventType": "COMMAND_EXECUTION",
"commandArn":"arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086",
"targetArn":"arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd",
"timestamp":1717708862107
}
```
# Criar e gerenciar comandos
Use AWS IoT Device Management comandos para configurar ações remotas reutilizáveis ou enviar instruções imediatas aos dispositivos. Crie e gerencie comandos no AWS IoT console ou usando AWS CLI o.
**Topics**
+ [Criar um recurso de comando](#iot-remote-command-create)
+ [Recuperar informações sobre um comando](#iot-remote-command-get)
+ [Liste os comandos em seu Conta da AWS](#iot-remote-command-list)
+ [Atualizar um recurso de comando](#iot-remote-command-update)
+ [Suspender ou restaurar um recurso de comando](#iot-remote-command-deprecatecmd)
+ [Excluir um recurso de comando](#iot-remote-command-delete)
## Criar um recurso de comando
Forneça as seguintes informações ao criar um Comando:
+
**Informações gerais**
Forneça um ID de comando exclusivo para identificar o comando ao executá-lo nos dispositivos de destino. Opcionalmente, especifique um nome de exibição, uma descrição e tags para gerenciamento.
+ **Carga útil**
Para comandos estáticos, forneça uma carga que defina as ações do dispositivo. Especifique o tipo de formato do Payload para a interpretação correta do dispositivo.
Para comandos dinâmicos, consulte o atributo do modelo Payload.
+ **Modelo de carga**
Para comandos dinâmicos, forneça um PayloadTemplate com espaços reservados e parâmetros. Opcionalmente, forneça `defaultValue` e condicione. AWS IoT Device Management Os comandos substituem os espaços reservados em tempo de execução. Os parâmetros ausentes usam seu DefaultValue. Todos os valores devem satisfazer as condições definidas.
Os seguintes tipos de espaço reservado com distinção entre maiúsculas e minúsculas são compatíveis:
+ `${aws:iot:commandexecution::parameter:parameter1}`— Um espaço reservado para o valor de um parâmetro com o nome`parameter1`.
+ `${aws:iot:commandexecution::executionTimeoutSec}`— Um espaço reservado para o parâmetro de tempo limite de execução do comando fornecido em tempo de execução.
### Tópicos de carga útil e comandos
Comandos reservados Os tópicos usam um formato baseado no tipo de formato Payload.
+ Para `application/json` nossos tipos de `application/cbor` conteúdo, use este tópico de solicitação:
```
$aws/commands///executions/+/request/
```
+ Para outros tipos de conteúdo ou formato não especificado, use este tópico de solicitação. O formato Payload aparece no cabeçalho da mensagem MQTT.
```
$aws/commands///executions/+/request
```
O tópico de resposta dos comandos usa `json` ou `cbor` formata independentemente do tipo de carga útil. **deve ser `json` ou`cbor`:
```
$aws/commands///executions//response/
```
### Criar um recurso de comando (console)
As seções a seguir descrevem as considerações sobre o formato de carga útil e a criação de comandos a partir do console.
**Topics**
+ [Formato de carga útil de comando estático](#iot-commands-payload-format)
+ [Formato de carga útil de comando dinâmico](#iot-commands-dynamic-payload-format)
+ [Como criar um comando (console)](#iot-commands-console-how)
#### Formato de carga útil de comando estático
O Payload suporta qualquer formato de até 32 KB. Especifique o tipo de formato do Payload para uma interpretação segura e correta do dispositivo.
Especifique o tipo de formato de carga usando o `type/subtype` formato (por exemplo, `application/json` ou`application/cbor`). Padrão: `application/octet-stream`. Consulte [Tipos comuns de MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types) para ver os formatos compatíveis.
#### Formato de carga útil de comando dinâmico
O PayloadTemplate deve ser um JSON válido com pelo menos um espaço reservado, de até 32 KB.
Para o `AwsJsonSubstitution` pré-processador, o AWS IoT Device Management Commands envia notificações no formato JSON ou CBOR com base na configuração do pré-processador.
#### Como criar um comando (console)
Para criar um comando a partir do console, acesse o [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) e siga estas etapas:
1. Escolha **Criar comando**.
1. Especifique um ID de comando exclusivo.
1. (Opcional) Especifique o nome de exibição, a descrição e as tags.
1. Faça upload do arquivo Payload contendo as ações do dispositivo. Especifique o tipo de formato do Payload para a interpretação correta do dispositivo.
1. (Opcional) Para modelos de carga útil JSON com espaços reservados, os parâmetros são pré-preenchidos na tabela embutida para edição.
1. (Opcional) Configure o tipo de valor do parâmetro (obrigatório), o valor padrão e as condições.
1. Escolha **Criar comando**.
### Criar um recurso de comando (CLI)
Use o comando [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html)da API ou da [https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html)CLI para criar um comando.
**Topics**
+ [Carga útil do comando](#iot-commands-payload)
+ [Exemplo de política do IAM](#iot-remote-command-create-iam)
+ [Exemplo de criação de comando estático](#iot-remote-command-create-example)
+ [Exemplo de criação de comando dinâmico](#iot-remote-dynamic-command-create-example)
#### Carga útil do comando
Forneça uma carga estática ou um modelo de carga útil. As cargas estáticas são codificadas em base64. Para modelos de carga útil, a carga útil final é gerada em tempo de execução usando valores de parâmetros. Os dispositivos processam a carga e executam ações especificadas. Especifique o tipo de conteúdo do Payload para a recepção correta do dispositivo.
**nota**
As cargas não podem ser modificadas após a criação do Comando. Crie um novo comando para modificar a carga.
#### Exemplo de política do IAM
Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação `CreateCommand`.
Neste exemplo, substitua:
+ `region` por sua Região da AWS, como `us-east-1`.
+ `account-id` pelo número de sua Conta da AWS , como `123456789012`.
+ `command-id`com um identificador exclusivo para seu ID de AWS IoT comando, como`LockDoor`. Se quiser enviar mais de um comando, você poderá especificá-los na seção *Recursos* na política do IAM.
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:CreateCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
}
}
```
#### Exemplo de criação de comando estático
O exemplo a seguir mostra como você pode criar um comando estático. Dependendo da sua aplicação, substitua:
+ *``* por um identificador exclusivo para o comando. Por exemplo, para trancar a porta da sua casa, você pode especificar*`LockDoor`*. Recomendamos usar o UUID. Você também pode usar caracteres alfanuméricos, “-” e “\$1”.
+ (Opcional) *``* e *``*, que são campos opcionais que você pode usar para fornecer um nome amigável e uma descrição significativa para o comando, como *`Lock the doors of my home`*.
+ `namespace`, que você pode usar para especificar o namespace do comando. Deve ser `AWS-IoT`. Para obter informações sobre como usar esse recurso para AWS IoT FleetWise, consulte [Comandos remotos](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html)
+ `payload` contém informações sobre a carga útil que você deseja usar ao executar o comando e seu tipo de conteúdo.
```
aws iot create-command \
--command-id \
--display-name \
--description \
--namespace AWS-IoT \
--payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}'
```
A execução desse comando gera uma resposta que contém o ID e o ARN (nome do recurso da Amazon) do comando. Por exemplo, se você especificou o comando `LockDoor` durante a criação, o trecho seguinte mostra um exemplo de saída da execução dele.
```
{
"commandId": "LockDoor",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor"
}
```
#### Exemplo de criação de comando dinâmico
O exemplo a seguir mostra como você pode criar um comando dinâmico. Dependendo da sua aplicação, substitua:
+ *``* por um identificador exclusivo para o comando. Por exemplo, para definir o status da energia da luz, você pode especificar*`Light_Power_Status`*. Recomendamos usar o UUID. Você também pode usar caracteres alfanuméricos, “-” e “\$1”.
+ (Opcional) *``* e *``*, que são campos opcionais que você pode usar para fornecer um nome amigável e uma descrição significativa para o comando, como *`Turn a light ON or OFF`*.
+ `namespace`, que você pode usar para especificar o namespace do comando. Deve ser `AWS-IoT`. Para obter informações sobre como usar esse recurso para AWS IoT FleetWise, consulte [Comandos remotos](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html)
+ `payloadTemplate`contém o modelo de carga de reprodução formatado em JSON com espaços reservados.
+ `preprocessor`contém a configuração do pré-processador que determina como o PayloadTemplate deve ser processado.
+ `mandatoryParameter`contém os parâmetros correspondentes aos espaços reservados no PayloadTemplate, seu tipo, valores padrão e condições.
```
aws iot create-command \
--command-id Light_Power_Status \
--description "Turn a light ON or OFF" \
--namespace AWS-IoT \
--payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \
--preprocessor awsJsonSubstitution={outputFormat=JSON} \
--mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]"
```
A execução desse comando gera uma resposta que contém o ID e o ARN (nome do recurso da Amazon) do comando. Por exemplo, se você especificou o comando `Light_Power_Status` durante a criação, o trecho seguinte mostra um exemplo de saída da execução dele.
```
{
"commandId": "Light_Power_Status",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status"
}
```
## Recuperar informações sobre um comando
Depois de criar um comando, você pode recuperar informações sobre ele no console da AWS IoT e usando a AWS CLI. Você pode acessar as informações a seguir.
+ O ID do comando, o nome do recurso da Amazon (ARN), qualquer nome de exibição e a descrição que você especificou para o comando.
+ O estado que indica se um comando está disponível para execução no dispositivo de destino, ou se ele está sendo suspenso ou foi excluído.
+ A carga ou o PayloadTemplate que você forneceu.
+ O pré-processador que você forneceu.
+ Os parâmetros obrigatórios que você forneceu.
+ A hora em que o comando foi criado e atualizado pela última vez.
### Recuperar um recurso de comando (console)
Para recuperar um comando do console, acesse o [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) do AWS IoT console e escolha o comando que você criou para ver seus detalhes.
Além dos detalhes do comando, você pode ver o histórico dele, que fornece informações sobre as execuções no dispositivo de destino. Depois de executar esse comando no dispositivo, você encontrará informações sobre as execuções nessa guia.
### Recuperar um recurso de comando (CLI)
Use a operação da API do plano de controle [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html)HTTP ou o [https://docs.aws.amazon.com/cli/latest/reference/get-command.html](https://docs.aws.amazon.com/cli/latest/reference/get-command.html) AWS CLI comando para recuperar informações sobre um recurso de comando. Você já deve ter criado o comando usando a solicitação de API `CreateCommand` ou a CLI `create-command`.
#### Exemplo de política do IAM
Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação `GetCommand`.
Neste exemplo, substitua:
+ `region` por sua Região da AWS, como `us-east-1`.
+ `account-id` pelo número de sua Conta da AWS , como `123456789023`.
+ `command-id`com seu identificador de comando AWS IoT exclusivo, como `LockDoor` ou`Light_Power_Status`. Se quiser recuperar mais de um comando, você poderá especificá-los na seção *Recurso* na política do IAM.
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:GetCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
}
}
```
#### Recuperar um exemplo de comando (AWS CLI)
O exemplo a seguir mostra como recuperar informações sobre um comando usando o. `get-command` AWS CLI Dependendo da sua aplicação, substitua *``* pelo identificador do comando para o qual você deseja recuperar informações. Você pode acessar essas informações na resposta da CLI `create-command`.
```
aws iot get-command --command-id
```
A execução desse comando gera uma resposta com informações sobre ele, bem como a carga útil e a hora em que ele foi criado e atualizado pela última vez. Ela também fornece informações que indicam se um comando foi suspenso ou está sendo excluído.
O código a seguir mostra um exemplo de resposta.
```
{
"commandId": "LockDoor",
"commandArn": "arn:aws:iot:::command/LockDoor",
"namespace": "AWS-IoT",
"payload":{
"content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=",
"contentType": "application/json"
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
"deprecated": false,
"pendingDeletion": false
}
```
## Liste os comandos em seu Conta da AWS
Depois de criar comandos, você pode visualizá-los na sua conta. Na lista, você encontrará informações sobre:
+ O ID dos comandos e todos os nomes de exibição que você especificou para eles.
+ O nome do recurso da Amazon (ARN) dos comandos.
+ O estado que indica se os comandos estão disponíveis para execução no dispositivo de destino ou se foram suspensos.
**nota**
A lista não mostra os que estão sendo excluídos da sua conta. Se os comandos estiverem com a exclusão pendente, você ainda poderá visualizar os respectivos detalhes usando o ID do comando.
+ A hora em que os comandos foram criados e atualizados pela última vez.
### Listar comandos na sua conta (console)
No AWS IoT console, você pode encontrar a lista de comandos que você criou e seus detalhes acessando o [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub).
### Listar comandos em sua conta (CLI)
Para listar os comandos que você criou, use a operação de API [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html) ou a CLI [https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html).
#### Exemplo de política do IAM
Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação `ListCommands`.
Neste exemplo, substitua:
+ `region` por sua Região da AWS, como `us-east-1`.
+ `account-id` pelo número de sua Conta da AWS , como `123456789012`.
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:ListCommands",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/*"
}
}
```
#### Exemplo de como listar comandos em sua conta
O comando a seguir mostra como listar comandos em sua conta.
```
aws iot list-commands --namespace "AWS-IoT"
```
A execução desse comando gera uma resposta que contém uma lista dos comandos criados, a hora em que eles foram criados e quando foram atualizados pela última vez. Ele também fornece as informações de estado do comando, que indicam se ele foi suspenso ou se está disponível para execução no dispositivo de destino. Para acessar mais informações sobre os diferentes status e os respectivos motivos, consulte [Status de execução do comando](iot-remote-command-concepts.md#iot-command-execution-status).
## Atualizar um recurso de comando
Depois de criar um comando, você pode atualizar o nome de exibição e a descrição dele.
**nota**
Não é possível atualizar a carga útil do comando. Para atualizar essas informações ou usar uma carga útil modificada, você precisará criar outro comando.
### Atualizar um recurso de comando (console)
Para atualizar um comando do console, acesse o [Hub de Comando](https://console.aws.amazon.com/iot/home#/commandHub) do AWS IoT console e execute as etapas a seguir.
1. Para atualizar um recurso de comando existente, escolha o comando a ser atualizado e, em **Ações**, escolha **Editar**.
1. Especifique o nome de exibição e a descrição que você deseja usar e os pares de nome-valor como tags para seu comando.
1. Escolha **Editar** para salvar o comando com as novas configurações.
### Atualizar um recurso de comando (CLI)
Use a operação da API do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html)controle ou a [https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html) AWS CLI para atualizar um recurso de comando. Usando essa API, você pode:
+ Editar o nome de exibição e a descrição de um comando criado por você.
+ Suspender um recurso de comando ou restaurar um comando que já tenha sido suspenso.
#### Exemplo de política do IAM
Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação `UpdateCommand`.
Neste exemplo, substitua:
+ `region` por sua Região da AWS, como `us-east-1`.
+ `account-id` pelo número de sua Conta da AWS , como `123456789012`.
+ `command-id` pelo seu identificador de comando exclusivo da AWS IoT , como `LockDoor`. Se quiser recuperar mais de um comando, você poderá especificá-los na seção *Recurso* na política do IAM.
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:UpdateCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
}
}
```
#### Exemplos de como atualizar informações sobre um comando (AWS CLI)
O exemplo a seguir mostra como atualizar as informações sobre um comando usando o `update-command` AWS CLI comando. Para ter informações sobre como você pode usar essa API para suspender ou restaurar um recurso de comando, consulte [Atualizar um recurso de comando (CLI)](iot-remote-command-deprecate.md#iot-remote-command-deprecate-cli).
O exemplo mostra como você pode atualizar o nome de exibição e a descrição de um comando. Dependendo da sua aplicação, substitua *``* pelo identificador do comando cujas informações você deseja recuperar.
```
aws iot update-command \
--command-id
--displayname \
--description
```
A execução desse comando gera uma resposta com as informações atualizadas sobre ele e a respectiva atualização mais recente. O código a seguir mostra um exemplo de solicitação e resposta para atualizar o nome de exibição e a descrição de um comando que desliga o ar condicionado.
```
aws iot update-command \
--command-id \
--displayname \
--description
```
A execução desse comando gera a resposta a seguir.
```
{
"commandId": "LockDoor",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
"displayName": "Secondary lock door",
"description": "Locks doors to my home",
"lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00"
}
```
## Suspender ou restaurar um recurso de comando
Depois de criar um comando, se não quiser mais usá-lo, você poderá marcá-lo como suspenso. Quando você suspende um comando, todas as execuções pendentes dele continuam sendo executadas no dispositivo de destino até atingirem o status terminal. Depois que um comando for suspenso, se você quiser usá-lo para enviar uma nova execução para o dispositivo de destino, deverá restaurá-lo.
**nota**
Você não pode editar um comando suspenso nem realizar novas execuções dele. Para executar novos comandos no dispositivo, você deve restaurá-lo para que o estado do comando mude para *Disponível*.
Para acessar informações adicionais sobre a suspensão e a restauração de um comando e considerações sobre ele, consulte [Suspender um recurso de comando](iot-remote-command-deprecate.md).
## Excluir um recurso de comando
Se você não quiser mais usar um comando, poderá removê-lo permanentemente da sua conta. Se a ação de exclusão for bem-sucedida:
+ Se o comando permanecer suspenso por um período maior que o tempo limite máximo de 12 horas, ele será excluído imediatamente.
+ Se o comando não foi suspenso ou permanecer suspenso por um período menor que o valor do tempo limite máximo, ele entrará no estado `pending deletion`. Ele será removido automaticamente da sua conta após o tempo limite máximo de 12 horas.
**nota**
O comando poderá ser excluído mesmo se houver alguma execução pendente. O comando estará em um estado de exclusão pendente e será removido da sua conta automaticamente.
### Excluir um recurso de comando (console)
Para excluir um comando do console, acesse o [Hub de Comando](https://console.aws.amazon.com/iot/home#/commandHub) do AWS IoT console e execute as etapas a seguir.
1. Escolha o comando a ser excluído e, em **Ações**, selecione **Excluir**.
1. Confirme que você deseja excluir o comando e, depois, selecione **Excluir**.
O comando será marcado para exclusão e será removido permanentemente da sua conta após 12 horas.
### Excluir um recurso de comando (CLI)
Use a operação da API do plano de controle `DeleteCommand` HTTP ou o `delete-command` AWS CLI comando para excluir um recurso de comando. Se a ação de exclusão for bem-sucedida, você verá um `statusCode` HTTP de 204 ou 202, e o comando será excluído da sua conta automaticamente após o tempo limite máximo de 12 horas. O status 204 indica que o comando foi excluído.
#### Exemplo de política do IAM
Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação `DeleteCommand`.
Neste exemplo, substitua:
+ `region` por sua Região da AWS, como `us-east-1`.
+ `account-id` pelo número de sua Conta da AWS , como `123456789012`.
+ `command-id` pelo seu identificador de comando exclusivo da AWS IoT , como `LockDoor`. Se quiser recuperar mais de um comando, você poderá especificá-los na seção *Recurso* na política do IAM.
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:DeleteCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
}
}
```
#### Exemplo de como excluir um comando (AWS CLI)
Os exemplos a seguir mostram como excluir um comando usando o `delete-command` AWS CLI comando. Dependendo da sua aplicação, substitua *``* pelo identificador do comando que você está excluindo.
```
aws iot delete-command --command-id
```
Se a solicitação da API for bem-sucedida, o comando gerará um código de status 202 ou 204. Você pode usar a API `GetCommand` para verificar se o comando não existe mais na sua conta.
# Iniciar e monitorar execuções de comando
Depois de criar um comando, inicie uma execução no dispositivo de destino. O dispositivo atualiza os resultados e publica o status nos tópicos reservados do MQTT. Recupere e monitore o status de execução da sua conta.
Inicie e monitore os comandos usando o AWS IoT console ou AWS CLI.
**Topics**
+ [Iniciar uma execução de comando](#iot-remote-command-execution-start)
+ [Atualizar o resultado de uma execução de comando](#iot-remote-command-execution-update)
+ [Recuperar uma execução de comando](#iot-remote-command-execution-get)
+ [Visualizar atualizações de comandos usando o cliente de teste do MQTT](#iot-remote-command-execution-update-mqtt)
+ [Liste as execuções de comandos em seu Conta da AWS](#iot-remote-command-execution-list)
+ [Excluir uma execução de comando](#iot-remote-command-execution-delete)
## Iniciar uma execução de comando
**Importante**
Você é o único responsável por implantar comandos de forma segura e compatível com as leis aplicáveis.
Antes de iniciar uma execução, certifique-se de que:
+ Você criou um Comando no AWS IoT namespace com as informações do Payload. Ao iniciar a execução, o dispositivo processa as instruções do Payload e executa ações especificadas. Consulte [Criar um recurso de comando](iot-remote-command-create-manage.md#iot-remote-command-create) para criação de comandos.
+ Seu dispositivo se inscreveu no MQTT reservou Tópicos para Comandos. Ao iniciar a execução, as informações do Payload são publicadas nesta solicitação reservada do MQTT. Tópico:
**podem ser clientes Things ou MQTT. **é o nome da coisa ou ID do cliente. **Valores suportados: JSON e CBOR. Para obter mais informações, consulte [Tópicos de comandos](reserved-topics.md#reserved-topics-commands).
```
$aws/commands///executions/+/request/
```
Para não JSON/CBOR**, use este formato de tópico de comandos:
```
$aws/commands///executions/+/request
```
### Considerações sobre dispositivos de destino
Especifique o dispositivo de destino para receber e executar o Comando. Use um nome Thing para dispositivos registrados ou uma ID de cliente para dispositivos não registrados. Depois de receber a carga, o dispositivo executa o comando e executa as ações especificadas.
#### AWS IoT coisa
Os dispositivos de destino podem ser coisas registradas no AWS IoT registro. As coisas simplificam a pesquisa e o gerenciamento de dispositivos.
Registre dispositivos como Coisas na [página do dispositivo Connect](https://console.aws.amazon.com/iot/home#/connect-overview) ou usando [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html). Encontre coisas existentes no [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) ou usando [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html). Consulte [Gerenciando coisas com o registro](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry) para obter detalhes do registro.
#### ID de cliente
Para dispositivos não registrados, use o ID do cliente.
O ID do cliente é um identificador exclusivo que você atribui aos dispositivos. Definido no protocolo MQTT, ele contém caracteres alfanuméricos, sublinhados ou traços. Cada dispositivo conectado AWS IoT precisa de um ID de cliente exclusivo.
**nota**
Para itens registrados, o ID do cliente pode corresponder ao nome do item.
Ao segmentar uma ID de cliente específica, os dispositivos devem se conectar AWS IoT usando essa ID de cliente para receber a carga.
A ID do cliente é a ID do cliente MQTT que os dispositivos usam quando se conectam a. AWS IoT Core AWS IoT usa essa ID para identificar dispositivos e gerenciar conexões e assinaturas.
### Considerações sobre tempo limite de execução de comandos
O tempo limite especifica a duração (em segundos) para que os dispositivos forneçam resultados de execução.
Depois de criar uma execução, um cronômetro é iniciado. Se o dispositivo ficar off-line ou não reportar os resultados dentro do tempo limite, a Execução expirará com o status`TIMED_OUT`.
Padrão: 10 segundos. Máximo: 12 horas.
#### Valor do tempo limite e status de execução `TIMED_OUT`
Tanto a nuvem quanto o dispositivo podem relatar o tempo limite.
Depois de enviar o Comando, um cronômetro é iniciado. Se nenhuma resposta do dispositivo chegar dentro do tempo limite, a nuvem definirá o status de execução como `TIMED_OUT` com o código do `$NO_RESPONSE_FROM_DEVICE` motivo.
Isso ocorre quando:
+ O dispositivo ficou off-line durante a execução.
+ O dispositivo falhou ao concluir a execução dentro do tempo limite.
+ O dispositivo falhou ao relatar o status dentro do tempo limite.
Nesse caso, quando o status de execução de `TIMED_OUT` é relatado na nuvem, a execução do comando não é terminal. Seu dispositivo pode publicar uma resposta que substitui o status de qualquer um dos status do terminal:`SUCCEEDED`,, `FAILED` ou. `REJECTED` A execução do comando então se torna terminal e não aceita mais atualizações.
Seu dispositivo também pode atualizar um `TIMED_OUT` status iniciado pela nuvem relatando que ocorreu um tempo limite quando ele estava executando o comando. Nesse caso, o status de execução do comando permanece em`TIMED_OUT`, mas o `statusReason` objeto é atualizado com base nas informações relatadas pelo dispositivo. A execução do comando então se torna terminal e nenhuma atualização adicional é aceita.
#### Usar sessões persistentes do MQTT
Você pode configurar sessões persistentes do MQTT para usar com o recurso de AWS IoT Device Management comandos. Esse recurso é especialmente útil quando, por exemplo, o dispositivo fica offline e você deseja garantir que o dispositivo ainda receba o comando quando voltar a ficar on-line antes do tempo limite e execute as instruções especificadas.
Por padrão, a expiração da sessão persistente do MQTT é definida como 60 minutos. Se o tempo limite de execução do comando estiver configurado para um valor que exceda essa duração, as execuções de comandos executadas por mais de 60 minutos poderão ser rejeitadas pelo agente de mensagens e falhar. Para executar comandos com mais de 60 minutos de duração, você pode solicitar um aumento no tempo de expiração da sessão persistente.
**nota**
Para garantir que você esteja usando o recurso de sessões persistentes do MQTT corretamente, defina o sinalizador Clean Start como zero. Para acessar mais informações, consulte [MQTT persistent sessions](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-persistent-sessions).
### Iniciar uma execução de comando (console)
Para começar a executar o comando no console, acesse a página do [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) do AWS IoT console e execute as etapas a seguir.
1. Para executar o comando que você criou, escolha **Executar comando**.
1. Revise as informações sobre o comando que você criou, incluindo os tópicos reservados e os parâmetros do MQTT, se aplicável.
Para comandos dinâmicos, insira os valores dos parâmetros ou deixe-os com os padrões. Para parâmetros que não têm um valor padrão, você deve fornecer um valor a ser enviado como parte dessa execução.
1. Especifique o dispositivo de destino para receber e executar o Comando. O dispositivo pode ser especificado como uma AWS IoT coisa se tiver sido registrado AWS IoT ou usando o ID do cliente se o dispositivo ainda não tiver sido registrado. Para obter mais informações, consulte [Considerações sobre dispositivos de destino](#iot-command-execution-target).
1. (Opcional) Configure um valor de tempo limite para o comando que determine a duração pela qual você deseja que o comando seja executado antes que ele atinja o tempo limite. Se seu comando precisar ser executado por mais de 60 minutos, talvez seja necessário aumentar o tempo de expiração das sessões persistentes do MQTT. Para obter mais informações, consulte [Considerações sobre tempo limite de execução de comandos](#iot-command-execution-timeout).
1. Selecione **Run command**.
### Iniciar uma execução de comando (AWS CLI)
Use a operação da API do plano de dados HTTP [https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html) para iniciar uma execução de comando. A solicitação e a resposta da API são correlacionadas pelo ID de execução do comando. Depois que o dispositivo concluir a execução do comando, ele poderá relatar o status e o resultado da execução para a nuvem publicando uma mensagem no tópico de resposta dos comandos. Para um código de resposta personalizado, os códigos de aplicativo que você possui podem processar a mensagem de resposta e publicar o resultado em AWS IoT.
Se seus dispositivos assinaram o tópico de solicitação de comandos, a API `StartCommandExecution` publicará a mensagem de carga útil no tópico. A carga útil pode usar qualquer formato de sua escolha. Para obter mais informações, consulte [Carga útil do comando](iot-remote-command-create-manage.md#iot-commands-payload).
```
$aws/commands///executions/+/request/
```
Se o formato da carga não for JSON ou CBOR, o seguinte mostra o formato do tópico de solicitação de comandos.
```
$aws/commands///executions/+/request
```
#### Exemplo de política do IAM
Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação `StartCommandExecution`.
Neste exemplo, substitua:
+ `region` por sua Região da AWS, como `us-east-1`.
+ `account-id` pelo número de sua Conta da AWS , como `123456789012`.
+ `command-id`com um identificador exclusivo para seu AWS IoT comando, como`LockDoor`. Se quiser enviar mais de um comando, você poderá especificá-los na política do IAM.
+ `devices`com `thing` ou `client` dependendo se seus dispositivos foram registrados como AWS IoT itens ou especificados como clientes MQTT.
+ `device-id`com o seu AWS IoT `thing-name` ou`client-id`.
```
{
"Effect": "Allow",
"Action": [
"iot:StartCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
Para ver uma lista das chaves de condição suportadas`StartCommandExecution`, consulte [Chaves de condição AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-policy-keys) no *Guia do usuário do IAM*.
#### Acessar o endpoint do plano de dados específico da conta
Antes de executar o comando da API, você deve acessar o URL do endpoint específico da conta. Se você estiver usando endpoints de pilha dupla (IPv4e IPv6), use o. `iot:Data-ATS` O `iot:Jobs` endpoint é IPv4 apenas para. Por exemplo, se você executar este comando:
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
Ele retorna o URL do endpoint específico da conta, conforme mostrado no exemplo de resposta abaixo.
```
{
"endpointAddress":
"-ats.iot..api.com"
}
```
#### Iniciar um exemplo de execução de comando (AWS CLI)
O exemplo a seguir mostra como começar a executar um comando usando o `start-command-execution` AWS CLI comando.
Neste exemplo, substitua:
+ *``* pelo ARN do comando que você deseja executar. Você pode acessar essas informações na resposta do comando `create-command` da CLI. Por exemplo, se você estiver executando o comando para alterar o modo do volante, use `arn:aws:iot:region:account-id:command/SetComfortSteeringMode`.
+ *``* pelo ARN da coisa do dispositivo de destino, que pode ser uma coisa da IoT ou um cliente do MQTT, para o qual você deseja executar o comando. Por exemplo, se você estiver executando o comando para o dispositivo de destino `myRegisteredThing`, use `arn:aws:iot:region:account-id:thing/myRegisteredThing`.
+ *``* pelo endpoint específico da conta que você acessou em [Acessar o endpoint do plano de dados específico da conta](#iot-remote-command-execution-start-endpoint), com o prefixo `https://`. Por exemplo, .`https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com`
+ (Opcional) Você também pode especificar um parâmetro adicional, `executionTimeoutSeconds`, ao realizar a operação da API `StartCommandExecution`. Esse campo opcional especifica o tempo em segundos em que o dispositivo deve concluir a execução do comando. O valor padrão é de 10 segundos. Quando o status de execução do comando é `CREATED`, um cronômetro é iniciado. Se o resultado da execução do comando não for recebido antes que o cronômetro expire, o status mudará automaticamente para `TIMED_OUT`.
+
```
aws iot-jobs-data start-command-execution \
--command-arn \
--target-arn \
--endpoint \
--execution-timeout-seconds 900
```
+ (Opcional) Para comandos dinâmicos, especifique os parâmetros e seus valores a serem usados para substituição. Você deve fornecer um valor para parâmetros que não tenham um DefaultValue definido na criação do comando. Se um parâmetro tiver um DefaultValue, o valor do parâmetro fornecido aqui terá precedência. Para parâmetros que têm ValueConditions definidas, o valor do parâmetro fornecido aqui deve satisfazer a condição.
Com base no exemplo de comando `Light_Power_Status` dinâmico:
+
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status \
--target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \
--endpoint \
--execution-timeout-seconds 900 \
--parameters "powerStatus={S=ON}"
```
A execução desse comando exibe um ID de execução. Você pode usar esse ID para consultar o status, os detalhes e o histórico da execução do comando.
**nota**
Se o comando estiver suspenso, a solicitação da API `StartCommandExecution` falhará com uma exceção de validação. Para corrigir esse erro, primeiro restaure o comando usando a API `UpdateCommand` e, depois, execute a solicitação `StartCommandExecution`.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
## Atualizar o resultado de uma execução de comando
Use a operação da API do plano de dados do MQTT `UpdateCommandExecution` para atualizar o status ou o resultado de uma execução de comando.
**nota**
Antes de usar essa API:
Seu dispositivo deve ter estabelecido uma conexão do MQTT e assinado os tópicos de solicitação e resposta de comandos. Para obter mais informações, consulte [Fluxo de trabalho de comandos de alto nível](iot-remote-command-workflow.md).
Você já deve ter executado esse comando usando a operação da API `StartCommandExecution`.
### Exemplo de política do IAM
Antes de usar essa operação da API, verifique se sua política do IAM autoriza seu dispositivo a realizar essas ações. Veja a seguir um exemplo de política que autoriza seu dispositivo a realizar a ação. Para exemplos adicionais de políticas do IAM que permitem que o usuário execute a ação do `UpdateCommandExecution` MQTT, consulte[Exemplos de política para conectar e publicar](connect-and-pub.md).
Neste exemplo, substitua:
+ `Region`com o seu Região da AWS, como`us-east-1`.
+ `AccountID` pelo número de sua Conta da AWS , como *`123456789012`*.
+ `ThingName`com o nome da AWS IoT coisa para a qual você está direcionando a execução do comando, como*`myRegisteredThing`*.
+ `commands-request-topic`e `commands-response-topic` com os nomes dos seus tópicos de solicitação e resposta de AWS IoT comandos. Para obter mais informações, consulte [Fluxo de trabalho de comandos de alto nível](iot-remote-command-workflow.md).
#### Exemplo de política do IAM para o ID do cliente do MQTT
O código a seguir mostra um exemplo de política de dispositivos ao usar o ID do cliente do MQTT.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
}
]
}
```
#### Exemplo de política do IAM para uma coisa da IoT
O código a seguir mostra um exemplo de política de dispositivos ao usar uma coisa da AWS IoT .
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response"
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
}
]
}
```
### Como usar a API `UpdateCommandExecution`
Depois que a execução do comando é recebida no tópico da solicitação, o dispositivo processa o comando. Depois, ele usa a API `UpdateCommandExecution` para atualizar o status e o resultado da execução do comando para o tópico de resposta a seguir.
```
$aws/commands///executions//response/
```
Neste exemplo, *``* é o identificador exclusivo do dispositivo de destino, e *``* é o identificador da execução do comando no dispositivo de destino. Eles ** podem ser JSON ou CBOR.
**nota**
Se você não registrou seu dispositivo com AWS IoT, você pode usar o ID do cliente como seu identificador em vez de um nome de coisa.
```
$aws/commands/clients//executions//response/
```
#### O dispositivo relatou atualizações no status de execução
Seus dispositivos podem usar a API para relatar qualquer uma das atualizações de status a seguir na execução do comando. Para acessar mais informações sobre esses status, consulte [Status de execução do comando](iot-remote-command-concepts.md#iot-command-execution-status).
+ `IN_PROGRESS`: quando o dispositivo começa a executar o comando, ele pode atualizar o status para `IN_PROGRESS`.
+ `SUCCEEDED`: quando o dispositivo processa com êxito o comando e conclui sua execução, ele pode publicar uma mensagem no tópico de resposta como `SUCCEEDED`.
+ `FAILED`: se o dispositivo não conseguir executar o comando, ele poderá publicar uma mensagem no tópico de resposta como `FAILED`.
+ `REJECTED`: se o dispositivo falhar ao aceitar o comando, ele poderá publicar uma mensagem no tópico de resposta como `REJECTED`.
+ `TIMED_OUT`: o status de execução do comando pode mudar para `TIMED_OUT` devido a qualquer um dos motivos a seguir.
+ O resultado da execução do comando não foi recebido. Isso pode acontecer porque a execução não foi concluída no período especificado ou se o dispositivo não conseguiu publicar as informações de status no tópico de resposta.
+ O dispositivo relata que ocorreu um tempo limite ao tentar executar o comando.
Para acessar mais informações sobre o status `TIMED_OUT`, consulte [Valor do tempo limite e status de execução `TIMED_OUT`](#iot-command-execution-timeout-status).
#### Considerações ao usar a API `UpdateCommandExecution`
Veja a seguir algumas considerações importantes ao usar a API `UpdateCommandExecution`.
+ Seus dispositivos podem usar um `statusReason` objeto opcional para fornecer informações adicionais sobre a execução. Se seus dispositivos fornecerem esse objeto, o `reasonCode` campo do objeto será obrigatório, mas o `reasonDescription` campo é opcional.
+ Quando seus dispositivos usam o `statusReason` objeto, eles `reasonCode` devem usar o padrão `[A-Z0-9_-]+` e não exceder 64 caracteres de comprimento. Se você fornecer o`reasonDescription`, certifique-se de que ele não exceda 1.024 caracteres. Ele pode usar qualquer caractere, exceto caracteres de controle, como novas linhas.
+ Seus dispositivos podem usar um objeto `result` opcional para fornecer informações sobre o resultado da execução do comando, como o valor de retorno de uma chamada de função remota. Se você fornecer o `result`, ele deverá exigir pelo menos uma entrada.
+ No campo `result`, você especifica as entradas como pares de chave-valor. Para cada entrada, você deve especificar as informações do tipo de dados como string, booliano ou binário. Um tipo de dados de string deve usar a chave `s`, um tipo booliano usa a chave `b` e um binário deve usar a chave `bin`. Certifique-se de que essas teclas estejam em minúsculas.
+ Se você encontrar um erro ao executar a `UpdateCommandExecution` API, poderá ver o erro no grupo de `AWSIoTLogsV2` registros na Amazon CloudWatch. Para acessar informações sobre como habilitar o registro em log e visualizar os logs, consulte [Configurar o AWS IoT registro](configure-logging.md).
#### Exemplo de API `UpdateCommandExecution`
O código a seguir mostra um exemplo de como seu dispositivo pode usar a API `UpdateCommandExecution` para relatar o status da execução, o campo `statusReason` para fornecer informações adicionais sobre o status e o campo de resultados para fornecer informações sobre o resultado da execução, como a porcentagem da bateria do carro, nesse caso.
```
{
"status": "IN_PROGRESS",
"statusReason": {
"reasonCode": "200",
"reasonDescription": "Execution_in_progress"
},
"result": {
"car_battery": {
"s": "car battery at 50 percent"
}
}
}
```
## Recuperar uma execução de comando
Depois de executar um comando, você pode recuperar informações sobre a execução do comando no AWS IoT console e usando o. AWS CLI Você pode acessar as informações a seguir.
**nota**
Para recuperar o status mais recente de execução do comando, seu dispositivo deve publicar as informações de status no tópico de resposta usando a API `UpdateCommandExecution` do MQTT, conforme descrito abaixo. Até que o dispositivo publique neste tópico, a API `GetCommandExecution` relatará o status como `CREATED` ou `TIMED_OUT`.
Cada execução de comando que você criar terá:
+ Um **ID de execução**, que é um identificador exclusivo da execução do comando.
+ O **status** da execução do comando. Quando você executa o comando no dispositivo de destino, a execução entra no estado `CREATED`. Depois, ele pode fazer a transição para outros status de execução, conforme descrito abaixo.
+ O **resultado** da execução do comando.
+ O **ID de comando** exclusivo e o dispositivo de destino para o qual as execuções foram criadas.
+ A **Data de início**, que mostra a hora em que a execução do comando foi criada.
### Recuperar uma execução de comando (console)
Você pode recuperar uma execução de comando do console usando qualquer um dos métodos a seguir.
+
**Na página Hub de comandos**
Acesse a página do [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) do AWS IoT console e execute essas etapas.
1. Escolha o comando para o qual você criou uma execução no dispositivo de destino.
1. Na página de detalhes do comando, na guia **Histórico de comandos**, você verá as execuções criadas. Escolha a execução cujas informações você deseja recuperar.
1. Se seus dispositivos usaram a API `UpdateCommandExecution` para fornecer as informações do resultado, você poderá encontrá-las na guia **Resultados** desta página.
+
**Na página Hub de coisas**
Se você escolheu AWS IoT algo como dispositivo de destino ao executar o comando, você pode ver os detalhes da execução na página Thing hub.
1. Acesse a página [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) no AWS IoT console e escolha a coisa para a qual você criou a execução do comando.
1. Na página de detalhes da coisa, no **histórico de comandos**, você verá as execuções criadas. Escolha a execução cujas informações você deseja recuperar.
1. Se seus dispositivos usaram a API `UpdateCommandExecution` para fornecer as informações do resultado, você poderá encontrar essas informações na guia **Resultados** desta página.
### Recuperar uma execução de comando (CLI)
Use a operação da API HTTP do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT Core controle para recuperar informações sobre a execução de um comando. Você já deve ter executado esse comando usando a operação da API `StartCommandExecution`.
#### Exemplo de política do IAM
Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação `GetCommandExecution`.
Neste exemplo, substitua:
+ `region` por sua Região da AWS, como `us-east-1`.
+ `account-id` pelo número de sua Conta da AWS , como `123456789012`.
+ `command-id`com seu identificador de AWS IoT comando exclusivo, como`LockDoor`.
+ `devices`com `thing` ou `client` dependendo se seus dispositivos foram registrados como AWS IoT itens ou especificados como clientes MQTT.
+ `device-id`com o seu AWS IoT `thing-name` ou`client-id`.
```
{
"Effect": "Allow",
"Action": [
"iot:GetCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
#### Exemplo de como recuperar uma execução de comando
O exemplo a seguir mostra como recuperar informações sobre um comando que foi executado usando o `start-command-execution` AWS CLI comando. O exemplo a seguir mostra como recuperar informações sobre um comando executado para desativar o modo do volante.
Neste exemplo, substitua:
+ *``* pelo identificador da execução do comando cujas informações você deseja recuperar.
+ *``* pelo nome do recurso da Amazon (ARN) do dispositivo para o qual você planeja a execução. Você pode acessar essas informações na resposta do comando `start-command-execution` da CLI.
+ Opcionalmente, se seus dispositivos usaram a API `UpdateCommandExection` para fornecer o resultado da execução, você poderá especificar se deseja incluir o resultado da execução do comando na resposta da API `GetCommandExecution` usando a API `GetCommandExecution`.
```
aws iot get-command-execution
--execution-id \
--target-arn \
--include-result
```
A execução desse comando gera uma resposta que contém informações sobre o ARN da execução do comando, o status da execução e a hora em que ela foi iniciada e concluída. Ela também fornece um objeto `statusReason` que contém informações adicionais sobre o status. Para acessar mais informações sobre os diferentes status e os respectivos motivos, consulte [Status de execução do comando](iot-remote-command-concepts.md#iot-command-execution-status).
O código a seguir mostra um exemplo de resposta da solicitação da API.
**nota**
O campo `completedAt` na resposta de execução corresponde ao momento em que o dispositivo relata o status terminal para a nuvem. No caso do status `TIMED_OUT`, esse campo será definido somente quando o dispositivo informar um tempo limite. Quando o status `TIMED_OUT` é definido pela nuvem, o status `TIMED_OUT` não é atualizado. Para acessar mais informações sobre o comportamento do tempo limite, consulte [Considerações sobre tempo limite de execução de comandos](#iot-command-execution-timeout).
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
"targetArn": "arn:aws:iot:us-east-1:123456789012:thing/myRegisteredThing",
"status": "SUCCEEDED",
"statusReason": {
"reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED",
"reasonDescription": "SUCCESS"
},
"result": {
"sn": { "s": "ABC-001" },
"digital": { "b": true }
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00"
}
```
## Visualizar atualizações de comandos usando o cliente de teste do MQTT
É possível usar o cliente de teste do MQTT para visualizar a troca de mensagens pelo MQTT ao usar o recurso de comandos. Depois que seu dispositivo estabelecer uma conexão MQTT com AWS IoT, você poderá criar um comando, especificar a carga útil e executá-la no dispositivo. Quando você executa o comando, se seu dispositivo se inscreveu no tópico de solicitação reservada do MQTT para comandos, ele vê a mensagem de carga publicada nesse tópico.
O dispositivo então recebe as instruções de carga útil e executa as operações especificadas no AWS IoT dispositivo. Em seguida, ele usa a `UpdateCommandExecution` API para publicar o resultado da execução do comando e as informações de status nos tópicos de resposta reservados do MQTT para comandos. AWS IoT Device Management escuta atualizações sobre os tópicos de resposta, armazena as informações atualizadas e publica registros AWS CloudTrail na Amazon. CloudWatch Em seguida, você pode recuperar as informações mais recentes sobre a execução do comando no console ou usando a `GetCommandExecution` API.
As etapas a seguir mostram como usar o cliente de teste do MQTT para observar mensagens.
1. Abra o [cliente de teste MQTT](https://console.aws.amazon.com/iot/home#/test) no AWS IoT console.
1. Na guia **Inscrever-se**, insira o tópico a seguir e escolha **Inscrever-se**, onde ** está o nome do dispositivo com o qual você se registrou AWS IoT.
**nota**
Você pode encontrar o nome da coisa para o seu dispositivo na página [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) do AWS IoT console. Se você não registrou seu dispositivo como uma coisa, você pode registrar o dispositivo ao se conectar a AWS IoT partir da [página Connect device](https://console.aws.amazon.com/iot/home#/connect-overview).
```
$aws/commands/things//executions/+/request
```
1. (Opcional) Na guia **Assinar**, você também pode inserir os tópicos a seguir e escolher **Assinar**.
```
$aws/commands/things/+/executions/+/response/accepted/json
$aws/commands/things/+/executions/+/response/rejected/json
```
1. Depois de iniciar uma execução de comando, a carga útil de mensagem será enviada ao dispositivo usando o tópico de solicitação assinado pelo dispositivo, ou seja, `$aws/commands/things//executions/+/request`. No cliente de teste do MQTT, você deve ver a carga útil que contém as instruções para que o dispositivo processe o comando.
1. Depois que o dispositivo começar a executar o comando, ele poderá publicar atualizações de status no tópico de resposta reservada do MQTT a seguir.
```
$aws/commands///executions//response/json
```
Por exemplo, pense em um comando que você executou para ligar o ar condicionado do seu carro a fim de reduzir a temperatura até o valor desejado. O JSON a seguir mostra um exemplo de mensagem que o veículo publicou no tópico de resposta que mostra que ele não executou o comando.
```
{
"deviceId": "My_Car",
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"status": "FAILED",
"statusReason": {
"reasonCode": "CAR_LOW_ON_BATTERY",
"reasonDescription": "Car battery is lower than 5 percent"
}
}
```
Nesse caso, você pode carregar a bateria do carro e executar o comando novamente.
## Liste as execuções de comandos em seu Conta da AWS
Depois de executar um comando, você pode recuperar informações sobre a execução do comando no AWS IoT console e usando o. AWS CLI Você pode acessar as informações a seguir.
+ Um **ID de execução**, que é um identificador exclusivo da execução do comando.
+ O **status** da execução do comando. Quando você executa o comando no dispositivo de destino, a execução entra no estado `CREATED`. Depois, ele pode fazer a transição para outros status de execução, conforme descrito abaixo.
+ O **ID de comando** exclusivo e o dispositivo de destino para o qual as execuções foram criadas.
+ A **Data de início**, que mostra a hora em que a execução do comando foi criada.
### Listar as execuções de comandos na sua conta (console)
Você pode recuperar todas as execuções de comandos do console usando qualquer um dos métodos a seguir.
+
**Na página Hub de comandos**
Acesse a página do [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) do AWS IoT console e execute essas etapas.
1. Escolha o comando para o qual você criou uma execução no dispositivo de destino.
1. Na página de detalhes do comando, acesse a guia **Histórico de comandos**. Você verá uma lista das execuções criadas.
+
**Na página Hub de coisas**
Se você escolheu AWS IoT algo como dispositivo de destino ao executar o comando e criou várias execuções de comando para um único dispositivo, você pode ver as execuções do dispositivo na página Thing hub.
1. Acesse a página [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) no AWS IoT console e escolha a coisa para a qual você criou as execuções.
1. Na página de detalhes da coisa, no **histórico de comandos**, você verá a lista de execuções criadas para o dispositivo.
### Listar as execuções de comandos em sua conta (CLI)
Use a operação da API HTTP do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html) AWS IoT Core controle para listar todas as execuções de comandos em sua conta.
#### Exemplo de política do IAM
Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação `ListCommandExecutions`.
Neste exemplo, substitua:
+ `region` por sua Região da AWS, como `us-east-1`.
+ `account-id` pelo número de sua Conta da AWS , como `123456789012`.
+ `command-id`com seu identificador de AWS IoT comando exclusivo, como`LockDoor`.
```
{
"Effect": "Allow",
"Action": "iot:ListCommandExecutions",
"Resource": *
}
```
#### Exemplo de como listar as execuções de comandos
O exemplo a seguir mostra como listar as execuções de comandos na Conta da AWS.
Ao executar o comando, você deve especificar se deseja filtrar a lista para exibir somente execuções de comandos que foram criadas para um dispositivo específico usando o `targetArn` ou execuções para um comando especificado usando o `commandArn`.
Neste exemplo, substitua:
+ *``* pelo nome do recurso da Amazon (ARN) do dispositivo no qual pretende realizar a execução, como `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`.
+ *``* pelo nome do recurso da Amazon (ARN) do dispositivo no qual você planeja a execução, como `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`.
+ *``* pelo tempo após o qual você deseja listar as execuções criadas, por exemplo, `2024-11-01T03:00`.
```
aws iot list-command-executions \
--target-arn \
--started-time-filter '{after=}' \
--sort-order "ASCENDING"
```
A execução desse comando gera uma resposta com uma lista das execuções de comando criadas, a hora em que elas começaram a ser realizadas e quando foram concluídas. Ela também fornece informações de status e o objeto `statusReason` que contém informações adicionais sobre o status.
```
{
"commandExecutions": [
{
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
"executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24",
"targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
"status": "TIMED_OUT",
"createdAt": "2024-11-24T14:39:25.791000-08:00",
"startedAt": "2024-11-24T14:39:25.791000-08:00"
},
{
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
"executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f",
"targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
"status": "IN_PROGRESS",
"createdAt": "2024-11-24T14:05:36.021000-08:00",
"startedAt": "2024-11-24T14:05:36.021000-08:00"
}
]
}
```
Para acessar mais informações sobre os diferentes status e os respectivos motivos, consulte [Status de execução do comando](iot-remote-command-concepts.md#iot-command-execution-status).
## Excluir uma execução de comando
Se você não quiser mais usar uma execução de comando, poderá removê-la permanentemente da sua conta.
**nota**
A execução de um comando só poderá ser excluída se tiver entrado em um status terminal, como `SUCCEEDED`, `FAILED` ou `REJECTED`.
Essa operação só pode ser executada usando a AWS IoT Core API ou AWS CLI o. Essa opção não está disponível no console.
### Exemplo de política do IAM
Antes de usar essa operação da API, verifique se sua política do IAM autoriza seu dispositivo a realizar essas ações. Veja a seguir um exemplo de política que autoriza seu dispositivo a realizar a ação.
Neste exemplo, substitua:
+ `Region`com o seu Região da AWS, como`us-east-1`.
+ `AccountID` pelo número de sua Conta da AWS , como *`123456789012`*.
+ `CommandID` pelo identificador do comando cuja execução você deseja excluir.
+ `devices`com `thing` ou `client` dependendo se seus dispositivos foram registrados como AWS IoT itens ou especificados como clientes MQTT.
+ `device-id`com o seu AWS IoT `thing-name` ou`client-id`.
```
{
"Effect": "Allow",
"Action": [
"iot:DeleteCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
### Exemplo de como excluir uma execução de comando
O exemplo a seguir mostra como excluir um comando usando o `delete-command` AWS CLI comando. Dependendo da sua aplicação, substitua *``* pelo identificador da execução do comando que você está excluindo e *``* pelo ARN do dispositivo de destino.
```
aws iot delete-command-execution \
--execution-id \
--target-arn
```
Se a solicitação da API for bem-sucedida, a execução do comando gerará um código de status de 200. Você pode usar a API `GetCommandExecution` para verificar se a execução do comando não existe mais na sua conta.
# Suspender um recurso de comando
Desative os comandos para indicar que estão desatualizados e não devem ser usados. Por exemplo, os comandos obsoletos não são mais mantidos ativamente ou ao criar comandos mais novos com o mesmo ID, mas com cargas diferentes.
## Considerações importantes
Considerações importantes ao descontinuar comandos:
+ A descontinuação de um comando não o exclui. Você pode recuperar o comando usando seu ID e restaurá-lo para reutilização.
+ A tentativa de iniciar novas execuções em comandos obsoletos gera um erro, impedindo o uso de comandos desatualizados.
+ Para executar um comando obsoleto, primeiro restaure-o. Após a restauração, o comando fica disponível para uso e execução regulares nos dispositivos de destino.
+ Se você descontinuar um comando enquanto as execuções estiverem em andamento, elas continuarão em execução até serem concluídas. Você ainda pode recuperar o status de execução.
## Suspender um recurso de comando (console)
Para descontinuar um comando do console, acesse o [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) do AWS IoT console e execute as etapas a seguir.
1. **Escolha o comando que você deseja descontinuar e, em **Ações**, escolha Descontinuar.**
1. Confirme que você deseja suspender o comando e, depois, selecione **Suspender**.
## Suspender um recurso de comando (CLI)
Marque os comandos como obsoletos usando a CLI. `update-command` Você deve descontinuar um comando antes de excluí-lo. Para usar um comando obsoleto, restaure-o primeiro.
```
aws iot update-command \
--command-id \
--deprecated
```
Por exemplo, se você suspendeu o comando `ACSwitch` atualizado no exemplo acima, o código a seguir mostrará um exemplo de saída da execução.
```
{
"commandId": "turnOffAc",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
## Conferir a hora e o status da suspensão
Use a `GetCommand` API para determinar se um comando está obsoleto e quando foi descontinuado pela última vez.
```
aws iot get-command --command-id
```
Esse comando gera uma resposta contendo informações do comando, incluindo registros de data e hora de criação e descontinuação do último campo atualizado. Isso ajuda a determinar a vida útil do comando e se ele deve ser excluído ou reutilizado. Veja a seguir um exemplo de resposta para o `turnOffAc` comando:
```
{
"commandId": "turnOffAC",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/turnOffAC",
"namespace": "AWS-IoT",
"payload": {
"content": "testPayload.json",
"contentType": "application/json"
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00",
"deprecated": false
}
```
## Restaurar um recurso de comando
Para usar ou enviar o `ACSwitch` comando para seu dispositivo, restaure-o primeiro.
Para restaurar um comando do console, acesse o [Hub de Comando](https://console.aws.amazon.com/iot/home#/commandHub) do AWS IoT console, escolha o comando que você deseja restaurar e, em **Ações**, escolha **Restaurar**.
Para restaurar um comando usando a AWS IoT Core API ou a AWS CLI, use a operação da `UpdateCommand` API ou a `update-command` CLI. O código a seguir mostra um exemplo de solicitação e resposta.
```
aws iot update-command \
--command-id
--no-deprecated
```
O código a seguir mostra um exemplo de saída.
```
{
"commandId": "ACSwitch",
"deprecated": false,
"lastUpdatedAt": "2024-05-09T23:17:21.954000-07:00"
}
```