Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Comandos
**importante**
El acceso a ciertas FleetWise funciones de AWS IoT está actualmente restringido. Para obtener más información, consulte [AWS Disponibilidad regional y de funciones en el AWS IoT FleetWise](fleetwise-regions.md).
Esta documentación describe cómo utilizar la [función de comandos para AWS IoT FleetWise](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html#commands-iotfw-namespace). Para obtener información sobre el uso de la función de comandos en AWS IoT Device Management, consulte [comandos](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html).
Usted es el único responsable de implementar los comandos de forma segura y que cumpla con las normativas aplicables. Para obtener más información sobre sus responsabilidades, consulte los [términos de servicio de AWS para los servicios de AWS IoT](https://aws.amazon.com/service-terms/).
Utilice la función de comandos para ejecutar comandos en un vehículo desde la nube. Los comandos se dirigen a un dispositivo a la vez y se pueden usar para aplicaciones de baja latencia y alto rendimiento, como, por ejemplo, recuperar los registros del dispositivo o iniciar un cambio de estado del dispositivo.
El *comando* es un recurso gestionado por AWS IoT Device Management. Contiene configuraciones reutilizables que se aplican al enviar la ejecución de un comando al vehículo. Puede predefinir un conjunto de comandos para casos de uso específicos o usarlos para crear configuraciones reutilizables para casos de uso recurrentes. Por ejemplo, puedes configurar comandos que una aplicación puede utilizar para cerrar la puerta de un vehículo o para cambiar la temperatura de forma remota.
Con la función de AWS IoT comandos, puede:
+ Cree un recurso de comandos y reutilice la configuración para enviar varios comandos al dispositivo de destino y, a continuación, ejecutarlos en el dispositivo.
+ Controle la granularidad con la que desea que se ejecute cada comando en el dispositivo. Por ejemplo, puede aprovisionar un vehículo como una AWS IoT cosa y, a continuación, enviar una orden para bloquear o desbloquear las puertas del vehículo.
+ Ejecuta varios comandos simultáneamente en el dispositivo objetivo sin esperar a que se complete el anterior.
+ Seleccione activar las notificaciones de los eventos de comandos y recupere la información de estado y los resultados del dispositivo a medida que ejecuta el comando y una vez que se completa.
En los temas siguientes, se muestra cómo crear, enviar, recibir y administrar comandos.
**Topics**
+ [Conceptos de comandos](remote-command-concepts-states.md)
+ [Vehículos y comandos](remote-command-vehicles.md)
+ [Creación y administración de comandos](create-manage-remote-command-cli.md)
+ [Inicio y supervisión de las ejecuciones de comandos](send-monitor-remote-command-cli.md)
+ [Ejemplo: Uso de comandos para controlar el modo de dirección de un vehículo (AWS CLI)](remote-command-tutorial.md)
+ [Escenarios de uso de comandos](remote-command-use-cases.md)
# Conceptos de comandos
**importante**
El acceso a ciertas FleetWise funciones de AWS IoT está actualmente restringido. Para obtener más información, consulte [AWS Disponibilidad regional y de funciones en el AWS IoT FleetWise](fleetwise-regions.md).
Los comandos son instrucciones que se envían desde la nube al dispositivo de destino. El dispositivo objetivo puede ser un vehículo y debe estar registrado como una *AWS IoT cosa* en el registro de objetos. El comando puede contener parámetros que definen una acción que deben realizar los actuadores del vehículo. A continuación, el vehículo analiza el comando y sus parámetros y los procesa para realizar la acción correspondiente. A continuación, responde a la aplicación en la nube con el estado de la ejecución del comando.
Para ver el flujo de trabajo detallado, consulte[Vehículos y comandos](remote-command-vehicles.md).
**Topics**
+ [Conceptos clave de los comandos](#remote-command-concepts)
+ [Estado de la ejecución del comando](#remote-command-execution-status-codes)
## Conceptos clave de los comandos
A continuación, se muestran algunos conceptos clave sobre el uso de la función de comandos y su funcionamiento con las plantillas de estado del último estado conocido (LKS).
**Comando**
Un comando es una entidad que puedes usar para enviar instrucciones a un vehículo físico para que realice acciones como encender el motor o cambiar la posición de las ventanillas. Puedes predefinir un conjunto de comandos para casos de uso específicos o usarlos para crear configuraciones reutilizables para casos de uso recurrentes. Por ejemplo, puedes configurar comandos que una aplicación puede utilizar para cerrar la puerta de un vehículo o para cambiar la temperatura de forma remota.
**Namespace**
Al utilizar la función de comandos, debe especificar el espacio de nombres del comando. Cuando creas un comando en AWS IoT FleetWise, debes elegirlo `AWS-IoT-FleetWise` como espacio de nombres. Al utilizar este espacio de nombres, debe proporcionar los parámetros que se utilizarán para ejecutar el comando en el vehículo. Si desea crear un comando en AWS IoT Device Management su lugar, debe usar el espacio de `AWS-IoT` nombres en su lugar. Para obtener más información, consulta [los comandos](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html) de la guía *AWS IoT Device Management para desarrolladores*.
**Estados de comandos**
Los comandos que cree estarán en un estado disponible, lo que significa que se pueden usar para iniciar la ejecución de un comando en el vehículo. Si un comando queda obsoleto, puedes dejarlo obsoleto. En el caso de un comando en estado obsoleto, las ejecuciones de los comandos existentes se ejecutarán hasta completarse. No puede actualizar el comando ni ejecutar ninguna ejecución nueva. Para iniciar nuevas ejecuciones, debe restaurar el comando para que esté disponible.
También puede eliminar un comando si ya no es necesario. Al marcar un comando para su eliminación, si el comando ha quedado obsoleto durante un período superior al tiempo de espera máximo de 24 horas, el comando se eliminará inmediatamente. Si el comando no ha quedado obsoleto o ha dejado de utilizarse durante un periodo inferior al tiempo de espera máximo, el comando pasará al estado Pendiente de eliminación. El comando se eliminará automáticamente de tu cuenta después de 24 horas.
**Parámetros**
Al crear un comando, si lo desea, puede especificar los parámetros que desea que ejecute el vehículo objetivo al ejecutar el comando. El comando que cree es una configuración reutilizable y puede usarse para enviar múltiples ejecuciones de comandos a su vehículo y ejecutarlas simultáneamente. Como alternativa, también puedes especificar los parámetros solo en tiempo de ejecución y elegir realizar una sola operación: crear un comando y enviarlo a tu vehículo.
**Vehículo objetivo**
Cuando quieras ejecutar el comando, debes especificar un vehículo objetivo que recibirá el comando y realizará acciones específicas. El vehículo objetivo ya debe estar registrado como *un* objeto AWS IoT. Cuando envíes el comando al vehículo, este empezará a ejecutar una instancia del comando en función de los parámetros y valores que hayas especificado.
**Actuadores**
Cuando desee ejecutar el comando, debe especificar los actuadores del vehículo que recibirá el comando y sus valores, que determinan las acciones que se van a realizar. Si lo desea, puede configurar los valores predeterminados de los actuadores para evitar enviar comandos imprecisos. Por ejemplo, puede utilizar el valor por defecto de un actuador de `LockDoor` cerradura de puerta para que el comando no desbloquee accidentalmente las puertas. Para obtener información general sobre los actuadores, consulte[Conceptos clave](how-iotfleetwise-works.md#key-concepts).
**Soporte de tipos de datos**
Los actuadores que se utilizan para la función de comandos admiten los siguientes tipos de datos.
Las matrices no son compatibles con los datos telemáticos, los comandos ni el último estado conocido (LKS). Solo puede utilizar el tipo de datos de matriz para los datos de los sistemas de visión.
+ Tipos de punto flotante. Se admiten los siguientes tipos:
+ Flotante (32 bits)
+ Doble (64 bits)
+ Entero (con y sin signo). Se admiten los siguientes tipos de enteros.
+ int8 y uint8
+ int16 y uint16
+ int32 y uint32
+ Largo. Se admiten los siguientes tipos largos.
+ Largo (int64)
+ Largo sin signo (uint64)
+ Cadena
+ Booleano
**Ejecución de comandos**
La ejecución de un comando es una instancia de un comando que se ejecuta en un dispositivo de destino. El vehículo ejecuta el comando utilizando los parámetros que especificó al crear el comando o al iniciar la ejecución del comando. A continuación, el vehículo realiza las operaciones especificadas y devuelve el estado de la ejecución.
Para un vehículo determinado, puede ejecutar varios comandos al mismo tiempo. Para obtener información sobre el número máximo de ejecuciones simultáneas que puedes ejecutar para cada vehículo, consulta las cuotas de [AWS IoT Device Management comandos](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits).
**Plantillas de estado del último estado conocido (LKS)**
Las plantillas de estados proporcionan un mecanismo para que los propietarios de vehículos rastreen el estado de su vehículo. Para monitorizar el último estado conocido (LKS) de tus vehículos prácticamente en tiempo real, puedes crear plantillas de estado y asociarlas a tus vehículos.
Con la función de comandos, puede realizar operaciones «bajo demanda» que se pueden utilizar para recopilar y procesar datos de estado. Por ejemplo, puedes solicitar el estado actual del vehículo una sola vez (recuperar), o activar o desactivar las plantillas de estado LKS desplegadas anteriormente para iniciar o dejar de informar sobre los datos del vehículo. Para ver ejemplos que muestran cómo utilizar comandos con plantillas de estado, consulte. [Escenarios de uso de comandos](remote-command-use-cases.md)
## Estado de la ejecución del comando
Tras iniciar la ejecución del comando, el vehículo puede publicar el estado de la ejecución y proporcionar los motivos del estado como información adicional sobre la ejecución. En las siguientes secciones se describen los distintos estados de ejecución de los comandos y los códigos de estado.
**Topics**
+ [Estado de ejecución del comando, motivo, código y descripción](#remote-command-execution-status-reason-codes)
+ [Estado de ejecución de comandos y códigos de estado](#remote-command-execution-status-codes)
+ [Estado de espera de ejecución del comando](#remote-command-execution-status-timeout)
### Estado de ejecución del comando, motivo, código y descripción
Para informar sobre las actualizaciones del estado de ejecución de los comandos, sus vehículos pueden utilizar la `UpdateCommandExecution` API para publicar la información de estado actualizada en la nube, utilizando los [temas reservados a los comandos](https://docs.aws.amazon.com/iot/latest/developerguide/reserved-topics.html#reserved-topics-commands) que se describen en la *guía para AWS IoT Core desarrolladores*. Al enviar la información de estado, sus dispositivos pueden proporcionar un contexto adicional sobre el estado de cada ejecución de comandos mediante el `StatusReason` objeto `reasonCode` y `reasonDescription` los campos contenidos en el objeto.
### Estado de ejecución de comandos y códigos de estado
La siguiente tabla muestra los distintos códigos de estado de ejecución de comandos y los estados permitidos a los que puede pasar la ejecución de un comando. También muestra si la ejecución de un comando es «terminal» (es decir, si no habrá más actualizaciones de estado), si el cambio lo ha iniciado el vehículo o la nube, y los diferentes códigos de estado predefinidos y cómo se corresponden con los estados notificados por la nube.
+ Para obtener información sobre cómo se AWS IoT FleetWise utilizan los códigos de estado predefinidos y el `statusReason` objeto, consulte el [estado del comando](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/include/aws/iotfleetwise/ICommandDispatcher.h) en la *documentación del FleetWise software Edge Agent para AWS IoT*.
+ Para obtener información adicional sobre las ejecuciones terminales y no terminales y las transiciones entre los estados, consulte el [estado de ejecución de los comandos](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#iot-command-execution-status) en la guía para *AWS IoT Core desarrolladores*.
**Estado y origen de la ejecución de los comandos**
| Estado de la ejecución del comando | Description (Descripción) | ¿Iniciado por un dispositivo o la nube? | ¿Ejecución final? | Transiciones de estado permitidas | Códigos de estado predefinidos |
| --- | --- | --- | --- | --- | --- |
| CREATED | Cuando la solicitud de la API para iniciar la ejecución del comando (StartCommandExecutionAPI) se realiza correctamente, el estado de ejecución del comando cambia aCREATED. | Cloud | No | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | Ninguno |
| IN\$1PROGRESS | Cuando el vehículo comience a ejecutar el comando, podrá publicar un mensaje en el tema de respuesta para actualizar el estadoIN\$1PROGRESS. | Dispositivo | No | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1COMMAND\$1IN\$1PROGRESS |
| SUCCEEDED | Cuando el vehículo haya procesado correctamente el comando y completado la ejecución, podrá publicar un mensaje en el tema de respuesta para actualizar el estado. SUCCEEDED | Dispositivo | Sí | No aplicable | COMMAND\$1STATUS\$1SUCCEEDED |
| FAILED | Si el vehículo no ha ejecutado el comando, puede publicar un mensaje en el tema de respuesta para actualizar el estadoFAILED. | Dispositivo | Sí | No aplicable | COMMAND\$1STATUS\$1EXECUTION\$1FAILED |
| REJECTED | Si el vehículo no acepta la orden, puede publicar un mensaje en el tema de respuesta para actualizar el estadoREJECTED. | Dispositivo | Sí | No aplicable | Ninguno |
| TIMED\$1OUT | El estado de ejecución del comando puede cambiar a `TIMED_OUT` uno debido a cualquiera de los siguientes motivos. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) Para obtener más información sobre este estado, consulte[Estado de espera de ejecución del comando](#remote-command-execution-status-timeout). | Dispositivo y nube | No | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1EXECUTION\$1TIMEOUT |
### Estado de espera de ejecución del comando
Tanto la nube como el dispositivo pueden informar sobre el tiempo de espera de la ejecución de un comando. Una vez que se envía el comando al dispositivo, se iniciará un temporizador. Si no se recibe ninguna respuesta del dispositivo dentro del período especificado, la nube informa del `TIMED_OUT` estado. En este caso, la ejecución del comando en `TIMED_OUT` estado no es terminal.
El dispositivo puede sustituir este estado por un estado de terminal, como `SUCCEEDED``FAILED`, o. `REJECTED` También puede indicar que se ha agotado el tiempo de espera al ejecutar el comando. En este caso, el estado de ejecución del comando permanece en, `TIMED_OUT` pero los campos del `StatusReason` objeto se actualizan en función de la información proporcionada por el dispositivo. La ejecución del comando en ese `TIMED_OUT` estado pasa ahora a ser terminal.
Para obtener información adicional, consulte [Consideraciones sobre el tiempo de espera de la ejecución de comandos](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-command-execution-timeout) en la *guía para AWS IoT Core desarrolladores*.
# Vehículos y comandos
**importante**
El acceso a ciertas FleetWise funciones de AWS IoT está actualmente restringido. Para obtener más información, consulte [AWS Disponibilidad regional y de funciones en el AWS IoT FleetWise](fleetwise-regions.md).
Usted es el único responsable de implementar los comandos de forma segura y que cumpla con las normativas aplicables.
Cómo utilizar la característica de comandos:
1. En primer lugar, cree un recurso de comando. Si lo desea, especifique los parámetros que contienen la información necesaria para ejecutar el comando.
1. Especifique el vehículo objetivo que recibirá el comando y realizará las acciones especificadas.
1. Ahora puedes ejecutar el comando en el dispositivo objetivo y comprobar los detalles de ejecución del comando para recuperar el estado y utilizar CloudWatch los registros para seguir solucionando cualquier problema.
En las siguientes secciones, se muestra el flujo de trabajo entre los vehículos y los comandos.
**Topics**
+ [Información general sobre el flujo de trabajo](#remote-command-vehicles-overview)
+ [Flujo de trabajo de](#iot-remote-command-devices-workflow)
+ [Flujo de trabajo de comandos](#iot-remote-command-commands-workflow)
+ [(Opcional) Comandos y notificaciones](#remote-command-notifications)
## Información general sobre el flujo de trabajo
Los siguientes pasos proporcionan una visión general del flujo de trabajo de comandos entre sus vehículos y los comandos. Al utilizar cualquiera de las operaciones de la API HTTP de los comandos, la solicitud se firma con las credenciales de Sigv4.
**nota**
A excepción del funcionamiento de la `StartCommandExecution` API, todas las operaciones que se realizan mediante el protocolo HTTP utilizan el punto final del plano de control.
1.
**Establezca una conexión MQTT y suscríbase a los temas de comandos**
Para prepararse para el flujo de trabajo de los comandos, los dispositivos deben establecer una conexión MQTT con el `iot:Data-ATS` terminal y suscribirse al tema de solicitud de comandos mencionado anteriormente. De forma opcional, sus dispositivos también pueden suscribirse a los temas de respuesta sobre los comandos aceptados y rechazados.
1.
**Cree un modelo de vehículo y un recurso de mando**
Ahora puede crear un vehículo y un recurso de comando mediante las operaciones de la API `CreateVehicle` y del plano de `CreateCommand` control. El recurso de comando contiene las configuraciones que se aplicarán cuando el comando se ejecute en el vehículo.
1.
**Inicio de la ejecución de comandos en el dispositivo de destino**
Inicie la ejecución del comando en el vehículo mediante la API del plano de `StartCommandExecution` datos con el punto final específico de su cuenta`iot:Jobs`. La API publica un mensaje de carga útil codificado por protobug en el tema de solicitud de comandos.
1.
**Actualización del resultado de la ejecución de comandos**
El vehículo procesa el comando y la carga útil recibida y, a continuación, publica el resultado de la ejecución del comando en el tema de respuesta mediante la API. `UpdateCommandExecution` Si tu vehículo se ha suscrito a los temas de respuesta con los comandos de aceptación y rechazo, recibirá un mensaje en el que se indicará si el servicio en la nube ha aceptado o rechazado la respuesta.
1.
**(Opcional) Recuperación del resultado de la ejecución de comandos**
Para recuperar el resultado de la ejecución del comando, puede utilizar la operación API del plano de `GetCommandExecution` control. Una vez que tu vehículo publique el resultado de la ejecución del comando en el tema de respuesta, esta API devolverá la información actualizada.
1.
**(Opcional) Suscríbase y gestione los eventos de comandos**
Para recibir notificaciones sobre las actualizaciones del estado de ejecución de los comandos, puede suscribirse al tema de eventos de comandos. A continuación, puede utilizar la API del plano de `CreateTopicRule` control para enrutar los datos de eventos de comandos a otras aplicaciones, como AWS Lambda funciones o Amazon SQS, y crear aplicaciones a partir de ellos.
## Flujo de trabajo de
Los siguientes pasos describen en detalle el flujo de trabajo del vehículo cuando se utiliza la función de comandos.
**nota**
Las operaciones que se describen en esta sección utilizan el protocolo MQTT.
1.
**Establecimiento de una conexión con MQTT**
Para preparar sus vehículos para usar la función de comandos, primero deben conectarse al intermediario de AWS IoT Core mensajes. Su vehículo debe poder realizar la `iot:Connect` acción necesaria para conectarse AWS IoT Core y establecer una conexión MQTT con el intermediario de mensajes. Para encontrar el punto final del plano de datos para usted Cuenta de AWS, utilice la `DescribeEndpoint` API o el comando `describe-endpoint` CLI como se muestra a continuación.
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
Al ejecutar este comando, se devolverá el punto de conexión del plano de datos específico de la cuenta, tal como se muestra a continuación.
```
account-specific-prefix.iot.region.amazonaws.com
```
1.
**Suscríbase al tema de solicitud de comandos**
Una vez establecida la conexión, sus dispositivos pueden suscribirse al tema de solicitud de AWS IoT comandos en MQTT. Al crear un comando e iniciar la ejecución del comando en el dispositivo de destino, el intermediario de mensajes publicará un mensaje de carga útil codificado en protobuf en el tema de solicitud. A continuación, el dispositivo podrá recibir el mensaje de carga útil y procesar el comando. En este ejemplo, *``* sustitúyalo por el identificador único del vehículo objetivo. Este identificador puede ser el identificador único de tu vehículo o el nombre de una cosa
**nota**
El mensaje de carga que se envía al dispositivo debe usar el formato protobuf.
```
$aws/commands/things//executions/+/request/protobuf
```
1.
**(Opcional) Suscríbase a los temas de respuesta a los comandos**
Si lo desea, puede suscribirse a estos temas de respuesta a los comandos para recibir un mensaje que indique si el servicio en la nube ha aceptado o rechazado la respuesta del dispositivo.
**nota**
Es opcional que sus vehículos se suscriban a los temas `/accepted` y a los temas de `/rejected` respuesta. Tus vehículos recibirán automáticamente estos mensajes de respuesta, incluso si no se han suscrito explícitamente a estos temas.
```
$aws/commands/things//executions//response/protobuf/accepted
$aws/commands/things//executions//response/protobuf/rejected
```
1.
**Actualización del resultado de la ejecución de un comando**
A continuación, el vehículo objetivo procesa el comando. A continuación, utiliza la `UpdateCommandExecution` API para publicar el resultado de la ejecución en el siguiente tema de respuesta de MQTT.
**nota**
Para ejecutar un vehículo y un comando determinados, ** debe coincidir con el campo correspondiente del tema de solicitud al que se haya suscrito el dispositivo.
```
$aws/commands/things//executions//response/protobuf
```
La `UpdateCommandExecution` API es una operación de API de plano de datos a través de MQTT que se autentica con TLS.
+ Si el servicio en la nube procesó correctamente el resultado de la ejecución del comando, se publicará un mensaje en el tema aceptado por MQTT. El tema aceptado utiliza el siguiente formato.
```
$aws/commands/things//executions//response/protobuf/accepted
```
+ Si el servicio en la nube no ha podido procesar el resultado de la ejecución del comando, se publica una respuesta al tema de MQTT rechazado. El tema rechazado utiliza el siguiente formato.
```
$aws/commands/things//executions//response/protobuf/rejected
```
Para obtener más información sobre esta API y un ejemplo, consulte[Actualiza el resultado de la ejecución del comando](send-monitor-remote-command-cli.md#update-remote-command-execution-cli).
## Flujo de trabajo de comandos
Los siguientes pasos describen en detalle el flujo de trabajo de los comandos.
**nota**
Las operaciones que se describen en esta sección utilizan el protocolo HTTP.
1.
**Registre su vehículo**
Ahora que ha preparado su vehículo para usar la función de comandos, puede preparar su solicitud registrando su vehículo y, a continuación, creando un comando que se enviará al vehículo. Para registrar el vehículo, cree una instancia de un modelo de vehículo (manifiesto del modelo) mediante la operación API del 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)control. Para obtener más información y ejemplos, consulte [Crear un vehículo](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/create-vehicle.html).
1.
**Cree un comando**
Usa la operación de la API del plano de control [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 los comandos que se apliquen al vehículo al que te diriges. Especifique los parámetros y valores predeterminados que se utilizarán al ejecutar el comando y asegúrese de que utilice el espacio de `AWS-IoT-FleetWise` nombres. Para obtener más información y ejemplos sobre el uso de esta API, consulte. [Creación de un recurso de comandos](create-manage-remote-command-cli.md#create-remote-command-cli)
1.
**Inicie la ejecución del comando**
Ahora puede ejecutar el comando que creó en el vehículo mediante la operación de la API del 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)datos. AWS IoT Device Management obtiene el comando y los parámetros del comando y valida la solicitud entrante. A continuación, invoca la AWS IoT FleetWise API con los parámetros necesarios para generar la carga útil específica del vehículo. Luego, la carga útil se envía al dispositivo a AWS IoT Device Management través de MQTT al tema de solicitud de comando al que está suscrito el dispositivo. Para obtener más información y ejemplos sobre el uso de esta API, consulte. [Envía un comando ()AWS CLI](send-monitor-remote-command-cli.md#send-remote-command-cli)
```
$aws/commands/things//executions/+/request/protobuf
```
**nota**
Si el dispositivo estaba desconectado cuando se envió el comando desde la nube y se estaban utilizando sesiones persistentes de MQTT, el comando espera en el intermediario de mensajes. Si el dispositivo vuelve a conectarse antes de que se agote el tiempo de espera y se ha suscrito al tema de solicitud de comandos, el dispositivo podrá procesar el comando y publicar el resultado en el tema de respuesta. Si el dispositivo no vuelve a conectarse antes de que se agote el tiempo de espera, se agotará el tiempo de espera de la ejecución del comando y el mensaje de carga caducará.
1.
**Recupera la ejecución del comando**
Tras ejecutar el comando en el dispositivo, utilice la operación de la API del plano de [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html)control para recuperar y supervisar el resultado de la ejecución del comando. También puede usar la API para obtener información adicional sobre los datos de ejecución, como cuándo se actualizaron por última vez, cuándo se completó la ejecución y los parámetros especificados.
**nota**
Para recuperar la información de estado más reciente, el dispositivo debe haber publicado el resultado de la ejecución del comando en el tema de respuesta.
Para obtener más información y ejemplos sobre el uso de esta API, consulte[Obtenga la ejecución de comandos](send-monitor-remote-command-cli.md#get-remote-command-execution-cli).
## (Opcional) Comandos y notificaciones
Puede suscribirse a los eventos de comandos para recibir notificaciones cuando cambie el estado de la ejecución de un comando. En los siguientes pasos se muestra cómo suscribirse a los eventos de comandos y, a continuación, procesarlos.
1.
**Creación de una regla del tema**
Puede suscribirse al tema de eventos de comandos y recibir notificaciones cuando cambie el estado de la ejecución de un comando. También puede crear una regla temática para dirigir los datos procesados por el vehículo a otras aplicaciones, como AWS Lambda las funciones. Puede crear una regla temática mediante la AWS IoT consola o la operación de la API del 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 control. Para obtener más información, consulte [Creación de una AWS IoT regla](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-rule.html).
En este ejemplo, sustituya `` por el identificador del comando del que desea recibir notificaciones y `` por el estado de la ejecución del comando.
```
$aws/events/commandExecution//
```
**nota**
Para recibir notificaciones de todos los comandos y estados de ejecución de los comandos, puede utilizar caracteres comodín y suscribirse al tema siguiente.
```
$aws/events/commandExecution/+/#
```
1.
**Recepción y procesamiento de los eventos de comandos**
Si has creado una regla temática en el paso anterior para suscribirte a los eventos de comandos, puedes gestionar las notificaciones push de comandos que recibas. Si lo desea, también puede crear aplicaciones sobre ella, por ejemplo, con Amazon SQS AWS Lambda, Amazon SNS o Step AWS Functions mediante la regla de tema que ha creado.
En el siguiente código se muestra un ejemplo de carga útil para las notificaciones de eventos de comandos que recibirá.
```
{
"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
}
```
# Creación y administración de comandos
**importante**
El acceso a ciertas FleetWise funciones de AWS IoT está actualmente restringido. Para obtener más información, consulte [AWS Disponibilidad regional y de funciones en el AWS IoT FleetWise](fleetwise-regions.md).
Puedes configurar acciones remotas reutilizables o enviar instrucciones únicas e inmediatas a tus dispositivos. Al utilizar esta función, puede especificar las instrucciones que sus dispositivos pueden ejecutar prácticamente en tiempo real. Un comando te permite configurar acciones remotas reutilizables para el vehículo objetivo. Tras crear un comando, puedes iniciar la ejecución de un comando dirigido a un vehículo específico.
En este tema se muestra cómo puede crear y administrar un recurso de comando mediante la AWS IoT Core API o el AWS CLI. En él se muestra cómo realizar las siguientes acciones en un recurso de comandos.
**Topics**
+ [Creación de un recurso de comandos](#create-remote-command-cli)
+ [Recuperación de información sobre un comando](#get-remote-command-cli)
+ [Enumere los comandos de su cuenta](#list-remote-command-cli)
+ [Actualiza o desactiva un recurso de comando](#update-remote-command-cli)
+ [Eliminación de un recurso de comandos](#delete-remote-command-cli)
## Creación de un recurso de comandos
Puede usar la operación de la API del 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 control o la FleetWise consola de AWS IoT para crear un comando.
### Cree un comando (consola)
Puede usar la FleetWise consola de AWS IoT para crear un comando.
**Para crear un comando**
1. Abre la [ FleetWise consola AWS de IoT](https://console.aws.amazon.com/iotfleetwise).
1. En el panel de navegación, selecciona **Comandos**.
1. Seleccione **Crear comando**.
1. Especifique un identificador de comando único que le ayude a identificar el comando que desea ejecutar en el vehículo.
1. (Opcional) Especifique un nombre y una descripción opcionales para mostrar.
1. (Opcional) Seleccione el actuador y el valor del parámetro por defecto. Los parámetros especifican las acciones que el vehículo objetivo puede realizar al recibir el comando. Si no agrega parámetros, tendrá que proporcionarlos cuando ejecute el comando.
1. Elija una función de IAM que conceda permisos para generar la carga útil de los comandos. Consulte [Controlar el acceso](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html#generate-command-payload).
1. Seleccione **Crear comando**.
### Crea un comando (AWS CLI)
El siguiente ejemplo muestra cómo crear un comando con un parámetro.
#### Consideraciones a la hora de crear un comando
Al crear un comando en AWS IoT FleetWise:
+ Debe especificar el `roleArn` que otorga el permiso para crear y ejecutar comandos en su vehículo. Para obtener más información y ejemplos de políticas, incluidos los casos en que las claves KMS están habilitadas, consulte[Conceda AWS IoT Device Management permiso para generar la carga útil de los comandos con AWS IoT FleetWise](controlling-access.md#generate-command-payload).
+ Debe especificarlo `AWS-IoT-FleetWise` como espacio de nombres.
+ Puede omitir el `mandatory-parameters` campo y especificarlos en tiempo de ejecución. Como alternativa, puede crear un comando con parámetros y, si lo desea, especificar valores por defecto para ellos. Si especificó valores por defecto, en tiempo de ejecución, puede utilizarlos o anularlos especificando sus propios valores. Para ver estos ejemplos adicionales, consulte[Escenarios de uso de comandos](remote-command-use-cases.md).
+ Puede especificar hasta tres pares de nombre-valor para el `mandatory-parameters` campo. Sin embargo, al ejecutar el comando en el vehículo, solo se acepta un par nombre-valor y el `name` campo debe usar el nombre completo con el prefijo. `$actuatorPath.`
+ *command-id*Sustitúyalo por un identificador único para el comando. Puede usar el UUID, los caracteres alfanuméricos, «-» y «\$1».
+ *role-arn*Sustitúyalo por el rol de IAM que te otorga permiso para crear y ejecutar comandos, por ejemplo,. `"arn:aws:iam:accountId:role/FwCommandExecutionRole"`
+ (Opcional) *display-name* Sustitúyalo por un nombre fácil de usar para el comando y *description* por una descripción significativa del comando.
+ Sustituya *name* y *value* del `mandatory-parameters` objeto por la información necesaria para el comando que se va a crear. El `name` campo es el nombre completo, tal como se define en el catálogo de señales, con `$actuatorPath.` el prefijo. Por ejemplo, `name` puede ser *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode* y `value` puede ser un booleano que indica el estado de un modo de dirección similar. *\$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
}
]'
```
La operación de la `CreateCommand` API devuelve una respuesta que contiene el ID y el ARN (Amazon Resource Name) del comando.
```
{
"commandId": "HandsOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"
}
```
## Recuperación de información sobre un comando
Puede utilizar la operación de la API del 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 control para recuperar información sobre un recurso de comando.
Para obtener información sobre un recurso de comando, ejecute el siguiente comando. *command-id*Sustitúyalo por el identificador que se utilizó al crear el comando.
```
aws iot get-command --command-id command-id
```
La operación de la `GetCommand` API devuelve una respuesta que contiene la siguiente información.
+ El ID y el ARN (Amazon Resource Name) del comando.
+ La fecha y la hora en que se creó el comando y se actualizó por última vez.
+ El estado del comando, que indica si está disponible para ejecutarse en el vehículo.
+ Todos los parámetros que especificó al crear el 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
}
```
## Enumere los comandos de su cuenta
Puede utilizar la operación de la API del 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 control para enumerar todos los comandos de la cuenta que haya creado.
Para enumerar los comandos de tu cuenta, ejecuta el siguiente comando. De forma predeterminada, la API devuelve los comandos que se crearon para ambos espacios de nombres. Para filtrar la lista y mostrar solo los comandos para los que se crearon AWS IoT FleetWise, ejecuta el siguiente comando.
**nota**
También puede ordenar la lista en orden ascendente o descendente, o bien filtrarla para que muestre solo los comandos que tengan un nombre de parámetro de comando específico.
```
aws iot list-commands --namespace "AWS-IoT-FleetWise"
```
La operación `ListCommands` de la API devuelve una respuesta que contiene la siguiente información.
+ El ID y el ARN (Amazon Resource Name) de los comandos.
+ La fecha y la hora en que se creó el comando y se actualizó por última vez.
+ El estado del comando, que indica si los comandos están disponibles para ejecutarse en el vehículo.
## Actualiza o desactiva un recurso de comando
Puede usar la operación de la API del 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 control o la FleetWise consola de AWS IoT para actualizar un recurso de comando. Puede actualizar el nombre mostrado y la descripción de un comando. También puedes dejar de usar un comando si no se está utilizando actualmente.
**nota**
No puede modificar la información del espacio de nombres ni los parámetros que se van a utilizar al ejecutar el comando.
### Actualizar un comando (consola)
**Actualizar un comando**
Para actualizar un comando desde la consola, vaya a la página [Comandos](https://console.aws.amazon.com/iotfleetwise/home#/commands) de la FleetWise consola de AWS IoT y lleve a cabo los siguientes pasos.
1. Elija el comando que desee actualizar y, a continuación, elija **Editar**.
1. Edite los detalles del comando y, a continuación, elija **Guardar cambios**.
**Desactivar un comando**
Para anular un comando de la consola, vaya a la página [Comandos](https://console.aws.amazon.com/iotfleetwise/home#/commands) de la FleetWise consola de AWS IoT y lleve a cabo los siguientes pasos.
1. **Elija el comando que desee desaprobar y, a continuación, elija Deprecar.**
1. **Confirme la obsolescencia y, a continuación, elija Deprecatar.**
### Actualizar un comando ()AWS CLI
**Actualizar un comando**
Para actualizar un recurso de comandos, ejecute el siguiente comando. *command-id*Sustitúyalo por el identificador del comando que desee actualizar y proporcione el *display-name* y actualizado*description*.
```
aws iot update-command \
--command-id command-id \
--display-name display-name \
--description description
```
La operación `UpdateCommand` de la API devuelve la siguiente respuesta.
```
{
"commandId": "HandsOffSteeringMode",
"deprecated": false,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
**Desactivar un comando**
Se desaprueba un comando cuando se pretende dejar de usarlo en el dispositivo o cuando está desactualizado. En el siguiente ejemplo, se muestra cómo hacer que un comando quede obsoleto.
```
aws iot update-command \
--command-id command-id \
--deprecated
```
La operación de la `UpdateCommand` API devuelve una respuesta que contiene el ID y el ARN (Amazon Resource Name) del comando.
```
{
"commandId": "HandsOffSteeringMode",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
Una vez que un comando ha quedado obsoleto, las ejecuciones de comandos existentes seguirán ejecutándose en el vehículo hasta que pasen a ser inútiles. Para ejecutar cualquier comando nuevo, debes usar la `UpdateCommand` API para restaurar el comando de forma que esté disponible. *Para obtener información adicional sobre la obsolescencia y la restauración de un comando y las consideraciones al respecto, consulte Cómo [desaprobar un recurso de comandos](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-deprecate) en la AWS IoT Core Guía para desarrolladores.*
## Eliminación de un recurso de comandos
Puede usar la operación de la API del 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 control o la FleetWise consola de AWS IoT para eliminar un recurso de comando.
**nota**
Las acciones de eliminación son permanentes y no se pueden deshacer. El comando se eliminará permanentemente de tu cuenta.
### Eliminar un comando (consola)
Para eliminar un comando de la consola, vaya a la página [Comandos](https://console.aws.amazon.com/iotfleetwise/home#/commands) de la FleetWise consola de AWS IoT y lleve a cabo los siguientes pasos.
1. Elija el comando que desee eliminar y, a continuación, elija **Eliminar**.
1. Confirme que desea eliminar el comando y, a continuación, elija **Eliminar**.
### Eliminar un comando (AWS CLI)
Para eliminar un recurso de comando, ejecute el siguiente comando. *command-id*Sustitúyalo por el identificador del comando que desee eliminar. El siguiente ejemplo muestra cómo eliminar un recurso de comando.
```
aws iot delete-command --command-id command-id
```
Si la solicitud de eliminación se ha realizado correctamente:
+ Si el comando ha quedado obsoleto durante un período superior al tiempo de espera máximo de 24 horas, se eliminará inmediatamente y aparecerá un HTTP `statusCode` de 204.
+ Si el comando no está obsoleto o ha estado en desuso durante un tiempo inferior al tiempo de espera máximo, el comando estará en un `pending deletion` estado y aparecerá un HTTP de 202. `statusCode` El comando se eliminará automáticamente de tu cuenta una vez transcurrido el tiempo de espera máximo de 24 horas.
# Inicio y supervisión de las ejecuciones de comandos
**importante**
El acceso a ciertas FleetWise funciones de AWS IoT está actualmente restringido. Para obtener más información, consulte [AWS Disponibilidad regional y de funciones en el AWS IoT FleetWise](fleetwise-regions.md).
Una vez que hayas creado un recurso de comando, puedes iniciar la ejecución de un comando en el vehículo objetivo. Una vez que el vehículo comience a ejecutar el comando, podrá empezar a actualizar el resultado de la ejecución del comando y publicar las actualizaciones de estado y la información sobre los resultados en los temas reservados de MQTT. A continuación, puede recuperar el estado de la ejecución del comando y supervisar el estado de las ejecuciones en su cuenta.
En este tema se muestra cómo puede enviar un comando a su vehículo mediante la AWS CLI FleetWise consola de AWS IoT. También se muestra cómo supervisar y actualizar el estado de la ejecución del comando.
**Topics**
+ [Actualiza el resultado de la ejecución del comando](#update-remote-command-execution-cli)
+ [Obtenga la ejecución de comandos](#get-remote-command-execution-cli)
+ [Enumera las ejecuciones de comandos en tu cuenta](#list-remote-command-execution-cli)
+ [Eliminación de una ejecución de comandos](#delete-remote-command-execution-cli)
## Enviar un comando (consola)
Para enviar un comando desde la consola, vaya a la página [Vehículos](https://console.aws.amazon.com/iotfleetwise/home#/vehicles) de la FleetWise consola AWS IoT y lleve a cabo los siguientes pasos.
1. Elige el vehículo al que quieres enviar un comando.
1. Elija **Run command (Ejecutar comando)**.
1. Selecciona el ID del comando.
1. Especifique el tiempo de espera de ejecución del comando y, a continuación, elija **Ejecutar comando**.
## Envía un comando ()AWS CLI
Puede utilizar la operación de la API del 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 datos para enviar un comando a un vehículo. A continuación, el vehículo reenvía el comando a un servicio de software intermedio para automoción (por ejemplo SOME/IP , software intermedio escalable orientado a servicios sobre IP) o lo publica en la red de un vehículo (como la interfaz de un dispositivo de red de área de controlador (CAN)). El siguiente ejemplo utiliza AWS CLI.
**Topics**
+ [Consideraciones a la hora de enviar un comando](#send-remote-command-considerations)
+ [Obtención del punto de conexión del plano de datos específico de la cuenta](#send-remote-command-endpoint)
+ [Envía un ejemplo de comando](#send-remote-command-example)
### Consideraciones a la hora de enviar un comando
Al iniciar la ejecución de un comando en AWS IoT FleetWise:
+ Debe aprovisionar cualquier AWS IoT cosa para el vehículo. Para obtener más información, consulte [Aprovisionamiento AWS de FleetWise vehículos de IoT](provision-vehicles.md).
+ Debe haber creado ya un comando `AWS-IoT-FleetWise` como espacio de nombres y haber proporcionado uno `role-Arn` que le otorgue permiso para crear y ejecutar comandos en el IoT AWS . FleetWise Para obtener más información, consulte [Creación de un recurso de comandos](create-manage-remote-command-cli.md#create-remote-command-cli).
+ Puede omitir el `parameters` campo si decide usar cualquier valor predeterminado que se especificó para los parámetros al crear el comando. Si `mandatory-parameters` no se especificó en el momento de la creación, o si desea anular cualquier valor predeterminado especificando sus propios valores para los parámetros, debe especificar el `parameters` campo. Para ver estos ejemplos adicionales, consulte[Escenarios de uso de comandos](remote-command-use-cases.md).
+ Puede especificar hasta tres pares de nombre-valor para el `mandatory-parameters` campo. Sin embargo, al ejecutar el comando en el vehículo, solo se acepta un par nombre-valor y el `name` campo debe usar el nombre completo con el prefijo. `$actuatorPath.`
### Obtención del punto de conexión del plano de datos específico de la cuenta
Antes de ejecutar el comando de la API, debe obtener la URL del punto final específica de la cuenta para el punto final. `iot:Jobs` Por ejemplo, si ejecuta este comando:
```
aws iot describe-endpoint --endpoint-type iot:Jobs
```
Devolverá la URL del punto de conexión específico de la cuenta, tal y como se muestra en el ejemplo de respuesta que aparece a continuación.
```
{
"endpointAddress": ".jobs.iot..amazonaws.com"
}
```
### Envía un ejemplo de comando
Para enviar un comando a un vehículo, ejecute el siguiente comando.
+ *command-arn*Sustituya el comando que desee ejecutar por el ARN. Puede obtener esta información de la respuesta del comando `create-command` de la CLI.
+ *target-arn*Sustitúyalo por el ARN del dispositivo o AWS IoT elemento de destino para el que desee ejecutar el comando.
**nota**
Puede especificar el ARN objetivo de cualquier AWS IoT cosa ( FleetWise vehículo AWS IoT). Actualmente, no se admiten grupos de cosas ni flotas.
+ *endpoint-url*Sustitúyalo por el punto final específico de la cuenta que obtuviste[Obtención del punto de conexión del plano de datos específico de la cuenta](#send-remote-command-endpoint), con el prefijo, por ejemplo`https://`,. `https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com`
+ Sustituya *name* y *value* por el `mandatory-parameters` campo que especificó al crear el comando mediante la `create-command` CLI.
El `name` campo es el nombre completo tal como se define en el catálogo de señales con `$actuatorPath.` el prefijo. Por ejemplo, `name` puede ser *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode* y `value` puede ser un booleano que indica el estado de un modo de dirección similar. *\$1"B": false\$1*
+ (Opcional) También puede especificar un parámetro adicional,. `executionTimeoutSeconds` Este campo opcional especifica el tiempo en segundos dentro del cual el dispositivo debe responder con el resultado de la ejecución. Puede configurar el tiempo de espera en un valor máximo de 24 horas.
Cuando se ha creado la ejecución del comando, se inicia un temporizador. Antes de que caduque el temporizador, si el estado de ejecución del comando no cambia a un estado que lo convierta en terminal (por ejemplo`FAILED`, `SUCCEEDED` o), el estado cambia automáticamente a`TIMED_OUT`.
**nota**
El dispositivo también puede informar de un `TIMED_OUT` estado o anular este estado a un estado como`SUCCEEDED`, o `FAILED``REJECTED`, y la ejecución del comando pasará a ser terminal. Para obtener más información, consulte [Estado de espera de ejecución del 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
}
]'
```
La operación `StartCommandExecution` de la API devuelve un identificador de ejecución de comandos. Puede usar este ID para consultar el estado de ejecución del comando, los detalles y el historial de ejecución del comando.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
Tras ejecutar el comando, los dispositivos recibirán una notificación con la siguiente información. El `issued_timestamp_ms` campo corresponde a la hora en que se invocó la `StartCommandExecution` API. `timeout_ms`Corresponde al valor de tiempo de espera que se configura mediante el `executionTimeoutSeconds` parámetro al invocar la `StartCommandExecution` API.
```
timeout_ms: 9000000
issued_timestamp_ms: 1723847831317
```
## Actualiza el resultado de la ejecución del comando
Para actualizar el estado de la ejecución del comando, el dispositivo debe haber establecido una conexión MQTT y estar suscrito al siguiente tema de solicitud de comandos.
En este ejemplo, *``* sustitúyalo por el identificador único del dispositivo de destino, que puede ser el nombre `VehicleId` o el nombre de la cosa, y *``* por el identificador de la ejecución del comando.
**nota**
La carga útil debe usar el formato protobuf.
Es opcional que sus dispositivos se suscriban a los temas `/accepted` y `/rejected` a los temas de respuesta. Tus dispositivos recibirán estos mensajes de respuesta aunque no se hayan suscrito a ellos de forma explícita.
```
// 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
```
El dispositivo puede publicar un mensaje en el tema de respuesta a los comandos. Tras procesar el comando, envía una respuesta codificada en protobuf a este tema. El ** campo debe coincidir con el campo correspondiente del tema de la solicitud.
```
$aws/devices//command_executions//response/
```
Una vez que tu dispositivo publique una respuesta a este tema, podrás recuperar la información de estado actualizada mediante la `GetCommandExecution` API. El estado de la ejecución de un comando puede ser cualquiera de los que se muestran aquí.
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`
+ `REJECTED`
+ `TIMED_OUT`
Tenga en cuenta que un comando se ejecuta en cualquiera de los estados `SUCCEEDED` y `REJECTED` es terminal, y el estado lo informa el dispositivo. `FAILED` Cuando la ejecución de un comando es terminal, esto significa que no se realizarán más actualizaciones en su estado ni en los campos relacionados. El dispositivo o la nube pueden informar de un `TIMED_OUT` estado. Si lo informa la nube, el dispositivo podrá actualizar posteriormente el campo de motivo del estado.
Por ejemplo, a continuación se muestra un ejemplo de mensaje MQTT publicado por el dispositivo.
**nota**
En cuanto al estado de ejecución del comando, si sus dispositivos utilizan el `statusReason` objeto para publicar la información de estado, debe asegurarse de que:
`reasonCode`Utiliza el patrón `[A-Z0-9_-]+` y su longitud no supera los 64 caracteres.
La longitud `reasonDescription` no supera los 1024 caracteres. Puede utilizar cualquier carácter excepto los caracteres de control, como, por ejemplo, líneas nuevas.
```
{
"deviceId": "",
"executionId": "",
"status": "CREATED",
"statusReason": {
"reasonCode": "",
"reasonDescription": ""
}
}
```
*Para ver un ejemplo que muestre cómo utilizar el cliente de pruebas de AWS IoT Core MQTT para suscribirse a los temas y ver los mensajes de ejecución de los comandos, consulte [Visualización de las actualizaciones de los comandos mediante el cliente de pruebas de MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-remote-command-execution-update-mqtt) en la AWS IoT Core guía para desarrolladores.*
## Obtenga la ejecución de comandos
Puede utilizar la operación de la API del 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 control para recuperar información sobre la ejecución de un comando. Ya debe haber ejecutado este comando mediante la operación de la API `StartCommandExecution`.
Para recuperar los metadatos de un comando ejecutado, ejecute el siguiente comando.
+ *execution-id*Sustitúyalo por el ID del comando. Puede obtener esta información de la respuesta del comando `start-command-execution` de la CLI.
+ *target-arn*Sustitúyalo por el ARN del vehículo o AWS IoT objeto objetivo para el que desee ejecutar el comando.
```
aws iot get-command-execution --execution-id execution-id \
--target-arn target-arn
```
La operación de la `GetCommandExecution` API devuelve una respuesta que contiene información sobre el ARN de la ejecución del comando, el estado de la ejecución y la hora en que el comando comenzó a ejecutarse y se completó. En el siguiente código se muestra un ejemplo de respuesta de la solicitud de la API.
Para proporcionar un contexto adicional sobre el estado de la ejecución de cada comando, la función de comandos proporciona un `statusReason` objeto. El objeto contiene dos campos: `reasonCode` y`reasonDescription`. Con estos campos, sus dispositivos pueden proporcionar información adicional sobre el estado de la ejecución de un comando. Esta información anulará cualquier valor predeterminado `reasonCode` `reasonDescription` que se informe desde la nube.
Para reportar esta información, sus dispositivos pueden publicar la información de estado actualizada en la nube. Luego, cuando recuperes el estado de ejecución del comando mediante la `GetCommandExecution` API, verás los códigos de estado más recientes.
**nota**
El campo `completedAt` de la respuesta de ejecución corresponde al momento en que el dispositivo informa a la nube de un estado final. En el caso del `TIMED_OUT` estado, este campo solo se configurará cuando el dispositivo indique que se ha agotado el tiempo de espera. Cuando la nube establece el estado `TIMED_OUT`, no se actualizará el estado `TIMED_OUT`. Para obtener más información sobre el comportamiento del tiempo de espera, consulte [Estado de espera de ejecución del 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 }
}'
}
```
## Enumera las ejecuciones de comandos en tu cuenta
Usa la operación de la API HTTP del 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 control para enumerar todas las ejecuciones de comandos en tu cuenta. Este ejemplo usa AWS CLI.
**Topics**
+ [Consideraciones al enumerar las ejecuciones de comandos](#list-remote-command-considerations)
+ [Ejemplo de enumeración de las ejecuciones de comandos](#list-remote-command-example)
### Consideraciones al enumerar las ejecuciones de comandos
Las siguientes son algunas consideraciones a tener en cuenta a la hora de utilizar la `ListCommandExecutions` API.
+ Debe especificar al menos las ejecuciones de un comando en particular `targetArn` o de un vehículo objetivo, `commandArn` dependiendo de si desea enumerar las ejecuciones. La solicitud de API no puede estar vacía y no puede contener ambos campos en la misma solicitud.
+ Debe proporcionar únicamente la información `startedTimeFilter` o la `completedTimeFilter` información. La solicitud de API no puede estar vacía ni puede contener ambos campos en la misma solicitud. Puede usar los `after` campos `before` y del objeto para enumerar las ejecuciones de comandos que se crearon o completaron en un período de tiempo específico.
+ Los `after` campos `before` y no deben ser posteriores a la hora actual. De forma predeterminada, si no especificas ningún valor, el `before` campo es la hora actual y `after` la hora actual (6 meses). Es decir, según el filtro que utilices, la API mostrará una lista de todas las ejecuciones que se hayan creado o completado en los últimos seis meses.
+ Puede usar el `sort-order` parámetro para especificar si desea enumerar las ejecuciones en orden ascendente. De forma predeterminada, las ejecuciones se muestran en orden descendente si no especificas este campo.
+ No puede filtrar las ejecuciones de comandos en función de su estado al enumerar las ejecuciones de comandos de un ARN de comando.
### Ejemplo de enumeración de las ejecuciones de comandos
En el siguiente ejemplo se muestra cómo enumerar las ejecuciones de comandos en la Cuenta de AWS.
Al ejecutar el comando, debe especificar si desea filtrar la lista para que muestre únicamente las ejecuciones de comandos que se hayan creado para un determinado dispositivo mediante el `targetArn` o las ejecuciones de un determinado comando especificado mediante el `commandArn`.
En este ejemplo, sustituya:
+ *``* con el nombre de recurso de Amazon (ARN) del dispositivo al que se dirige la ejecución, como, por ejemplo, `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`.
+ *``* con el nombre de recurso de Amazon (ARN) del dispositivo al que se dirige la ejecución, como, por ejemplo, `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`.
+ *``* con el tiempo transcurrido a partir del cual desea enumerar las ejecuciones que se crearon, por ejemplo, `2024-11-01T03:00`.
```
aws iot list-command-executions \
--target-arn \
--started-time-filter '{after=}' \
--sort-order "ASCENDING"
```
Al ejecutar este comando, se genera una respuesta que incluye una lista de las ejecuciones de comandos que ha creado, el momento en que las ejecuciones comenzaron a ejecutarse y el momento en que finalizaron. También proporciona información sobre el estado, así como el objeto de `statusReason` que incluye información adicional sobre el estado.
```
{
"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"
}
]
}
```
## Eliminación de una ejecución de comandos
Si ya no quiere usar una ejecución de comandos, puede eliminarla permanentemente de la cuenta.
**nota**
La ejecución de un comando solo se puede eliminar si ha pasado a un estado final, como, por ejemplo, `SUCCEEDED`, `FAILED` o `REJECTED`.
En el siguiente ejemplo, se muestra cómo eliminar la ejecución de un comando mediante el `delete-command-execution` AWS CLI comando. *``*Sustitúyalo por el identificador de la ejecución del comando que va a eliminar.
```
aws iot delete-command-execution --execution-id
```
Si la solicitud a la API se realiza correctamente, la ejecución de comandos generará un código de estado 200. Puede usar la API `GetCommandExecution` para comprobar que la ejecución de comandos ya no existe en la cuenta.
# Ejemplo: Uso de comandos para controlar el modo de dirección de un vehículo (AWS CLI)
**importante**
El acceso a ciertas FleetWise funciones de AWS IoT está actualmente restringido. Para obtener más información, consulte [AWS Disponibilidad regional y de funciones en el AWS IoT FleetWise](fleetwise-regions.md).
El siguiente ejemplo muestra cómo utilizar la función de comandos mediante el AWS CLI. En este ejemplo, se utiliza un AWS IoT FleetWise vehículo como dispositivo objetivo para mostrar cómo se puede enviar un comando para controlar de forma remota el modo de dirección.
**Topics**
+ [Ejemplo de descripción general del modo de dirección del vehículo](#iot-remote-command-tutorial-overview)
+ [Requisitos previos](#iot-remote-command-tutorial-prereq)
+ [Política de IAM para el uso de comandos remotos](#remote-command-policy)
+ [Ejecute AWS IoT comandos (AWS CLI)](#iot-remote-command-tutorial-run)
+ [Limpieza](#remote-command-tutorial-clean)
## Ejemplo de descripción general del modo de dirección del vehículo
En este ejemplo, podrás:
1. Cree un recurso de comando para la operación y `create-command` AWS CLI utilícelo para cambiar el modo de dirección del vehículo.
1. Recupere información sobre el comando, como la hora en que se creó o se actualizó por última vez mediante el `get-command` AWS CLI.
1. Envíe el comando al vehículo utilizando el `start-command-execution` AWS CLI modo de dirección como parámetro obligatorio, que luego se ejecutará en el dispositivo.
1. Obtenga el resultado de la ejecución del comando mediante el `get-command-execution` AWS CLI. Puede comprobar cuándo se completa la ejecución y recuperar detalles adicionales, como el resultado de la ejecución y el tiempo que se tardó en completar la ejecución del comando.
1. Realice actividades de limpieza eliminando todos los comandos y las ejecuciones de comandos que ya no desee utilizar.
## Requisitos previos
Antes de ejecutar este ejemplo:
+ Aprovisione su AWS IoT FleetWise vehículo como una AWS IoT cosa inscrita en el AWS IoT registro. También debes añadir un certificado a lo tuyo y activarlo, y adjuntar una política a lo tuyo. Luego, su dispositivo puede conectarse a la nube y ejecutar los comandos. Para obtener más información, consulte [Aprovisionar vehículos](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/provision-vehicles.html).
+ Cree un usuario de IAM y una política de IAM que le conceda permiso para realizar las operaciones de la API relacionadas con el uso de comandos, como se muestra en. [Política de IAM para el uso de comandos remotos](#remote-command-policy)
## Política de IAM para el uso de comandos remotos
En la siguiente tabla se muestra un ejemplo de política de IAM que permite el acceso a todas las operaciones de la API del plano de control y del plano de datos para la función de comandos. El usuario de la aplicación tendrá permisos para realizar todas las operaciones de la API de comandos remotos, como se muestra en la tabla.
**Operación de la API**
| Acción de la API | Plano de control/datos | Protocolo | Description (Descripción) | Recurso |
| --- | --- | --- | --- | --- |
| CreateCommand | Plano de control | HTTP | Crea un recurso de comandos | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommand | Plano de control | HTTP | Recupera información sobre un comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommand | Plano de control | HTTP | Actualiza la información sobre un comando o lo deja obsoleto | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommands | Plano de control | HTTP | Muestra los comandos de tu cuenta | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommand | Plano de control | HTTP | Elimina un comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| StartCommandExecution | Plano de datos | HTTP | Comienza a ejecutar un comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommandExecution | Plano de datos | MQTT | Actualiza la ejecución de un comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommandExecution | Plano de control | HTTP | Recupera información sobre la ejecución de un comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommandExecutions | Plano de control | HTTP | Muestra las ejecuciones de comandos en su cuenta | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommandExecution | Plano de control | HTTP | Elimina la ejecución de un comando | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
En este ejemplo, sustituya:
+ `us-east-1`con tu Región de AWS, como`ap-south-1`.
+ `111122223333` con el número de la Cuenta de AWS , como, por ejemplo `57EXAMPLE833`.
+ `command-id``command-id1`, y `command-id2` con su identificador de comando único, como `LockDoor` o`TurnOffAC`.
+ `thing-name`con el nombre de tu AWS IoT cosa, 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"
]
}
]
}
```
------
## Ejecute AWS IoT comandos (AWS CLI)
A continuación, se muestra cómo se puede utilizar AWS CLI para ejecutar operaciones con comandos y cambiar el modo de dirección del vehículo.
1.
**Cree un recurso de comando para el funcionamiento del modo de dirección**
Cree el comando que desee enviar a su dispositivo mediante la `create-command` CLI. En este ejemplo, especifique:
+ `command-id` como *`TurnOffSteeringMode`*
+ `role-arn`ya que `role-arn` debe proporcionarse `"arn:aws:iam:accountId:role/FwCommandExecutionRole"` la función de IAM, ya que es la función de IAM la que otorga los permisos para crear y ejecutar comandos en el vehículo. Para obtener más información, consulte [Conceda AWS IoT Device Management permiso para generar la carga útil de los comandos con AWS IoT FleetWise](controlling-access.md#generate-command-payload).
+ `display-name`como "» *`Turn off steering mode`*
+ `namespace`debe ser `AWS-IoT-FleetWise`
+ `mandatory-parameters`como un par nombre-valor, con `name` como "*\$1actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode*" y DefaultValue como `{ "S": "true" }`
**nota**
También puede crear un comando sin especificar ningún parámetro obligatorio. A continuación, debe especificar los parámetros que se utilizarán al ejecutar el comando mediante la `start-command-execution` CLI. Para ver un ejemplo, consulta [Escenarios de uso de comandos](remote-command-use-cases.md).
**importante**
Al utilizar el espacio de `AWS-IoT-FleetWise` nombres, debe asegurarse de que el `Name` campo especificado como parte del mismo `mandatory-parameters` utilice el `$actuatorPath.` prefijo y que el `Value` campo utilice el tipo de datos de cadena.
```
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" }
}
]'
```
El siguiente resultado muestra un ejemplo de respuesta de la CLI, donde `ap-south-1` y `123456789012` son ejemplos del Cuenta de AWS ID Región de AWS y.
```
{
"commandId": "TurnOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode"
}
```
Para ver ejemplos adicionales sobre el uso de este comando, consulte[Creación de un recurso de comandos](create-manage-remote-command-cli.md#create-remote-command-cli).
1.
**Recupere información sobre el comando**
Ejecute el siguiente comando para recuperar información sobre el comando, donde `command-id` aparece el identificador del comando en el resultado de la `create-command` operación desde arriba.
**nota**
Si creas más de un comando, puedes usar la `ListCommands` API para enumerar todos los comandos de tu cuenta y, a continuación, usar la `GetCommand` API para obtener información adicional sobre un comando específico. Para obtener más información, consulte [Enumere los comandos de su cuenta](create-manage-remote-command-cli.md#list-remote-command-cli).
```
aws iot get-command --command-id TurnOffSteeringMode
```
La ejecución de este comando genera la siguiente respuesta. Verás la hora en que se creó el comando y cuándo se actualizó por última vez, los parámetros que especificaste y si el comando está disponible para ejecutarse en el 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 ver ejemplos adicionales sobre el uso de este comando, consulte[Recuperación de información sobre un comando](create-manage-remote-command-cli.md#get-remote-command-cli).
1.
**Inicie la ejecución del comando**
Ejecute el siguiente comando para iniciar la ejecución del comando, donde `command-arn` aparece el comando ARN en la salida de la `get-command` operación desde arriba. `target-arn`Es el ARN del dispositivo de destino para el que está ejecutando el comando, por ejemplo,. *`myVehicle`*
En este ejemplo, dado que proporcionó valores predeterminados para los parámetros al crear el comando, la `start-command-execution` CLI puede usar estos valores al ejecutar el comando. También puede optar por anular el valor predeterminado especificando un valor diferente para los parámetros cuando utilice la 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
```
La ejecución de este comando devuelve un ID de ejecución del comando. Puede usar este ID para consultar el estado de ejecución del comando, los detalles y el historial de ejecución del comando.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
Para ver ejemplos adicionales sobre el uso de la CLI, consulte[Envía un comando ()AWS CLI](send-monitor-remote-command-cli.md#send-remote-command-cli).
1.
**Recupere información sobre la ejecución del comando**
Ejecute el siguiente comando para recuperar información sobre el comando que ejecutó en el dispositivo de destino. Especifique el`execution-id`, que obtuvo como resultado de la `start-command-execution` operación desde arriba, y el`target-arn`, que es el ARN del dispositivo al que apunta.
**nota**
Para obtener la información de estado más reciente, sus dispositivos deben haber publicado la información de estado actualizada en el tema de respuesta reservada de MQTT para los comandos que utilizan la API de `UpdateCommandExecution` MQTT. Para obtener más información, consulte [Actualiza el resultado de la ejecución del comando](send-monitor-remote-command-cli.md#update-remote-command-execution-cli).
Si inicia más de una ejecución de comandos, puede utilizar la `ListCommandExecutions` API para enumerar todas las ejecuciones de comandos de su cuenta y, a continuación, utilizarla `GetCommandExecution` para obtener información adicional sobre una ejecución específica. Para obtener más información, consulte [Enumera las ejecuciones de comandos en tu cuenta](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
```
Al ejecutar este comando, se devuelve información sobre la ejecución del comando, el estado de la ejecución, la hora en que comenzó a ejecutarse y la hora en que se completó. Por ejemplo, la siguiente respuesta muestra que la ejecución del comando se realizó correctamente en el dispositivo de destino y que el modo de dirección estaba desactivado.
```
{
"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" }
}'
}
```
## Limpieza
Ahora que ha creado un comando y lo ha ejecutado en su dispositivo, si ya no tiene intención de usarlo, puede eliminarlo. Las ejecuciones de comandos pendientes que estén en curso seguirán ejecutándose sin que se vean afectadas por la solicitud de eliminación.
**nota**
Como alternativa, también puedes dejar de usar un comando si está desactualizado y es posible que tengas que usarlo más adelante para ejecutarlo en el dispositivo de destino.
1.
**(Opcional) Elimine el recurso de comandos**
Ejecute el siguiente comando para dejarlo obsoleto, donde `command-id` aparece el identificador del comando que aparece arriba en el resultado de la `get-command` operación.
```
aws iot update-command \
--command-id TurnOffSteeringMode \
--deprecated
```
La ejecución de este comando devuelve un resultado que indica que el comando ha quedado obsoleto. También puede usar la CLI para restaurar el comando.
**nota**
También puede usar la `update-command` CLI para actualizar el nombre mostrado y la descripción de un comando. Para obtener información adicional, consulta [Actualiza o desactiva un 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.
**Elimine el comando**
Ejecute el siguiente comando para eliminar el comando especificado por`command-id`.
**nota**
La acción de eliminación es permanente y no se puede deshacer.
```
aws iot delete-command --command-id TurnOffSteeringMode
```
Si la solicitud de eliminación se realiza correctamente, verás un HTTP `statusCode` de 202 o 204, dependiendo de si marcaste el comando como obsoleto y de cuándo lo hizo. Para obtener más información y un ejemplo, consulte [Eliminación de un recurso de comandos](create-manage-remote-command-cli.md#delete-remote-command-cli).
Puede usar la `get-command` CLI para comprobar que el comando se ha eliminado de su cuenta.
1.
**(Opcional) Elimine las ejecuciones de comandos**
De forma predeterminada, todas las ejecuciones de comandos se eliminarán en un plazo de seis meses a partir de la fecha en que las haya creado. Puede ver esta información mediante el `timeToLive` parámetro de la `GetCommandExecution` API.
Como alternativa, si la ejecución del comando ha pasado a ser terminal, por ejemplo, cuando el estado de ejecución es uno de `SUCCEEDED``FAILED`, o bien`REJECTED`, puede eliminar la ejecución del comando. Ejecute el siguiente comando para eliminar la ejecución, donde `execution-id` aparece el identificador de ejecución que aparece arriba en el resultado de la `get-command-execution` operación.
```
aws iot delete-command-execution \
--execution-id "07e4b780-7eca-4ffd-b772-b76358da5542"
```
Puede usar la `get-command-execution` CLI para comprobar que la ejecución del comando se ha eliminado de su cuenta.
# Escenarios de uso de comandos
**importante**
El acceso a ciertas FleetWise funciones de AWS IoT está actualmente restringido. Para obtener más información, consulte [AWS Disponibilidad regional y de funciones en el AWS IoT FleetWise](fleetwise-regions.md).
Al utilizar la función de comandos, puede crear y ejecutar comandos en los siguientes escenarios:
+ Puede omitir los parámetros durante la creación y especificar solo el ID del comando. En este caso, debe especificar los parámetros que se utilizarán al ejecutar el comando en el dispositivo de destino.
+ Puede especificar uno o más parámetros y configurar sus valores predeterminados al crear el comando. Proporcionar valores predeterminados le ayudará a evitar el envío de comandos imprecisos.
+ Puede especificar uno o más parámetros y configurar sus valores al crear el comando. Se puede proporcionar más de un parámetro, pero solo se ejecutará uno de ellos, y el `Name` campo de este parámetro debe usar el `$actuatorPath` prefijo.
En esta sección se proporcionan algunos escenarios de uso para la `StartCommandExecution` API `CreateCommand` y el uso de los parámetros. También muestra algunos ejemplos del uso de comandos con plantillas de estado.
**Topics**
+ [Crear un comando sin parámetros](#remote-command-use-case1)
+ [Crear un comando con valores predeterminados para los parámetros](#remote-command-use-case2)
+ [Crear un comando con valores de parámetros](#remote-command-use-case3)
+ [Uso de comandos con plantillas de estado](#remote-command-use-cases-templates)
## Crear un comando sin parámetros
El siguiente caso de uso muestra cómo puede usar la `CreateCommand` API o la `create-command` CLI para crear un comando sin parámetros. Al crear un comando, solo necesita proporcionar un ID de comando y un ARN de rol.
Este caso de uso es especialmente útil en casos de uso recurrentes, como cuando se quiere enviar el mismo comando varias veces a un vehículo. En este caso, el comando no está vinculado a un actuador específico y ofrece la flexibilidad necesaria para ejecutar el comando en cualquier actuador. En lugar de ello, debe especificar los parámetros en tiempo de ejecución al ejecutar el comando mediante la `StartCommandExecution` API o la `start-command-execution` CLI, que incluye los valores de los actuadores y las señales físicas.
### Crear un comando sin entrada `mandatory-parameters`
Este caso de uso muestra cómo crear un comando sin introducir parámetros obligatorios.
```
aws iot create-command \
--command-id "UserJourney1" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--description "UserJourney1 - No mandatory parameters" \
--namespace "AWS-IoT-FleetWise"
```
### Ejecutar un comando creado sin `mandatory-parameters` entrada
En este primer ejemplo, el comando que se creó anteriormente permite ejecutar un comando en cualquier actuador sin restricciones. `actuator1`Para establecer un valor de 10, ejecute:
```
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"}
}'
```
Del mismo modo, puede ejecutar un comando que se establezca `actuator3` en un 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"}
}'
```
## Crear un comando con valores predeterminados para los parámetros
Este comando solo permite ejecutar un comando en el actuador especificado. Proporcionar valores predeterminados le ayudará a evitar el envío de comandos imprecisos. Por ejemplo, un `LockDoor` comando que bloquea y abre puertas se puede configurar con un valor predeterminado para evitar que el comando desbloquee puertas accidentalmente.
Este caso de uso resulta especialmente útil cuando se desea enviar el mismo comando varias veces y realizar diferentes acciones en el mismo actuador, como bloquear y desbloquear las puertas de un vehículo. Si desea configurar el actuador en el valor predeterminado, no necesita pasar ninguno `parameters` a la `start-command-execution` CLI. Si especifica un valor diferente para el `parameters` en la `start-command-execution` CLI, se anulará el valor predeterminado.
### Crear un comando con valores predeterminados para `mandatory-parameters`
El siguiente comando muestra cómo proporcionar un valor por defecto para el actuador1.
```
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"}
}
]'
```
### Ejecutar un comando creado con valores predeterminados para `mandatory-parameters`
El comando `UserJourney2` permite ejecutar un comando sin necesidad de pasar un valor de entrada durante el tiempo de ejecución. En este caso, la ejecución en tiempo de ejecución utilizará los valores predeterminados especificados durante la creación.
```
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
```
También puede pasar un valor diferente para el mismo actuador, el actuator1, durante el tiempo de ejecución, lo que anulará el valor predeterminado.
```
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"}
}'
```
## Crear un comando con valores de parámetros
Este comando solo permite ejecutar un comando en el actuador especificado. También le obliga a establecer un valor para el actuador durante el tiempo de ejecución.
Este caso de uso es especialmente útil cuando se quiere que el usuario final solo realice determinadas acciones específicas en algunos de los actuadores cuando los utilice en el vehículo.
**nota**
Puede tener más de pares nombre-valor para la `mandatory-parameters` entrada, con valores predeterminados para algunos o todos ellos. En tiempo de ejecución, puede determinar el parámetro que desea usar cuando se ejecuta en el actuador, siempre que el nombre del actuador utilice el nombre completo con el prefijo. `$actuatorPath.`
### Crear un comando sin valores predeterminados para `mandatory-parameters`
Este comando solo permite ejecutar un comando en el actuador especificado. También le obliga a establecer un valor para el actuador durante el tiempo de ejecución.
```
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"
}
]'
```
### Ejecutar un comando creado sin valores predeterminados para `mandatory-parameters`
Al ejecutar el comando, en este caso, debe especificar un valor para el actuador1. La ejecución del comando que se muestra a continuación establecerá correctamente el valor de `actuator1` en. `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"}
}'
```
## Uso de comandos con plantillas de estado
También puede utilizar las operaciones de la API de comandos para la recopilación y el procesamiento de datos de estado. Por ejemplo, puede obtener una instantánea del estado de un solo uso o activar o desactivar las plantillas de estado para iniciar o detener la recopilación de datos del estado del vehículo. Los siguientes ejemplos muestran cómo utilizar la función de comandos con plantillas de estado. Para obtener más información, consulte [Operaciones de plantillas de estado para la recopilación y el procesamiento de datos](state-template-api-operations.md)
**nota**
El campo Nombre especificado como parte de la `mandatory-parameters` entrada debe usar el `$stateTemplate` prefijo.
### Ejemplo 1: Crear comandos para plantillas de estado con valores predeterminados
En este ejemplo, se muestra cómo utilizar la `create-command` CLI para activar las plantillas 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"}
}
]'
```
Del mismo modo, el siguiente comando muestra un ejemplo de cómo puede utilizar la `start-command-execution` CLI para las plantillas 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"}
}'
```
### Ejemplo 2: Crear comandos para plantillas de estado sin valores predeterminados
El siguiente comando crea varias plantillas de estado sin valores predeterminados para ninguno de los parámetros. Obliga a ejecutar el comando con estos parámetros y sus valores.
```
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"}
}
]'
```
El siguiente comando muestra cómo puede utilizar la `start-command-execution` CLI para el ejemplo anterior.
```
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"}
```