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á.
# Comandos
**Importante**
O acesso a determinados FleetWise recursos de AWS IoT está atualmente bloqueado. Para obter mais informações, consulte [AWS Disponibilidade de regiões e recursos na AWS IoT FleetWise](fleetwise-regions.md).
Esta documentação descreve como usar o [recurso de comandos para AWS IoT FleetWise](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html#commands-iotfw-namespace). Para obter informações sobre como usar o recurso de comandos em AWS IoT Device Management, consulte [comandos](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.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 o recurso de comandos para executar comandos em um veículo a partir da nuvem. Os comandos têm como alvo um dispositivo por vez e podem ser usados para aplicações de baixa latência e alto throughput, como recuperar os logs do lado do dispositivo ou iniciar uma alteração no estado do dispositivo.
O *comando* é um recurso gerenciado pelo AWS IoT Device Management. Ele contém configurações reutilizáveis que são aplicadas ao enviar uma execução de comando para o veículo. Você pode predefinir um conjunto de comandos para casos de uso específicos ou usá-los para criar configurações reutilizáveis para casos de uso recorrentes. Por exemplo, você pode configurar comandos que podem ser usados por um aplicativo para trancar a porta de um veículo ou alterar a temperatura remotamente.
Usando o recurso de AWS IoT comandos, você pode:
+ Crie um recurso de comando e reutilize a configuração para enviar vários comandos ao dispositivo de destino e, em seguida, executá-los no dispositivo.
+ Controle a granularidade com a qual você deseja que cada comando seja executado no dispositivo. Por exemplo, você pode provisionar um veículo como uma AWS IoT coisa e, em seguida, enviar um comando para trancar ou destrancar as portas do veículo.
+ Execute vários comandos simultaneamente no dispositivo de destino sem esperar que o anterior seja concluído.
+ Escolha ativar notificações para eventos de comandos e recuperar as informações de status e resultado do dispositivo à medida que ele executa o comando e depois de concluído.
Os tópicos a seguir mostram como criar, enviar, receber e gerenciar comandos.
**Topics**
+ [Conceitos de comandos](remote-command-concepts-states.md)
+ [Veículos e comandos](remote-command-vehicles.md)
+ [Criar e gerenciar comandos](create-manage-remote-command-cli.md)
+ [Iniciar e monitorar execuções de comando](send-monitor-remote-command-cli.md)
+ [Exemplo: Usando comandos para controlar o modo de direção de um veículo (AWS CLI)](remote-command-tutorial.md)
+ [Cenários de uso de comandos](remote-command-use-cases.md)
# Conceitos de comandos
**Importante**
O acesso a determinados FleetWise recursos de AWS IoT está atualmente bloqueado. Para obter mais informações, consulte [AWS Disponibilidade de regiões e recursos na AWS IoT FleetWise](fleetwise-regions.md).
Comandos são instruções enviadas da nuvem para o dispositivo de destino. O dispositivo de destino pode ser um veículo e deve ser registrado como uma *AWS IoT coisa* no registro de coisas. O comando pode conter parâmetros que definem uma ação que os atuadores do veículo precisam realizar. O veículo então analisa o comando e seus parâmetros e os processa para realizar a ação correspondente. Em seguida, ele responde ao aplicativo em nuvem com o status da execução do comando.
Para obter o fluxo de trabalho detalhado, consulte[Veículos e comandos](remote-command-vehicles.md).
**Topics**
+ [Conceitos de chaves de comandos](#remote-command-concepts)
+ [Status de execução do comando](#remote-command-execution-status-codes)
## Conceitos de chaves de comandos
Veja a seguir alguns conceitos-chave para usar o recurso de comandos e como ele funciona com os modelos de estado do último estado conhecido (LKS).
**Comando**
Um Comando é uma entidade que você pode usar para enviar instruções a um veículo físico para que ele execute ações como ligar o motor ou alterar a posição das janelas. Você pode predefinir um conjunto de comandos para casos de uso específicos ou usá-los para criar configurações reutilizáveis para casos de uso recorrentes. Por exemplo, você pode configurar comandos que podem ser usados por um aplicativo para trancar a porta de um veículo ou alterar a temperatura remotamente.
**Namespace**
Ao usar o recurso de comandos, você deve especificar o namespace para o comando. Ao criar um comando na AWS IoT FleetWise, você deve escolher `AWS-IoT-FleetWise` como seu namespace. Ao usar esse namespace, você deve fornecer os parâmetros que serão usados para executar o comando no veículo. Se você quiser criar um comando em AWS IoT Device Management vez disso, você deve usar o `AWS-IoT` namespace em vez disso. Para obter mais informações, consulte [os comandos](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html) no *guia do AWS IoT Device Management desenvolvedor*.
**Estados de comando**
Os comandos que você criar estarão em um estado disponível, o que significa que podem ser usados para iniciar a execução de um comando no veículo. Se um comando ficar desatualizado, você poderá descontinuar o comando. Para um comando no estado obsoleto, as execuções de comandos existentes serão executadas até a conclusão. Você não pode atualizar o comando nem executar novas execuções. Para enviar novas execuções, você deve restaurar o comando para que ele fique disponível.
Você também pode excluir um comando se ele não for mais necessário. Quando você marca um comando para exclusão, se o comando tiver sido descontinuado por um período maior que o tempo limite máximo de 24 horas, o comando será excluído imediatamente. Se o comando não for suspenso ou permanecer suspenso por um período menor que o valor do tempo limite máximo, ele entrará no estado de exclusão pendente. O comando será removido automaticamente da sua conta após 24 horas.
**Parâmetros**
Ao criar um comando, você pode especificar opcionalmente os parâmetros que deseja que o veículo de destino execute ao executar o comando. O comando que você cria é uma configuração reutilizável e pode ser usado para enviar várias execuções de comando ao seu veículo e executá-las simultaneamente. Como alternativa, você também pode especificar os parâmetros somente em tempo de execução e optar por realizar uma operação única de criar um comando e enviá-lo ao seu veículo.
**Veículo alvo**
Quando quiser executar o comando, você deve especificar um veículo alvo que receberá o comando e executará ações específicas. O veículo-alvo já deve ter sido registrado como *algo* com AWS IoT. Depois de enviar o comando para o veículo, ele começará a executar uma instância do comando com base nos parâmetros e nos valores que você especificou.
**Atuadores**
Quando quiser executar o comando, você deve especificar os atuadores no veículo que receberão o comando e seus valores que determinam as ações a serem executadas. Opcionalmente, você pode configurar valores padrão para os atuadores para evitar o envio de comandos imprecisos. Por exemplo, você pode usar um valor padrão de `LockDoor` para um atuador de fechadura de porta para que o comando não destranque acidentalmente as portas. Para obter informações gerais sobre atuadores, consulte[Principais conceitos](how-iotfleetwise-works.md#key-concepts).
**Suporte ao tipo de dados**
Os seguintes tipos de dados são compatíveis com os atuadores usados para o recurso de comandos.
As matrizes não são suportadas para dados telemáticos, comandos ou último estado conhecido (LKS). Você só pode usar o tipo de dados de matriz para dados de sistemas de visão.
+ Tipos de ponto flutuante. Os tipos a seguir são aceitos.
+ Flutuante (32 bits)
+ Duplo (64 bits)
+ Inteiro (assinado e não assinado). Os seguintes tipos de números inteiros são suportados.
+ int8 e uint8
+ int16 e uint16
+ int32 e uint32
+ Longo. Os seguintes tipos longos são compatíveis.
+ Longo (int64)
+ Não assinado por muito tempo (uint64)
+ String
+ Booleano
**Execução de comandos**
A execução de um comando é uma instância de um comando em execução em um dispositivo de destino. O veículo executa o comando usando os parâmetros que você especificou quando criou o comando ou quando iniciou a execução do comando. O veículo então executa as operações especificadas e retorna o status da execução.
Para um determinado veículo, você pode executar vários comandos simultaneamente. Para obter informações sobre o número máximo de execuções simultâneas que você pode executar para cada veículo, consulte cotas de [AWS IoT Device Management comandos](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits).
**Modelos de estado do último estado conhecido (LKS)**
Os modelos de estado fornecem um mecanismo para que os proprietários de veículos rastreiem o estado de seus veículos. Para monitorar o último estado conhecido (LKS) de seus veículos quase em tempo real, você pode criar modelos de estado e associá-los aos seus veículos.
Usando o recurso de comandos, você pode realizar operações “On Demand” que podem ser usadas para coleta e processamento de dados estaduais. Por exemplo, você pode solicitar o estado atual do veículo uma única vez (buscar) ou ativar ou desativar modelos de estado do LKS implantados anteriormente para iniciar ou parar de relatar dados do veículo. Para exemplos que mostram como usar comandos com modelos de estado, consulte[Cenários de uso de comandos](remote-command-use-cases.md).
## Status de execução do comando
Depois de iniciar a execução do comando, seu veículo pode publicar o status da execução e fornecer os motivos do status como informações adicionais sobre a execução. As seções a seguir descrevem os vários status de execução do comando e os códigos de status.
**Topics**
+ [Status da execução do comando, motivo, código e descrição](#remote-command-execution-status-reason-codes)
+ [Status de execução do comando e códigos de status](#remote-command-execution-status-codes)
+ [Status do tempo limite de execução do comando](#remote-command-execution-status-timeout)
### Status da execução do comando, motivo, código e descrição
Para relatar atualizações no status de execução do comando, seus veículos podem usar a `UpdateCommandExecution` API para publicar as informações de status atualizadas na nuvem, usando os [tópicos reservados de Comandos](https://docs.aws.amazon.com/iot/latest/developerguide/reserved-topics.html#reserved-topics-commands) descritos no *guia do AWS IoT Core desenvolvedor*. Ao relatar as informações de status, seus dispositivos podem fornecer contexto adicional sobre o status de cada execução de comando usando o `StatusReason` objeto `reasonCode` e os campos `reasonDescription` que estão contidos no objeto.
### Status de execução do comando e códigos de status
A tabela a seguir mostra os vários códigos de status de execução de comandos e os status permitidos para os quais uma execução de comando pode fazer a transição. Também mostra se a execução de um comando é “terminal” (ou seja, não há mais atualizações de status disponíveis), se a alteração foi iniciada pelo veículo ou pela nuvem, os diferentes códigos de status predefinidos e como eles são mapeados para os status que são relatados pela nuvem.
+ Para obter informações sobre como AWS IoT FleetWise usa os códigos de status predefinidos e o `statusReason` objeto, consulte [Status do comando na documentação](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/include/aws/iotfleetwise/ICommandDispatcher.h) do software *Edge Agent para AWS FleetWise IoT*.
+ *Para obter informações adicionais sobre execuções terminais e não terminais e as transições entre os status, consulte [Status de execução de comandos](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#iot-command-execution-status) no guia do desenvolvedor.AWS IoT Core *
**Status e origem da execução do comando**
| Status de execução do comando | Description | Iniciado pelo dispositivo/nuvem? | Execução do terminal? | Transições de status permitidas | Códigos de status predefinidos |
| --- | --- | --- | --- | --- | --- |
| CREATED | Quando a solicitação da API para começar a executar o comando (StartCommandExecutionAPI) é bem-sucedida, o status de execução do comando muda paraCREATED. | Nuvem | Não | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | Nenhum |
| IN\$1PROGRESS | Quando o veículo começa a executar o comando, ele pode publicar uma mensagem no tópico de resposta para atualizar o status. IN\$1PROGRESS | Dispositivo | Não | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1COMMAND\$1IN\$1PROGRESS |
| SUCCEEDED | Quando o veículo tiver processado o comando com sucesso e concluído a execução, ele poderá publicar uma mensagem no tópico de resposta para atualizar o statusSUCCEEDED. | Dispositivo | Sim | Não aplicável | COMMAND\$1STATUS\$1SUCCEEDED |
| FAILED | Quando o veículo falhou ao executar o comando, ele pode publicar uma mensagem no tópico de resposta para atualizar o statusFAILED. | Dispositivo | Sim | Não aplicável | COMMAND\$1STATUS\$1EXECUTION\$1FAILED |
| REJECTED | Se o veículo não aceitar o comando, ele poderá publicar uma mensagem no tópico de resposta para atualizar o statusREJECTED. | Dispositivo | Sim | Não aplicável | Nenhum |
| TIMED\$1OUT | O status de execução do comando pode mudar para `TIMED_OUT` devido a qualquer um dos motivos a seguir. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) Para obter mais informações sobre esse status, consulte[Status do tempo limite de execução do comando](#remote-command-execution-status-timeout). | Dispositivo e nuvem | Não | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1EXECUTION\$1TIMEOUT |
### Status do tempo limite de execução do comando
O tempo limite de execução do comando pode ser relatado tanto pela nuvem quanto pelo dispositivo. Depois que o comando é enviado ao dispositivo, um temporizador é iniciado. Se não houver resposta recebida do dispositivo dentro da duração especificada, a nuvem relatará um `TIMED_OUT` status. Nesse caso, a execução do comando no `TIMED_OUT` status não é terminal.
O dispositivo pode substituir esse status por um status de terminal, como `SUCCEEDED``FAILED`, ou`REJECTED`. Ele também pode relatar que ocorreu um tempo limite ao executar o comando. Nesse caso, o status de execução do comando permanece em`TIMED_OUT`, mas os campos do `StatusReason` objeto são atualizados com base nas informações relatadas pelo dispositivo. A execução do comando no `TIMED_OUT` status agora se torna terminal.
Para obter informações adicionais, consulte [Considerações sobre o tempo limite de execução do comando](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-command-execution-timeout) no guia do *AWS IoT Core desenvolvedor*.
# Veículos e comandos
**Importante**
O acesso a determinados FleetWise recursos de AWS IoT está atualmente bloqueado. Para obter mais informações, consulte [AWS Disponibilidade de regiões e recursos na AWS IoT FleetWise](fleetwise-regions.md).
Você é o único responsável por implantar comandos de forma segura e compatível com as leis aplicáveis.
Para usar o recurso de comandos:
1. Primeiro, crie um recurso de comando. Opcionalmente, especifique os parâmetros que contêm as informações necessárias para executar o comando.
1. Especifique o veículo alvo que receberá o comando e executará as ações especificadas.
1. Agora, você pode executar o comando no dispositivo de destino e verificar os detalhes da execução do comando para recuperar o status e usar CloudWatch os registros para solucionar problemas adicionais.
As seções a seguir mostram o fluxo de trabalho entre veículos e comandos.
**Topics**
+ [Visão geral do fluxo de trabalho](#remote-command-vehicles-overview)
+ [fluxo de trabalho do veículo](#iot-remote-command-devices-workflow)
+ [Fluxo de trabalho de comandos](#iot-remote-command-commands-workflow)
+ [(Opcional) Notificações de comandos](#remote-command-notifications)
## Visão geral do fluxo de trabalho
As etapas a seguir fornecem uma visão geral do fluxo de trabalho de comandos entre seus veículos e comandos. Quando você usa qualquer um dos comandos das operações da API HTTP, a solicitação é assinada usando credenciais do Sigv4.
**nota**
Com exceção da operação da `StartCommandExecution` API, todas as operações executadas pelo protocolo HTTP usam o endpoint do plano de controle.
1.
**Estabeleça uma conexão MQTT e assine os tópicos de comandos**
Para se preparar para o fluxo de trabalho de comandos, os dispositivos devem estabelecer uma conexão MQTT com o `iot:Data-ATS` endpoint e assinar o tópico de solicitação de comandos mencionado acima. Opcionalmente, seus dispositivos também podem assinar os tópicos de resposta aceitos e rejeitados dos comandos.
1.
**Crie um modelo de veículo e um recurso de comando**
Agora você pode criar um veículo e um recurso de comando usando as operações da API `CreateVehicle` e do plano de `CreateCommand` controle. O recurso de comando contém as configurações a serem aplicadas quando o comando é executado no veículo.
1.
**Iniciar a execução do comando no dispositivo de destino**
Inicie a execução do comando no veículo usando a API do plano `StartCommandExecution` de dados com o endpoint específico da sua conta`iot:Jobs`. A API publica uma mensagem de carga útil codificada por protobuf no tópico de solicitação de comandos.
1.
**Atualizar o resultado da execução do comando**
O veículo processa o comando e a carga recebida e, em seguida, publica o resultado da execução do comando no tópico de resposta usando a `UpdateCommandExecution` API. Se seu veículo se inscreveu nos tópicos de resposta aceitos e rejeitados dos comandos, ele receberá uma mensagem indicando se a resposta foi aceita ou rejeitada pelo serviço em nuvem.
1.
**(Opcional) Recuperar o resultado da execução do comando**
Para recuperar o resultado da execução do comando, você pode usar a operação da API do plano de `GetCommandExecution` controle. Depois que seu veículo publicar o resultado da execução do comando no tópico de resposta, essa API retornará as informações atualizadas.
1.
**(Opcional) Inscrever-se e gerenciar eventos de comandos**
Para receber notificações sobre atualizações de status de execução de comandos, você pode se inscrever no tópico de eventos de comandos. Em seguida, você pode usar a API do plano de `CreateTopicRule` controle para rotear os dados de eventos de comandos para outros aplicativos, como AWS Lambda funções ou Amazon SQS, e criar aplicativos em cima deles.
## fluxo de trabalho do veículo
As etapas a seguir descrevem detalhadamente o fluxo de trabalho do veículo ao usar o recurso de comandos.
**nota**
As operações descritas nesta seção usam o protocolo MQTT.
1.
**Estabelecer uma conexão do MQTT**
Para preparar seus veículos para usar o recurso de comandos, ele deve primeiro se conectar ao agente de AWS IoT Core mensagens. Seu veículo deve ter permissão para realizar a `iot:Connect` ação para se conectar AWS IoT Core e estabelecer uma conexão MQTT com o agente de mensagens. Para encontrar o endpoint do plano de dados para seu Conta da AWS, use a `DescribeEndpoint` API ou o comando `describe-endpoint` CLI, conforme mostrado abaixo.
```
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 no tópico de solicitação de comandos**
Depois que uma conexão for estabelecida, seus dispositivos poderão assinar o tópico de solicitação de AWS IoT comandos do MQTT. Quando você cria um comando e inicia a execução do comando no dispositivo de destino, uma mensagem de carga útil codificada em protobuf será publicada no tópico da solicitação pelo agente de mensagens. Seu dispositivo pode então receber a mensagem de carga útil e processar o comando. Neste exemplo, *``* substitua pelo identificador exclusivo do seu veículo alvo. Esse ID pode ser o identificador exclusivo do seu veículo ou o nome de uma coisa.
**nota**
A mensagem de carga que é enviada ao dispositivo deve usar o formato protobuf.
```
$aws/commands/things//executions/+/request/protobuf
```
1.
**(Opcional) Inscreva-se nos tópicos de resposta de comandos**
Opcionalmente, você pode assinar esses tópicos de resposta de comandos para receber uma mensagem indicando se o serviço de nuvem aceitou ou rejeitou a resposta do dispositivo.
**nota**
É opcional que seus veículos se inscrevam nos tópicos `/accepted` e de `/rejected` resposta. Seus veículos receberão automaticamente essas mensagens de resposta, mesmo que não tenham se inscrito explicitamente nesses tópicos.
```
$aws/commands/things//executions//response/protobuf/accepted
$aws/commands/things//executions//response/protobuf/rejected
```
1.
**Atualizar o resultado de uma execução de comando**
O veículo alvo então processa o comando. Em seguida, ele usa a `UpdateCommandExecution` API para publicar o resultado da execução no seguinte tópico de resposta do MQTT.
**nota**
Para um determinado veículo e execução de comando, ele ** deve corresponder ao campo correspondente no tópico de solicitação ao qual o dispositivo se inscreveu.
```
$aws/commands/things//executions//response/protobuf
```
A `UpdateCommandExecution` API é uma operação de API de plano de dados em MQTT autenticada com TLS.
+ Se o serviço de nuvem processou com sucesso o resultado da execução do comando, uma mensagem será publicada no tópico aceito pelo MQTT. O tópico aceito usa o seguinte formato.
```
$aws/commands/things//executions//response/protobuf/accepted
```
+ Se o serviço de nuvem falhar ao processar o resultado da execução do comando, uma resposta será publicada no tópico rejeitado do MQTT. O tópico rejeitado usa o seguinte formato.
```
$aws/commands/things//executions//response/protobuf/rejected
```
Para obter mais informações sobre essa API e um exemplo, consulte[Atualizar o resultado da execução do comando](send-monitor-remote-command-cli.md#update-remote-command-execution-cli).
## Fluxo de trabalho de comandos
As etapas a seguir descrevem detalhadamente o fluxo de trabalho dos comandos.
**nota**
As operações descritas nesta seção usam o protocolo HTTP.
1.
**Registre seu veículo**
Agora que você preparou seu veículo para usar o recurso de comandos, você pode preparar seu aplicativo registrando seu veículo e criando um comando que será enviado ao veículo. Para registrar o veículo, crie uma instância de um modelo de veículo (manifesto do modelo) usando a operação da API do plano de [https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateVehicle.html](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateVehicle.html)controle. Para obter mais informações e exemplos, consulte [Criar um veículo](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/create-vehicle.html).
1.
**Crie um comando**
Use a operação da API do plano de controle [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html)HTTP para modelar comandos aplicáveis ao veículo que você está segmentando. Especifique todos os parâmetros e valores padrão a serem usados ao executar o comando e certifique-se de que ele use o `AWS-IoT-FleetWise` namespace. Para obter mais informações e exemplos de uso dessa API, consulte[Criar um recurso de comando](create-manage-remote-command-cli.md#create-remote-command-cli).
1.
**Inicie a execução do comando**
Agora você pode executar o comando que criou no veículo usando a operação da API do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_StartCommandExecution.html)dados. AWS IoT Device Management busca o comando e os parâmetros do comando e valida a solicitação recebida. Em seguida, ele invoca a AWS IoT FleetWise API com os parâmetros necessários para gerar a carga útil específica do veículo. A carga é então enviada ao dispositivo por meio AWS IoT Device Management do MQTT para o tópico de solicitação de comando no qual seu dispositivo se inscreveu. Para obter mais informações e exemplos de uso dessa API, consulte[Enviar um comando (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli).
```
$aws/commands/things//executions/+/request/protobuf
```
**nota**
Se o dispositivo estava off-line quando o comando foi enviado da nuvem e as sessões persistentes do MQTT estão em uso, o comando espera no agente de mensagens. Se o dispositivo voltar a ficar on-line antes do tempo limite e se tiver se inscrito no tópico de solicitação de comandos, o dispositivo poderá processar o comando e publicar o resultado no tópico de resposta. Se o dispositivo não voltar a ficar on-line antes do tempo limite, a execução do comando atingirá o tempo limite e a mensagem de carga útil expirará.
1.
**Recupere a execução do comando**
Depois de executar o comando no dispositivo, use a operação da API 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)controle para recuperar e monitorar o resultado da execução do comando. Você também pode usar a API para obter informações adicionais sobre os dados de execução, como quando foram atualizados pela última vez, quando a execução foi concluída e os parâmetros especificados.
**nota**
Para recuperar as informações de status mais recentes, seu dispositivo deve ter publicado o resultado da execução do comando no tópico de resposta.
Para obter mais informações e exemplos de uso dessa API, consulte[Obtenha a execução do comando](send-monitor-remote-command-cli.md#get-remote-command-execution-cli).
## (Opcional) Notificações de comandos
É possível assinar eventos de comandos para receber notificações quando o status de uma execução é alterado. As etapas a seguir mostram como assinar eventos de comandos e processá-los.
1.
**Criar uma regra de tópico**
É possível assinar eventos de tópicos de comandos e receber notificações quando o status de uma execução de comando é alterado. Você também pode criar uma regra de tópico para rotear os dados processados pelo veículo para outros aplicativos, como AWS Lambda funções. Você pode criar uma regra de tópico usando o AWS IoT console ou a operação da API do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html) AWS IoT Core controle. Para obter mais informações, consulte [Criação de uma AWS IoT regra](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-rule.html).
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**
Se você criou uma regra de tópico na etapa anterior para assinar eventos de comandos, poderá gerenciar as notificações push de comandos recebidas. Opcionalmente, você também pode criar aplicativos em cima dele, como with, Amazon SQS AWS Lambda, Amazon SNS ou Step AWS Functions usando a regra de tópico que você criou.
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": "4",
"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
**Importante**
O acesso a determinados FleetWise recursos de AWS IoT está atualmente bloqueado. Para obter mais informações, consulte [AWS Disponibilidade de regiões e recursos na AWS IoT FleetWise](fleetwise-regions.md).
Você pode configurar ações remotas reutilizáveis ou enviar instruções únicas e imediatas para seus dispositivos. Ao usar esse recurso, você pode especificar as instruções que seus dispositivos podem executar quase em tempo real. Um comando permite que você configure ações remotas reutilizáveis para o veículo de destino. Depois de criar um comando, você pode iniciar a execução de um comando direcionado a um veículo específico.
Este tópico mostra como você pode criar e gerenciar um recurso de comando usando a AWS IoT Core API ou AWS CLI o. Ele mostra como realizar as seguintes ações em um recurso de comando.
**Topics**
+ [Criar um recurso de comando](#create-remote-command-cli)
+ [Recuperar informações sobre um comando](#get-remote-command-cli)
+ [Listar comandos na sua conta](#list-remote-command-cli)
+ [Atualizar ou descontinuar um recurso de comando](#update-remote-command-cli)
+ [Excluir um recurso de comando](#delete-remote-command-cli)
## Criar um recurso de comando
Você pode usar a operação da API do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) AWS IoT Core controle ou o FleetWise console de AWS IoT para criar um comando.
### Crie um comando (console)
Você pode usar o FleetWise console de AWS IoT para criar um comando.
**Para criar um comando**
1. Abra o console [AWS de IoT. FleetWise ](https://console.aws.amazon.com/iotfleetwise)
1. No painel de navegação, escolha **Comandos**.
1. Escolha **Criar comando**.
1. Especifique um ID de comando exclusivo para ajudá-lo a identificar o comando que você deseja executar no veículo.
1. (Opcional) Especifique um nome de exibição e uma descrição opcionais.
1. (Opcional) Selecione o atuador e o valor padrão do parâmetro. Os parâmetros especificam as ações que o veículo-alvo pode realizar ao receber o comando. Se você não adicionar parâmetros, precisará fornecê-los ao executar o comando.
1. Escolha uma função do IAM que conceda permissões para gerar a carga útil dos comandos. Consulte [Controle de acesso](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html#generate-command-payload).
1. Escolha **Criar comando**.
### Crie um comando (AWS CLI)
O exemplo a seguir mostra como criar um comando com um parâmetro.
#### Considerações ao criar um comando
Quando você cria um comando em AWS IoT FleetWise:
+ Você deve especificar o `roleArn` que concede permissão para criar e executar comandos em seu veículo. Para obter mais informações e sobre exemplos de políticas, incluindo quando as chaves KMS estão habilitadas, consulte[Conceda AWS IoT Device Management permissão para gerar a carga útil para comandos com AWS IoT FleetWise](controlling-access.md#generate-command-payload).
+ Você deve especificar `AWS-IoT-FleetWise` como namespace.
+ Em vez disso, você pode pular o `mandatory-parameters` campo e especificá-los em tempo de execução. Como alternativa, você pode criar um comando com parâmetros e, opcionalmente, especificar valores padrão para eles. Se você especificou valores padrão, em tempo de execução, poderá usar esses valores ou substituí-los especificando seus próprios valores. Para ver esses exemplos adicionais, consulte[Cenários de uso de comandos](remote-command-use-cases.md).
+ Você pode especificar até três pares de nome-valor para o `mandatory-parameters` campo. No entanto, ao executar o comando no veículo, somente um par nome-valor é aceito, e o `name` campo deve usar o nome totalmente qualificado com o prefixo. `$actuatorPath.`
+ *command-id*Substitua por um identificador exclusivo para o comando. Você pode usar UUID, caracteres alfanuméricos, “-” e “\$1”.
+ *role-arn*Substitua pela função do IAM que concede permissão para criar e executar comandos, por exemplo,`"arn:aws:iam:accountId:role/FwCommandExecutionRole"`.
+ (Opcional) *display-name* Substitua por um nome fácil de usar para o comando e *description* por uma descrição significativa do comando.
+ Substitua *name* e *value* do `mandatory-parameters` objeto pelas informações necessárias para o comando que está sendo criado. O `name` campo é o nome totalmente qualificado, conforme definido no catálogo de sinais com `$actuatorPath.` o prefixo. Por exemplo, `name` pode ser *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode* e `value` pode ser um booleano que indica um status do modo de direção, como*\$1"B": false\$1*.
```
aws iot create-command --command-id command-id \
--role-arn role-arn \
--description description \
--display-name display-name \
--namespace "AWS-IoT-FleetWise" \
--mandatory-parameters '[
{
"name": name,
"value": value
}
]'
```
A operação da `CreateCommand` API retorna uma resposta que contém o ID e o ARN (Amazon Resource Name) do comando.
```
{
"commandId": "HandsOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"
}
```
## Recuperar informações sobre um comando
Você pode usar a operação da API do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html) AWS IoT Core controle para recuperar informações sobre um recurso de comando.
Para obter informações sobre um recurso de comando, execute o comando a seguir. *command-id*Substitua pelo identificador que foi usado ao criar o comando.
```
aws iot get-command --command-id command-id
```
A operação `GetCommand` da API retorna uma resposta que contém as informações a seguir.
+ O ID e o ARN (Amazon Resource Name) do comando.
+ A data e a hora em que o comando foi criado e atualizado pela última vez.
+ O estado do comando que indica se ele está disponível para ser executado no veículo.
+ Qualquer parâmetro que você especificou ao criar o comando.
```
{
"commandId": "HandsOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"",
"namespace": "AWS-IoT-FleetWise",
"mandatoryParameters":[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode",
"value": {"B": false }
}
],
"createdAt": "2024-03-23T11:24:14.919000-07:00",
"lastUpdatedAt": "2024-03-23T11:24:14.919000-07:00",
"deprecated": false,
"pendingDeletion": false
}
```
## Listar comandos na sua conta
Você pode usar a operação da API do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html) AWS IoT Core controle para listar todos os comandos que você criou na sua conta.
Para listar comandos em sua conta, execute o comando a seguir. Por padrão, a API retorna comandos que foram criados para os dois namespaces. Para filtrar a lista para exibir somente os comandos que foram criados para AWS IoT FleetWise, execute o comando a seguir.
**nota**
Você também pode classificar a lista em ordem crescente ou decrescente, ou filtrar a lista para exibir somente comandos que tenham um nome de parâmetro de comando específico.
```
aws iot list-commands --namespace "AWS-IoT-FleetWise"
```
A operação `ListCommands` da API retorna uma resposta que contém as informações a seguir.
+ O ID e o ARN (Amazon Resource Name) dos comandos.
+ A data e a hora em que o comando foi criado e atualizado pela última vez.
+ O estado do comando que indica se os comandos estão disponíveis para execução no veículo.
## Atualizar ou descontinuar um recurso de comando
Você pode usar 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) AWS IoT Core controle ou o FleetWise console de AWS IoT para atualizar um recurso de comando. Você pode atualizar o nome de exibição e a descrição de um comando. Você também pode descontinuar um comando se ele não estiver sendo usado no momento.
**nota**
Você não pode modificar as informações do namespace ou os parâmetros a serem usados ao executar o comando.
### Atualizar um comando (console)
**Atualizar um comando**
Para atualizar um comando do console, acesse a página [Comandos](https://console.aws.amazon.com/iotfleetwise/home#/commands) do FleetWise console de AWS IoT e execute as etapas a seguir.
1. Escolha o comando que você deseja atualizar e, em seguida, escolha **Editar**.
1. Edite os detalhes do comando e escolha **Salvar alterações**.
**Descontinuar um comando**
Para descontinuar um comando do console, acesse a página [Comandos](https://console.aws.amazon.com/iotfleetwise/home#/commands) do FleetWise console de AWS IoT e execute as etapas a seguir.
1. **Escolha o comando que você deseja descontinuar e, em seguida, escolha Descontinuar.**
1. **Confirme a suspensão de uso e, em seguida, escolha Descontinuar.**
### Atualizar um comando (AWS CLI)
**Atualizar um comando**
Para atualizar um recurso de comando, execute o comando a seguir. *command-id*Substitua pelo identificador do comando que você deseja atualizar e forneça o *description* e. *display-name*
```
aws iot update-command \
--command-id command-id \
--display-name display-name \
--description description
```
A operação `UpdateCommand` da API retorna a seguinte resposta.
```
{
"commandId": "HandsOffSteeringMode",
"deprecated": false,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
**Descontinuar um comando**
Você desaprova um comando quando não pretende mais continuar a usá-lo em seu dispositivo ou quando ele está desatualizado. O exemplo a seguir mostra como descontinuar um comando.
```
aws iot update-command \
--command-id command-id \
--deprecated
```
A operação da `UpdateCommand` API retorna uma resposta que contém o ID e o ARN (Amazon Resource Name) do comando.
```
{
"commandId": "HandsOffSteeringMode",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
Depois que um comando for descontinuado, as execuções de comandos existentes continuarão sendo executadas no veículo até se tornarem terminais. Para executar qualquer nova execução de comando, você deve usar a `UpdateCommand` API para restaurar o comando para que ele fique disponível. *Para obter informações adicionais sobre a descontinuação e a restauração de um comando e considerações sobre ele, consulte [Descontinuar um recurso de comando no Guia do desenvolvedor](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-deprecate).AWS IoT Core *
## Excluir um recurso de comando
Você pode usar a operação da API do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCommand.html) AWS IoT Core controle ou o FleetWise console de AWS IoT para excluir um recurso de comando.
**nota**
Uma ação de exclusão é permanente e não pode ser desfeita. O comando será removido permanentemente da sua conta.
### Excluir um comando (console)
Para excluir um comando do console, acesse a página [Comandos](https://console.aws.amazon.com/iotfleetwise/home#/commands) do FleetWise console de AWS IoT e execute as etapas a seguir.
1. Escolha o comando que você deseja excluir e, em seguida, escolha **Excluir**.
1. Confirme que você deseja excluir o comando e escolha **Excluir**.
### Excluir um comando (AWS CLI)
Para excluir um recurso de comando, execute o comando a seguir. *command-id*Substitua pelo identificador do comando que você deseja excluir. O exemplo a seguir mostra como excluir um recurso de comando.
```
aws iot delete-command --command-id command-id
```
Se a solicitação de exclusão for bem-sucedida:
+ Se o comando estiver obsoleto por um período maior que o tempo limite máximo de 24 horas, o comando será excluído imediatamente e você verá um HTTP de 204. `statusCode`
+ Se o comando não estiver obsoleto ou tiver sido preterido por um período menor que o tempo limite máximo, o comando estará em um `pending deletion` estado e você verá um HTTP de 202. `statusCode` O comando será removido automaticamente da sua conta após o tempo limite máximo de 24 horas.
# Iniciar e monitorar execuções de comando
**Importante**
O acesso a determinados FleetWise recursos de AWS IoT está atualmente bloqueado. Para obter mais informações, consulte [AWS Disponibilidade de regiões e recursos na AWS IoT FleetWise](fleetwise-regions.md).
Depois de criar um recurso de comando, você pode iniciar a execução de um comando no veículo de destino. Depois que o veículo começa a executar o comando, ele pode começar a atualizar o resultado da execução do comando e publicar atualizações de status e informações do resultado nos tópicos reservados do MQTT. Depois, você pode recuperar o status da execução do comando e monitorar o status das execuções em sua conta.
Este tópico mostra como você pode enviar um comando para seu veículo usando o console de IoT AWS CLI ou AWS IoT FleetWise . Também mostra como monitorar e atualizar o status da execução do comando.
**Topics**
+ [Atualizar o resultado da execução do comando](#update-remote-command-execution-cli)
+ [Obtenha a execução do comando](#get-remote-command-execution-cli)
+ [Listar as execuções de comandos em sua conta](#list-remote-command-execution-cli)
+ [Excluir uma execução de comando](#delete-remote-command-execution-cli)
## Enviar um comando (console)
Para enviar um comando do console, acesse a página [Veículos](https://console.aws.amazon.com/iotfleetwise/home#/vehicles) do FleetWise console de AWS IoT e execute as etapas a seguir.
1. Escolha o veículo para o qual você deseja enviar um comando.
1. Selecione **Run command**.
1. Selecione o ID do comando.
1. Especifique o tempo limite de execução do comando e escolha **Executar comando**.
## Enviar um comando (AWS CLI)
Você pode usar a operação da API do plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html) AWS IoT dados para enviar um comando para um veículo. O veículo então encaminha o comando para um serviço de middleware automotivo (como SOME/IP (Scalable Service-Oriented Middleware over IP)) ou o publica em uma rede veicular (como uma interface de dispositivo de rede de área controladora (CAN)). O exemplo a seguir usa a AWS CLI.
**Topics**
+ [Considerações ao enviar um comando](#send-remote-command-considerations)
+ [Acessar o endpoint do plano de dados específico da conta](#send-remote-command-endpoint)
+ [Envie um exemplo de comando](#send-remote-command-example)
### Considerações ao enviar um comando
Quando você inicia a execução de um comando em AWS IoT FleetWise:
+ Você deve provisionar qualquer AWS IoT coisa para o veículo. Para obter mais informações, consulte [Provisionar AWS veículos de IoT FleetWise](provision-vehicles.md).
+ Você já deve ter criado um comando com `AWS-IoT-FleetWise` como namespace e fornecido um `role-Arn` que conceda permissão para criar e executar comandos na IoT AWS . FleetWise Para obter mais informações, consulte [Criar um recurso de comando](create-manage-remote-command-cli.md#create-remote-command-cli).
+ Você pode ignorar o `parameters` campo se optar por usar qualquer valor padrão que tenha sido especificado para os parâmetros ao criar o comando. Se o `mandatory-parameters` não foi especificado no momento da criação, ou se você quiser substituir qualquer valor padrão especificando seus próprios valores para os parâmetros, você deverá especificar o `parameters` campo. Para ver esses exemplos adicionais, consulte[Cenários de uso de comandos](remote-command-use-cases.md).
+ Você pode especificar até três pares de nome-valor para o `mandatory-parameters` campo. No entanto, ao executar o comando no veículo, somente um par nome-valor é aceito, e o `name` campo deve usar o nome totalmente qualificado com o prefixo. `$actuatorPath.`
### Acessar o endpoint do plano de dados específico da conta
Antes de executar o comando da API, você deve obter o URL do endpoint específico da conta para o endpoint. `iot:Jobs` Por exemplo, se você executar este comando:
```
aws iot describe-endpoint --endpoint-type iot:Jobs
```
Ele exibirá o URL do endpoint específico da conta, conforme mostrado no exemplo de resposta abaixo.
```
{
"endpointAddress": ".jobs.iot..amazonaws.com"
}
```
### Envie um exemplo de comando
Para enviar um comando para um veículo, execute o comando a seguir.
+ *command-arn*Substitua pelo ARN do comando que você deseja executar. Você pode acessar essas informações na resposta do comando `create-command` da CLI.
+ *target-arn*Substitua pelo ARN do dispositivo ou AWS IoT objeto de destino para o qual você deseja executar o comando.
**nota**
Você pode especificar o ARN de destino de uma AWS IoT coisa (veículo de AWS IoT) FleetWise . Atualmente, não há suporte para grupos e frotas de coisas.
+ *endpoint-url*Substitua pelo endpoint específico da conta que você obteve em[Acessar o endpoint do plano de dados específico da conta](#send-remote-command-endpoint), prefixado por, por exemplo`https://`,. `https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com`
+ *value*Substitua *name* e pelo `mandatory-parameters` campo que você especificou ao criar o comando usando a `create-command` CLI.
O `name` campo é o nome totalmente qualificado, conforme definido no catálogo de sinais com `$actuatorPath.` o prefixo. Por exemplo, `name` pode ser *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode* e `value` pode ser um booleano que indica um status do modo de direção, como*\$1"B": false\$1*.
+ (Opcional) Você também pode especificar um parâmetro adicional,`executionTimeoutSeconds`. Esse campo opcional especifica o tempo em segundos em que o dispositivo deve responder com o resultado da execução. Você pode configurar o tempo limite para um valor máximo de 24 horas.
Quando a execução do comando é criada, um cronômetro é iniciado. Antes que o cronômetro expire, se o status de execução do comando não mudar para um status que o torne terminal, como `SUCCEEDED` ou`FAILED`, o status mudará automaticamente para. `TIMED_OUT`
**nota**
O dispositivo também pode relatar um `TIMED_OUT` status ou substituir esse status por um status como`SUCCEEDED`, ou `FAILED``REJECTED`, e a execução do comando se tornará terminal. Para obter mais informações, consulte [Status do tempo limite de execução do comando](remote-command-concepts-states.md#remote-command-execution-status-timeout).
```
aws iot-jobs-data start-command-execution \
--command-arn command-arn \
--target-arn target-arn \
--execution-timeout-seconds 30 \
--endpoint-url endpoint-url \
--parameters '[
{
"name": name,
"value": value
}
]'
```
A operação `StartCommandExecution` da API retorna um ID de execução do comando. Você pode usar esse ID para consultar o status, os detalhes e o histórico da execução do comando.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
Depois de executar o comando, seus dispositivos receberão uma notificação contendo as seguintes informações. O `issued_timestamp_ms` campo corresponde à hora em que a `StartCommandExecution` API foi invocada. O `timeout_ms` corresponde ao valor de tempo limite configurado usando o `executionTimeoutSeconds` parâmetro ao invocar a `StartCommandExecution` API.
```
timeout_ms: 9000000
issued_timestamp_ms: 1723847831317
```
## Atualizar o resultado da execução do comando
Para atualizar o status da execução do comando, seu dispositivo deve ter estabelecido uma conexão MQTT e inscrito no seguinte tópico de solicitação de comandos.
Neste exemplo, *``* substitua pelo identificador exclusivo do dispositivo de destino, que pode ser o nome `VehicleId` ou a coisa, e *``* pelo identificador para a execução do comando.
**nota**
A carga deve usar o formato protobuf.
É opcional que seus dispositivos se inscrevam nos tópicos `/accepted` e `/rejected` respondam. Seus dispositivos receberão essas mensagens de resposta mesmo que não tenham se inscrito explicitamente.
```
// Request topic
$aws/devices//command_executions/+/request/protobuf
// Response topics (Optional)
$aws/devices//command_executions//response/accepted/protobuf
$aws/devices//command_executions//response/rejected/protobuf
```
Seu dispositivo pode publicar uma mensagem no tópico de resposta dos comandos. Depois de processar o comando, ele envia uma resposta codificada em protobuf para esse tópico. O ** campo deve corresponder ao campo correspondente no tópico da solicitação.
```
$aws/devices//command_executions//response/
```
Depois que seu dispositivo publicar uma resposta a esse tópico, você poderá recuperar as informações de status atualizadas usando a `GetCommandExecution` API. O status da execução de um comando pode ser qualquer um dos listados aqui.
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`
+ `REJECTED`
+ `TIMED_OUT`
Observe que a execução de um comando em qualquer um dos status `SUCCEEDED``FAILED`, e `REJECTED` é terminal, e o status é relatado pelo dispositivo. Quando a execução de um comando é terminal, isso significa que nenhuma atualização adicional será feita em seu status ou campos relacionados. Um `TIMED_OUT` status pode ser relatado pelo dispositivo ou pela nuvem. Se relatado pela nuvem, uma atualização do campo de motivo do status poderá ser feita posteriormente pelo dispositivo.
Por exemplo, o exemplo a seguir mostra um exemplo de mensagem MQTT publicada pelo dispositivo.
**nota**
Para o status de execução do comando, se seus dispositivos usarem o `statusReason` objeto para publicar as informações de status, você deverá se certificar de que:
O `reasonCode` usa `[A-Z0-9_-]+` o padrão e não excede 64 caracteres.
O `reasonDescription` comprimento não excede 1.024 caracteres. Ela pode usar qualquer caractere, exceto de controle, como novas linhas.
```
{
"deviceId": "",
"executionId": "",
"status": "CREATED",
"statusReason": {
"reasonCode": "",
"reasonDescription": ""
}
}
```
Para ver um exemplo que mostra como você pode usar o cliente de teste AWS IoT Core MQTT para assinar os tópicos e ver as mensagens de execução do comando, consulte [Visualização de atualizações de comandos usando o cliente de teste MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-remote-command-execution-update-mqtt) no guia do *AWS IoT Core desenvolvedor*.
## Obtenha a execução do comando
Você pode usar a operação da API 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 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`.
Para recuperar os metadados de um comando executado, execute o comando a seguir.
+ *execution-id*Substitua pelo ID do comando. Você pode acessar essas informações na resposta do comando `start-command-execution` da CLI.
+ *target-arn*Substitua pelo ARN do veículo ou AWS IoT objeto de destino para o qual você deseja executar o comando.
```
aws iot get-command-execution --execution-id execution-id \
--target-arn target-arn
```
A operação da `GetCommandExecution` API retorna 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 o comando começou a ser executado e quando foi concluído. O código a seguir mostra um exemplo de resposta da solicitação da API.
Para fornecer contexto adicional sobre o status de cada execução de comando, o recurso de comandos fornece um `statusReason` objeto. O objeto contém dois campos `reasonCode` `reasonDescription` e. Usando esses campos, seus dispositivos podem fornecer informações adicionais sobre o status da execução de um comando. Essas informações substituirão qualquer padrão `reasonCode` e `reasonDescription` isso será relatado na nuvem.
Para relatar essas informações, seus dispositivos podem publicar as informações de status atualizadas na nuvem. Então, ao recuperar o status de execução do comando usando a `GetCommandExecution` API, você verá os códigos de status mais recentes.
**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 de `TIMED_OUT` status, 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 [Status do tempo limite de execução do comando](remote-command-concepts-states.md#remote-command-execution-status-timeout).
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
"targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/myFrontDoor",
"status": "SUCCEEDED",
"statusReason": {
"reasonCode": "65536",
"reasonDescription": "SUCCESS"
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00",
"Parameters": '{
"$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode":
{ "B": true }
}'
}
```
## Listar as execuções de comandos em sua conta
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. O exemplo usa AWS CLI.
**Topics**
+ [Considerações ao listar as execuções de comandos](#list-remote-command-considerations)
+ [Exemplo de como listar as execuções de comandos](#list-remote-command-example)
### Considerações ao listar as execuções de comandos
Veja a seguir algumas considerações ao usar a `ListCommandExecutions` API.
+ Você deve especificar pelo menos o `targetArn` ou o, `commandArn` dependendo se deseja listar as execuções de um comando específico ou de um veículo-alvo. A solicitação de API não pode estar vazia e não pode conter os dois campos na mesma solicitação.
+ Você deve fornecer somente as `startedTimeFilter` ou as `completedTimeFilter` informações. A solicitação de API não pode estar vazia e não pode conter os dois campos na mesma solicitação. Você pode usar os `after` campos `before` e do objeto para listar as execuções de comandos que foram criadas ou concluídas em um período específico.
+ Os `after` campos `before` e não devem ser maiores que a hora atual. Por padrão, se você não especificar nenhum valor, o `before` campo será a hora atual e o `after` campo será a hora atual - 6 meses. Ou seja, dependendo do filtro que você usa, a API listará todas as execuções que foram criadas ou concluídas nos últimos seis meses.
+ Você pode usar o `sort-order` parâmetro para especificar se deseja listar as execuções na ordem crescente. Por padrão, as execuções serão listadas em ordem decrescente se você não especificar esse campo.
+ Você não pode filtrar as execuções de comandos com base em seu status ao listar as execuções de comandos para um ARN de comando.
### 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"
}
]
}
```
## 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`.
O exemplo a seguir mostra como excluir a execução de um comando usando o `delete-command-execution` AWS CLI comando. *``*Substitua pelo identificador da execução do comando que você está excluindo.
```
aws iot delete-command-execution --execution-id
```
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.
# Exemplo: Usando comandos para controlar o modo de direção de um veículo (AWS CLI)
**Importante**
O acesso a determinados FleetWise recursos de AWS IoT está atualmente bloqueado. Para obter mais informações, consulte [AWS Disponibilidade de regiões e recursos na AWS IoT FleetWise](fleetwise-regions.md).
O exemplo a seguir mostra como usar o recurso de comandos usando AWS CLI o. Este exemplo usa um AWS IoT FleetWise veículo como dispositivo de destino para mostrar como você pode enviar um comando para controlar remotamente o modo de direção.
**Topics**
+ [Visão geral do exemplo do modo de direção do veículo](#iot-remote-command-tutorial-overview)
+ [Pré-requisitos](#iot-remote-command-tutorial-prereq)
+ [Política do IAM para usar comandos remotos](#remote-command-policy)
+ [Executar AWS IoT comandos (AWS CLI)](#iot-remote-command-tutorial-run)
+ [Limpeza](#remote-command-tutorial-clean)
## Visão geral do exemplo do modo de direção do veículo
Neste exemplo, você vai:
1. Crie um recurso de comando para a operação usando o `create-command` AWS CLI para alterar o modo de direção do veículo.
1. Recupere informações sobre o comando, como a hora em que ele foi criado ou atualizado pela última vez usando o. `get-command` AWS CLI
1. Envie o comando para o veículo usando o modo de direção como parâmetro obrigatório, que será executado no dispositivo. `start-command-execution` AWS CLI
1. Obtenha o resultado da execução do comando usando `get-command-execution` AWS CLI o. Você pode verificar quando a execução foi concluída e recuperar detalhes adicionais, como o resultado da execução e o tempo necessário para concluir a execução do comando.
1. Execute atividades de limpeza removendo quaisquer comandos e execuções de comandos que você não queira mais usar.
## Pré-requisitos
Antes de executar este exemplo:
+ Provisione seu AWS IoT FleetWise veículo como AWS IoT algo no AWS IoT registro. Você também deve adicionar um certificado à sua coisa, ativá-lo e anexar uma política à sua coisa. Seu dispositivo pode então se conectar à nuvem e executar os comandos. Para obter mais informações, consulte [Provisionar veículos](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/provision-vehicles.html).
+ Crie um usuário do IAM e uma política do IAM que conceda a você permissão para realizar as operações de API para usar comandos, conforme mostrado em[Política do IAM para usar comandos remotos](#remote-command-policy).
## Política do IAM para usar comandos remotos
A tabela a seguir mostra um exemplo de política do IAM que concede acesso a todas as operações de API do plano de controle e do plano de dados para o recurso de comandos. O usuário do aplicativo terá permissões para realizar todas as operações da API de comando remoto, conforme mostrado na tabela.
**Operação de API**
| Ação da API | Plano de controle/dados | Protocolo | Description | Recurso |
| --- | --- | --- | --- | --- |
| CreateCommand | Ambiente de gerenciamento | HTTP | Cria um recurso de comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommand | Ambiente de gerenciamento | HTTP | Recupera informações sobre um comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommand | Ambiente de gerenciamento | HTTP | Atualiza as informações sobre um comando ou para descontinuá-lo | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommands | Ambiente de gerenciamento | HTTP | Lista os comandos na sua conta | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommand | Ambiente de gerenciamento | HTTP | Exclui um comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| StartCommandExecution | Plano de dados | HTTP | Inicia a execução de um comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommandExecution | Plano de dados | MQTT | Atualizar a execução de um comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommandExecution | Ambiente de gerenciamento | HTTP | Recupera informações sobre a execução de um comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommandExecutions | Ambiente de gerenciamento | HTTP | Lista as execuções de comandos em sua conta | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommandExecution | Ambiente de gerenciamento | HTTP | Exclui a execução de um comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
Neste exemplo, substitua:
+ `us-east-1`com o seu Região da AWS, como`ap-south-1`.
+ `111122223333` pelo número de sua Conta da AWS , como `57EXAMPLE833`.
+ `command-id``command-id1`, e `command-id2` com seu identificador de comando exclusivo, como `LockDoor` ou`TurnOffAC`.
+ `thing-name`com o nome da sua AWS IoT coisa, como`my_car`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iot:CreateCommand",
"iot:GetCommand",
"iot:ListCommands",
"iot:UpdateCommand",
"iot:DeleteCommand"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id1",
"arn:aws:iot:us-east-1:111122223333:command/command-id2"
]
},
{
"Action": [
"iot:GetCommandExecution",
"iot:ListCommandExecutions",
"iot:DeleteCommandExecution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id",
"arn:aws:iot:us-east-1:111122223333:thing/thing-name"
]
},
{
"Action": "iot:StartCommandExecution",
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id",
"arn:aws:iot:us-east-1:111122223333:thing/thing-name"
]
}
]
}
```
------
## Executar AWS IoT comandos (AWS CLI)
O seguinte mostra como você pode usar o AWS CLI para executar operações de comandos e alterar o modo de direção do veículo.
1.
**Crie um recurso de comando para a operação do modo de direção**
Crie o comando que você deseja enviar ao seu dispositivo usando a `create-command` CLI. Neste exemplo, especifique:
+ `command-id` como *`TurnOffSteeringMode`*
+ `role-arn`como `"arn:aws:iam:accountId:role/FwCommandExecutionRole"` O `role-arn` deve ser fornecido, pois é a função do IAM que concede permissões para criar e executar comandos em seu veículo. Para obter mais informações, consulte [Conceda AWS IoT Device Management permissão para gerar a carga útil para comandos com AWS IoT FleetWise](controlling-access.md#generate-command-payload).
+ `display-name`como "*`Turn off steering mode`*”
+ `namespace`deve ser `AWS-IoT-FleetWise`
+ `mandatory-parameters`como um par nome-valor, com as "*\$1actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode*" e defaultValue `name` como `{ "S": "true" }`
**nota**
Você também pode criar um comando sem especificar nenhum parâmetro obrigatório. Em seguida, você deve especificar os parâmetros a serem usados ao executar o comando usando a `start-command-execution` CLI. Para ver um exemplo, consulte [Cenários de uso de comandos](remote-command-use-cases.md).
**Importante**
Ao usar o `AWS-IoT-FleetWise` namespace, você deve garantir que o `Name` campo especificado como parte do `mandatory-parameters` use o `$actuatorPath.` prefixo e que o `Value` campo use o tipo de dados de string.
```
aws iot create-command \
--command-id TurnOffSteeringMode \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--display-name "Turn off steering mode" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode",
"defaultValue": { "S": "true" }
}
]'
```
A saída a seguir mostra um exemplo de resposta da CLI, onde `ap-south-1` e `123456789012` são exemplos do ID Região da AWS e. Conta da AWS
```
{
"commandId": "TurnOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode"
}
```
Para obter exemplos adicionais sobre o uso desse comando, consulte[Criar um recurso de comando](create-manage-remote-command-cli.md#create-remote-command-cli).
1.
**Recupere informações sobre o comando**
Execute o comando a seguir para recuperar informações sobre o comando, onde `command-id` está o ID do comando na saída da `create-command` operação acima.
**nota**
Se você criar mais de um comando, poderá usar a `ListCommands` API para listar todos os comandos em sua conta e, em seguida, usar a `GetCommand` API para obter informações adicionais sobre um comando específico. Para obter mais informações, consulte [Listar comandos na sua conta](create-manage-remote-command-cli.md#list-remote-command-cli).
```
aws iot get-command --command-id TurnOffSteeringMode
```
A execução desse comando gera a resposta a seguir. Você verá a hora em que o comando foi criado e quando foi atualizado pela última vez, todos os parâmetros que você especificou e se o comando está disponível para execução no dispositivo.
```
{
"commandId": "TurnOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode",
"namespace": "AWS-IoT-FleetWise",
"mandatoryParameters":[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode",
"defaultValue": {"S": "true" }
}
],
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
"deprecated": false
}
```
Para obter exemplos adicionais sobre o uso desse comando, consulte[Recuperar informações sobre um comando](create-manage-remote-command-cli.md#get-remote-command-cli).
1.
**Inicie a execução do comando**
Execute o comando a seguir para começar a executar o comando, onde `command-arn` está o comando ARN na saída `get-command` da operação acima. `target-arn`É o ARN do dispositivo de destino para o qual você está executando o comando, por exemplo,. *`myVehicle`*
Neste exemplo, como você forneceu valores padrão para os parâmetros ao criar o comando, a `start-command-execution` CLI pode usar esses valores ao executar o comando. Você também pode optar por substituir o valor padrão especificando um valor diferente para os parâmetros ao usar a CLI.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode \
--target-arn arn:aws:iot:ap-south-1:123456789012:thing/myVehicle
```
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.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
Para obter exemplos adicionais sobre o uso da CLI, consulte. [Enviar um comando (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli)
1.
**Recupere informações sobre a execução do comando**
Execute o comando a seguir para recuperar informações sobre o comando que você executou no dispositivo de destino. Especifique o`execution-id`, que você obteve como saída da `start-command-execution` operação acima, e o`target-arn`, que é o ARN do dispositivo que você está segmentando.
**nota**
Para obter as informações de status mais recentes, seus dispositivos devem ter publicado as informações de status atualizadas no tópico de resposta reservada do MQTT para comandos que usam a API do `UpdateCommandExecution` MQTT. Para obter mais informações, consulte [Atualizar o resultado da execução do comando](send-monitor-remote-command-cli.md#update-remote-command-execution-cli).
Se você iniciar mais de uma execução de comando, poderá usar a `ListCommandExecutions` API para listar todas as execuções de comandos em sua conta e, em seguida, usar a `GetCommandExecution` API para obter informações adicionais sobre uma execução específica. Para obter mais informações, consulte [Listar as execuções de comandos em sua conta](send-monitor-remote-command-cli.md#list-remote-command-execution-cli).
```
aws iot get-command-execution \
--execution-id <"07e4b780-7eca-4ffd-b772-b76358da5542"> \
--target-arn arn:aws:iot:us-east-1::thing/myVehicle
```
A execução desse comando retorna informações sobre a execução do comando, o status da execução, a hora em que a execução foi iniciada e a hora em que foi concluída. Por exemplo, a resposta a seguir mostra que a execução do comando foi bem-sucedida no dispositivo de destino e o modo de direção foi desativado.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode",
"targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/myVehicle",
"result": "SUCCEEDED",
"statusReason": {
"reasonCode": "65536",
"reasonDescription": "SUCCESS"
},
"result": {
"KeyName": {
"S": "",
"B": true,
"BIN": null
}
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00",
"parameters": '{
"$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode":
{ "S": "true" }
}'
}
```
## Limpeza
Agora que você criou um comando e o executou em seu dispositivo, se não pretende mais usá-lo, você pode excluí-lo. Todas as execuções de comando pendentes em andamento continuarão sendo executadas sem serem afetadas pela solicitação de exclusão.
**nota**
Como alternativa, você também pode descontinuar um comando se ele estiver desatualizado e talvez seja necessário usá-lo posteriormente para ser executado no dispositivo de destino.
1.
**(Opcional) Descontinuar o recurso de comando**
Execute o comando a seguir para descontinuar o comando, onde `command-id` está o ID do comando na saída da `get-command` operação acima.
```
aws iot update-command \
--command-id TurnOffSteeringMode \
--deprecated
```
A execução desse comando retorna uma saída que mostra que o comando foi descontinuado. Você também pode usar a CLI para restaurar o comando.
**nota**
Você também pode usar a `update-command` CLI para atualizar o nome de exibição e a descrição de um comando. Para obter informações adicionais, consulte [Atualizar ou descontinuar um recurso de comando](create-manage-remote-command-cli.md#update-remote-command-cli).
```
{
"commandId": "TurnOffSteeringMode",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
1.
**Exclua o comando**
Execute o comando a seguir para excluir o comando, especificado pelo`command-id`.
**nota**
A ação de exclusão é permanente e não pode ser desfeita.
```
aws iot delete-command --command-id TurnOffSteeringMode
```
Se a solicitação de exclusão for bem-sucedida, você verá um HTTP `statusCode` de 202 ou 204, dependendo se você marcou o comando para descontinuação e quando ele foi descontinuado. Para obter mais informações e um exemplo, consulte [Excluir um recurso de comando](create-manage-remote-command-cli.md#delete-remote-command-cli).
Você pode usar a `get-command` CLI para verificar se o comando foi removido da sua conta.
1.
**(Opcional) Exclua as execuções do comando**
Por padrão, todas as execuções de comandos serão excluídas em seis meses a partir da data em que você as criou. Você pode visualizar essas informações usando o `timeToLive` parâmetro da `GetCommandExecution` API.
Como alternativa, se sua execução de comando se tornou terminal, como quando seu status de execução é de`SUCCEEDED`,`FAILED`, ou`REJECTED`, você pode excluir a execução do comando. Execute o comando a seguir para excluir a execução, onde `execution-id` está o ID de execução na saída da `get-command-execution` operação acima.
```
aws iot delete-command-execution \
--execution-id "07e4b780-7eca-4ffd-b772-b76358da5542"
```
Você pode usar a `get-command-execution` CLI para verificar se a execução do comando foi removida da sua conta.
# Cenários de uso de comandos
**Importante**
O acesso a determinados FleetWise recursos de AWS IoT está atualmente bloqueado. Para obter mais informações, consulte [AWS Disponibilidade de regiões e recursos na AWS IoT FleetWise](fleetwise-regions.md).
Ao usar o recurso de comandos, você pode criar e executar comandos nos seguintes cenários:
+ Você pode omitir os parâmetros durante a criação e especificar somente o ID do comando. Nesse caso, você precisa especificar os parâmetros a serem usados ao executar o comando no dispositivo de destino.
+ Você pode especificar um ou mais parâmetros e configurar valores padrão para eles ao criar o comando. Fornecer valores padrão ajudará você a evitar o envio de comandos imprecisos.
+ Você pode especificar um ou mais parâmetros e configurar valores para eles ao criar o comando. Mais de um parâmetro pode ser fornecido, mas somente um deles será executado, e o `Name` campo desse parâmetro deve usar o `$actuatorPath` prefixo.
Esta seção fornece alguns cenários de uso da `CreateCommand` e da `StartCommandExecution` API e o uso dos parâmetros. Também mostra alguns exemplos de uso de comandos com modelos de estado.
**Topics**
+ [Criando um comando sem parâmetros](#remote-command-use-case1)
+ [Criação de um comando com valores padrão para parâmetros](#remote-command-use-case2)
+ [Criação de um comando com valores de parâmetros](#remote-command-use-case3)
+ [Usando comandos com modelos de estado](#remote-command-use-cases-templates)
## Criando um comando sem parâmetros
O caso de uso a seguir mostra como você pode usar a `CreateCommand` API ou a `create-command` CLI para criar um comando sem parâmetros. Ao criar um comando, você só precisa fornecer um ID de comando e um ARN de função.
Esse caso de uso é especialmente útil em casos de uso recorrentes, como quando você deseja enviar o mesmo comando várias vezes para um veículo. Nesse caso, o comando não está vinculado a um atuador específico e oferece a flexibilidade de executar o comando em qualquer atuador. Em vez disso, você deve especificar os parâmetros em tempo de execução ao executar o comando usando a `StartCommandExecution` API ou a `start-command-execution` CLI, que inclui os atuadores e os valores do sinal físico.
### Criando um comando sem `mandatory-parameters` entrada
Esse caso de uso mostra como criar um comando sem a entrada obrigatória de parâmetros.
```
aws iot create-command \
--command-id "UserJourney1" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--description "UserJourney1 - No mandatory parameters" \
--namespace "AWS-IoT-FleetWise"
```
### Executando um comando criado sem `mandatory-parameters` entrada
Neste primeiro exemplo, o comando criado acima permite que você execute um comando em qualquer atuador sem restrições. `actuator1`Para definir um valor de 10, execute:
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "10"}
}'
```
Da mesma forma, você pode executar um comando definido `actuator3` como um valor de`true`.
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator3": {"S": "true"}
}'
```
## Criação de um comando com valores padrão para parâmetros
Esse comando só permite que você execute um comando no atuador especificado. Fornecer valores padrão ajudará você a evitar o envio de comandos imprecisos. Por exemplo, um `LockDoor` comando que tranca e destranca portas pode ser configurado com um valor padrão para evitar que o comando destranque portas acidentalmente.
Esse caso de uso é especialmente útil quando você deseja enviar o mesmo comando várias vezes e realizar ações diferentes no mesmo atuador, como trancar e destrancar as portas de um veículo. Se você quiser definir o atuador para o valor padrão, não precisará passar nenhum `parameters` para a CLI`start-command-execution`. Se você especificar um valor diferente para o `parameters` na `start-command-execution` CLI, ele substituirá o valor padrão.
### Criação de um comando com valores padrão para `mandatory-parameters`
O comando a seguir mostra como fornecer um valor padrão para o atuador1.
```
aws iot create-command \
--command-id "UserJourney2" \
--namespace "AWS-IoT-FleetWise" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.actuator1",
"defaultValue": {"S": "0"}
}
]'
```
### Executando um comando criado com valores padrão para `mandatory-parameters`
O comando `UserJourney2` permite que você execute um comando sem a necessidade de passar um valor de entrada durante o tempo de execução. Nesse caso, a execução em tempo de execução usará os valores padrão especificados durante a criação.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle
```
Você também pode passar um valor diferente para o mesmo atuador, atuador1, durante o tempo de execução, o que substituirá o valor padrão.
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "139"}
}'
```
## Criação de um comando com valores de parâmetros
Esse comando só permite que você execute um comando no atuador especificado. Também força você a definir um valor para o atuador durante o tempo de execução.
Esse caso de uso é especialmente útil quando você deseja que o usuário final execute apenas determinadas ações especificadas em alguns dos atuadores ao executá-los no veículo.
**nota**
Você pode ter mais do que pares nome-valor para a `mandatory-parameters` entrada, com valores padrão para alguns ou todos eles. Em tempo de execução, você pode então determinar o parâmetro que deseja usar ao executar no atuador, desde que o nome do atuador use o nome totalmente qualificado com o prefixo. `$actuatorPath.`
### Criação de comando sem valores padrão para `mandatory-parameters`
Esse comando só permite que você execute um comando no atuador especificado. Também força você a definir um valor para o atuador durante o tempo de execução.
```
aws iot create-command \
--command-id "UserJourney2" \
--namespace "AWS-IoT-FleetWise" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.actuator1"
}
]'
```
### Executando um comando criado sem valores padrão para `mandatory-parameters`
Ao executar o comando, nesse caso, você deve especificar um valor para atuador1. A execução do comando mostrada abaixo definirá com sucesso o valor de `actuator1` para`10`.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney2 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "10"}
}'
```
## Usando comandos com modelos de estado
Você também pode usar as operações de API de comandos para coleta e processamento de dados estaduais. Por exemplo, você pode obter um instantâneo de estado único ou ativar ou desativar modelos de estado para iniciar ou parar de coletar dados de estado do veículo. Os exemplos a seguir mostram como usar o recurso de comandos com modelos de estado. Para obter mais informações, consulte [Operações de modelo de estado para a coleta e processamento de dados](state-template-api-operations.md).
**nota**
O campo Nome especificado como parte da `mandatory-parameters` entrada deve usar o `$stateTemplate` prefixo.
### Exemplo 1: Criação de comandos para modelos de estado com valores padrão
Este exemplo mostra como usar a `create-command` CLI para ativar modelos de estado.
```
aws iot create-command \
--command-id \
--display-name "Activate State Template" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$stateTemplate.name"
},
{
"name": "$stateTemplate.operation",
"defaultValue": {"S": "activate"}
}
]'
```
Da mesma forma, o comando a seguir mostra um exemplo de como você pode usar a `start-command-execution` CLI para modelos de estado.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/ \
--target-arn arn:aws:iot:region:111122223333:thing/ \
--parameters '{
"$stateTemplate.name": {"S": "ST345"}
}'
```
### Exemplo 2: Criação de comandos para modelos de estado sem valores padrão
O comando a seguir cria vários modelos de estado sem valores padrão para nenhum dos parâmetros. Isso força você a executar o comando com esses parâmetros e os valores para eles.
```
aws iot create-command \
--command-id \
--display-name "Activate State Template" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$stateTemplate.name",
"defaultValue": {"S": "ST123"}
},
{
"name": "$stateTemplate.operation",
"defaultValue": {"S": "activate"}
},
{
"name": "$stateTemplate.deactivateAfterSeconds",
"defaultValue": {"L": "120"}
}
]'
```
O comando a seguir mostra como você pode usar a `start-command-execution` CLI para o exemplo acima.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/ \
--target-arn arn:aws:iot:region:111122223333:thing/ \
--parameters '{
"$stateTemplate.name": {"S": "ST345"},
"$stateTemplate.operation": {"S": "activate"},
"$stateTemplate.deactivateAfterSeconds" : {"L": "120"}
```