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