AWS A IoT não FleetWise está mais aberta a novos clientes. Os FleetWise clientes de AWS IoT existentes podem continuar usando o serviço. O [Guia para Mobilidade Conectada AWS](https://aws.amazon.com/solutions/guidance/connected-mobility-on-aws/) fornece orientação sobre como desenvolver e implantar serviços modulares para soluções de mobilidade conectada que podem ser usadas para obter recursos equivalentes aos da AWS IoT FleetWise.
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á.
# 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 [Provisão 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 {{$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode}} e `value` pode ser um booleano que indica um status do modo de direção, como{{{"B": false}}}.
+ (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.