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.
# Inicio y supervisión de las ejecuciones de comandos
Después de crear un comando, inicie una ejecución en el dispositivo de destino. El dispositivo actualiza los resultados y publica el estado en los temas reservados de MQTT. Recupera y supervisa el estado de ejecución de tu cuenta.
Inicie y supervise los comandos mediante la AWS IoT consola o AWS CLI.
**Topics**
+ [Inicio de la ejecución de un comando](#iot-remote-command-execution-start)
+ [Actualización del resultado de la ejecución de un comando](#iot-remote-command-execution-update)
+ [Recuperación de la ejecución de un comando](#iot-remote-command-execution-get)
+ [Visualización de actualizaciones de comandos mediante el cliente de prueba de MQTT](#iot-remote-command-execution-update-mqtt)
+ [Enumera las ejecuciones de comandos en tu Cuenta de AWS](#iot-remote-command-execution-list)
+ [Eliminación de una ejecución de comandos](#iot-remote-command-execution-delete)
## Inicio de la ejecución de un comando
**importante**
Usted es el único responsable de implementar los comandos de forma segura y que cumpla con las normativas aplicables.
Antes de iniciar una ejecución, asegúrese de que:
+ Creó un comando en el espacio de AWS IoT nombres con la información de carga útil. Al iniciar la ejecución, el dispositivo procesa las instrucciones de carga útil y realiza acciones específicas. Consulte la [Creación de un recurso de comandos](iot-remote-command-create-manage.md#iot-remote-command-create) sección Creación de comandos.
+ Su dispositivo está suscrito a los temas reservados para comandos de MQTT. Al iniciar la ejecución, la información sobre la carga útil se publica en este tema reservado de solicitud de MQTT:
**pueden ser clientes Things o MQTT. **es el nombre de la cosa o el ID de cliente. **Valores admitidos: JSON y CBOR. Para obtener más información, consulte [Temas de comandos](reserved-topics.md#reserved-topics-commands).
```
$aws/commands///executions/+/request/
```
Si no es JSON/CBOR**, utilice este formato de tema de comandos:
```
$aws/commands///executions/+/request
```
### Consideraciones sobre los dispositivos de destino
Especifique el dispositivo de destino para recibir y ejecutar el comando. Utilice un nombre de cosa para los dispositivos registrados o un ID de cliente para los dispositivos no registrados. Tras recibir la carga útil, el dispositivo ejecuta el comando y realiza las acciones especificadas.
#### AWS IoT cosa
Los dispositivos de destino pueden ser cosas registradas en el AWS IoT registro. Las cosas simplifican la búsqueda y la administración de los dispositivos.
Registre los dispositivos como Cosas desde la [página Connect device](https://console.aws.amazon.com/iot/home#/connect-overview) o utilizando [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html). Encuentra cosas existentes en [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) o usándolas [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html). Consulte [Administrar cosas con el registro](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry) para obtener información sobre el registro.
#### ID de cliente
En el caso de los dispositivos no registrados, utilice el ID de cliente.
El ID de cliente es un identificador único que se asigna a los dispositivos. Definido en el protocolo MQTT, contiene caracteres alfanuméricos, guiones bajos o guiones. Cada dispositivo al que se conecta AWS IoT necesita un ID de cliente único.
**nota**
En el caso de las cosas registradas, el ID de cliente puede coincidir con el nombre de la cosa.
Al dirigirse a un ID de cliente específico, los dispositivos deben conectarse AWS IoT utilizando ese ID de cliente para recibir la carga útil.
El ID de cliente es el ID de cliente de MQTT que utilizan los dispositivos al conectarse. AWS IoT Core AWS IoT usa este ID para identificar los dispositivos y administrar las conexiones y suscripciones.
### Consideraciones sobre el tiempo de espera de ejecución de comandos
El tiempo de espera especifica el tiempo (en segundos) que tardan los dispositivos en proporcionar los resultados de la ejecución.
Tras crear una ejecución, se inicia un temporizador. Si el dispositivo se desconecta o no informa de los resultados dentro del tiempo de espera, la ejecución se agota con el estado`TIMED_OUT`.
Predeterminado: 10 segundos. Máximo: 12 horas.
#### Valor de tiempo de espera y estado de ejecución de `TIMED_OUT`
Tanto la nube como el dispositivo pueden informar sobre el tiempo de espera.
Tras enviar el comando, se inicia un temporizador. Si el dispositivo no responde dentro del tiempo de espera, la nube establece el estado de ejecución `TIMED_OUT` con el código `$NO_RESPONSE_FROM_DEVICE` de motivo.
Esto ocurre cuando:
+ El dispositivo se desconectó durante la ejecución.
+ El dispositivo no pudo completar la ejecución dentro del tiempo de espera.
+ El dispositivo no pudo informar sobre su estado dentro del tiempo de espera.
En este caso, cuando se informa del estado de ejecución de `TIMED_OUT` desde la nube, la ejecución del comando es no final. El dispositivo puede publicar una respuesta que sustituya el estado por cualquiera de los estados del terminal:`SUCCEEDED`,, `FAILED` o. `REJECTED` La ejecución del comando pasa entonces a ser terminal y no acepta más actualizaciones.
El dispositivo también puede actualizar un `TIMED_OUT` estado iniciado por la nube informando de 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 el `statusReason` objeto se actualiza en función de la información proporcionada por el dispositivo. La ejecución del comando pasa entonces a ser terminal y no se aceptan más actualizaciones.
#### Uso de las sesiones persistentes de MQTT
Puede configurar las sesiones persistentes de MQTT para utilizarlas con la función de AWS IoT Device Management comandos. Esta característica resulta especialmente útil en casos en los que el dispositivo se queda sin conexión y quiere asegurarse de que el dispositivo siga recibiendo el comando cuando vuelve a conectarse antes de que se agote el tiempo de espera y siga las instrucciones especificadas.
De forma predeterminada, la caducidad de la sesión persistente de MQTT está establecida en 60 minutos. Si el tiempo de espera de ejecución de comandos está configurado en un valor que supera esta duración, el agente de mensajes puede rechazar las ejecuciones de comandos que se ejecuten durante más de 60 minutos y producir un error. Para ejecutar comandos de más de 60 minutos de duración, puede solicitar un aumento del tiempo de caducidad de la sesión persistente.
**nota**
Para asegurarse de que está utilizando correctamente la función de sesiones persistentes de MQTT, establezca el indicador de inicio limpio en cero. Para obtener más información, consulte [Sesiones persistentes de MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-persistent-sessions).
### Inicio de la ejecución de un comando (consola)
Para empezar a ejecutar el comando desde la consola, vaya a la página [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) de la AWS IoT consola y lleve a cabo los siguientes pasos.
1. Para ejecutar el comando que ha creado, elija **Ejecutar comando**.
1. Revise la información sobre el comando que creó, incluidos los temas reservados de MQTT y los parámetros, si corresponde.
En el caso de los comandos dinámicos, introduzca los valores de los parámetros o déjelos con los valores predeterminados. Para los parámetros que no tienen un valor predeterminado, debe proporcionar un valor para enviarlo como parte de esta ejecución.
1. Especifique el dispositivo de destino para recibir y ejecutar el comando. El dispositivo se puede especificar como una AWS IoT cosa si se ha registrado AWS IoT o mediante el ID de cliente si el dispositivo aún no se ha registrado. Para obtener más información, consulte [Consideraciones sobre los dispositivos de destino](#iot-command-execution-target)
1. (Opcional) Configure un valor de tiempo de espera para el comando que determine el tiempo durante el que desea que se ejecute el comando antes de que se agote el tiempo de espera. Si el comando debe ejecutarse durante más de 60 minutos, puede que tenga que aumentar el tiempo de caducidad de las sesiones persistentes de MQTT. Para obtener más información, consulte [Consideraciones sobre el tiempo de espera de ejecución de comandos](#iot-command-execution-timeout).
1. Elija **Run command (Ejecutar comando)**.
### Inicio de la ejecución de un comando (AWS CLI)
Utilice la operación de la API del plano de datos [https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html) HTTP para iniciar la ejecución de un comando. La solicitud y la respuesta de la API se correlacionan mediante el ID de ejecución del comando. Una vez que el dispositivo termine de ejecutar el comando, puede informar del estado y el resultado de la ejecución a la nube publicando un mensaje en el tema de respuesta del comando. Para un código de respuesta personalizado, los códigos de aplicación que poseas pueden procesar el mensaje de respuesta y publicar el resultado en él. AWS IoT
Si los dispositivos se han suscrito al tema de solicitud de comandos, la API `StartCommandExecution`I publicará el mensaje de carga útil en ese tema. La carga útil puede usar cualquier formato de su elección. Para obtener más información, consulte [Carga útil de comandos](iot-remote-command-create-manage.md#iot-commands-payload).
```
$aws/commands///executions/+/request/
```
Si el formato de carga útil no es JSON ni CBOR, a continuación se muestra el formato del tema de solicitud de comandos.
```
$aws/commands///executions/+/request
```
#### Ejemplo de política de IAM
Antes de usar esta operación de la API, asegúrese de que la política de IAM le autorice a realizar esta acción en el dispositivo. A continuación, se muestra un ejemplo de una política de IAM que permite a un usuario realizar la acción `StartCommandExecution`.
En este ejemplo, sustituya:
+ `region` con la Región de AWS, como, por ejemplo, `us-east-1`.
+ `account-id` con el número de la Cuenta de AWS , como, por ejemplo `123456789012`.
+ `command-id`con un identificador único para el AWS IoT comando, como. `LockDoor` Si desea enviar más de un comando, puede especificarlos en la política de IAM.
+ `devices`con `thing` o en `client` función de si sus dispositivos se han registrado como AWS IoT cosas o se han especificado como clientes MQTT.
+ `device-id`con tu AWS IoT `thing-name` o. `client-id`
```
{
"Effect": "Allow",
"Action": [
"iot:StartCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
Para ver una lista de las claves de condición compatibles`StartCommandExecution`, consulte [las claves de condición AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-policy-keys) en la *Guía del usuario de IAM*.
#### 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 de conexión específico de la cuenta para el punto de conexión. Si utiliza puntos finales de doble pila (IPv4y IPv6), utilice el. `iot:Data-ATS` El `iot:Jobs` punto final es solo para. IPv4 Por ejemplo, si ejecuta este comando:
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
Devuelve la URL del punto final específica de la cuenta, como se muestra en el ejemplo de respuesta que aparece a continuación.
```
{
"endpointAddress":
"-ats.iot..api.com"
}
```
#### Ejemplo de inicio de la ejecución de un comando (AWS CLI)
En el siguiente ejemplo, se muestra cómo empezar a ejecutar un comando mediante el `start-command-execution` AWS CLI comando.
En este ejemplo, sustituya:
+ *``* con el ARN del comando que desee ejecutar. Puede obtener esta información de la respuesta del comando `create-command` de la CLI. Por ejemplo, si está ejecutando el comando para cambiar el modo de volante, utilice `arn:aws:iot:region:account-id:command/SetComfortSteeringMode`.
+ *``* con el ARN del objeto del dispositivo de destino, que puede ser un objeto de IoT o un cliente de MQTT, para el que desee ejecutar el comando. Por ejemplo, si está ejecutando el comando para el dispositivo de destino `myRegisteredThing`, utilice `arn:aws:iot:region:account-id:thing/myRegisteredThing`.
+ *``* con el punto de conexión específico de la cuenta que ha obtenido en [Obtención del punto de conexión del plano de datos específico de la cuenta](#iot-remote-command-execution-start-endpoint), con el prefijo `https://`. Por ejemplo, `https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com`.
+ (Opcional) También puede especificar un parámetro adicional, `executionTimeoutSeconds`, al realizar la operación de la API`StartCommandExecution`. Este campo opcional especifica el tiempo en segundos dentro del cual el dispositivo debe completar la ejecución del comando. De forma predeterminada, el valor es 10 segundos. Cuando el estado de ejecución del comando sea `CREATED`, se iniciará un temporizador. Si el resultado de la ejecución del comando no se recibe antes de que caduque el temporizador, el estado cambiará automáticamente a `TIMED_OUT`.
+
```
aws iot-jobs-data start-command-execution \
--command-arn \
--target-arn \
--endpoint \
--execution-timeout-seconds 900
```
+ (Opcional) En el caso de los comandos dinámicos, especifique los parámetros y sus valores que se utilizarán para la sustitución. Debe proporcionar un valor para los parámetros que no tengan un DefaultValue establecido al crear el comando. Si un parámetro tiene un DefaultValue, el valor del parámetro que se proporciona aquí tiene prioridad. En el caso de los parámetros que tienen definidas las condiciones de valor, el valor del parámetro que se proporciona aquí debe cumplir la condición.
Basado en el ejemplo de `Light_Power_Status` un comando dinámico:
+
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status \
--target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \
--endpoint \
--execution-timeout-seconds 900 \
--parameters "powerStatus={S=ON}"
```
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.
**nota**
Si el comando ha quedado obsoleto, se producirá un error en la solicitud de la API `StartCommandExecution` con una excepción de validación. Para corregir este error, primero restaure el comando mediante la API `UpdateCommand` y, a continuación, ejecute la solicitud `StartCommandExecution`.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
## Actualización del resultado de la ejecución de un comando
Utilice la operación de la API del plano de datos de MQTT `UpdateCommandExecution` para actualizar el estado o el resultado de la ejecución de un comando.
**nota**
Antes de usar esta API:
El dispositivo debe haber establecido una conexión de MQTT y estar suscrito a los temas de solicitud y respuesta de comandos. Para obtener más información, consulte [Flujo de trabajo de comandos de](iot-remote-command-workflow.md).
Ya debe haber ejecutado este comando mediante la operación de la API `StartCommandExecution`.
### Ejemplo de política de IAM
Antes de usar esta operación de la API, asegúrese de que la política de IAM autorice al dispositivo a realizar estas acciones. A continuación, se muestra un ejemplo de política que autoriza al dispositivo a realizar la acción. Para ver ejemplos adicionales de políticas de IAM que permiten al usuario realizar la acción de `UpdateCommandExecution` MQTT, consulte. [Ejemplos de políticas de conexión y publicación](connect-and-pub.md)
En este ejemplo, sustituya:
+ `Region`con las tuyas Región de AWS, por ejemplo. `us-east-1`
+ `AccountID` con el número de la Cuenta de AWS , como, por ejemplo *`123456789012`*.
+ `ThingName`con el nombre de la AWS IoT cosa a la que apunta la ejecución del comando, por ejemplo*`myRegisteredThing`*.
+ `commands-request-topic`y `commands-response-topic` con los nombres de los temas de solicitud y respuesta de sus AWS IoT comandos. Para obtener más información, consulte [Flujo de trabajo de comandos de](iot-remote-command-workflow.md).
#### Ejemplo de política de IAM para el ID de cliente de MQTT
En el siguiente ejemplo de código se muestra una política de dispositivo de ejemplo cuando se utiliza el ID de cliente de MQTT.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
}
]
}
```
#### Ejemplo de política de IAM para un objeto de IoT
En el siguiente ejemplo de código se muestra una política de dispositivo de ejemplo cuando se utiliza un objeto de AWS IoT .
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response"
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
}
]
}
```
### Cómo utilizar la API `UpdateCommandExecution`
Una vez recibida la ejecución del comando en el tema de solicitud, el dispositivo procesará el comando. A continuación, utiliza la API `UpdateCommandExecution` para actualizar el estado y el resultado de la ejecución del comando en el siguiente tema de respuesta.
```
$aws/commands///executions//response/
```
En este ejemplo, *``* es el identificador único del dispositivo de destino y *``* es el identificador de la ejecución del comando en el dispositivo de destino. **Pueden ser JSON o CBOR.
**nota**
Si no has registrado tu dispositivo AWS IoT, puedes usar el ID de cliente como identificador en lugar del nombre de una cosa.
```
$aws/commands/clients//executions//response/
```
#### Actualizaciones en el estado de ejecución indicadas por el dispositivo
Los dispositivos pueden usar la API para informar sobre cualquiera de las siguientes actualizaciones de estado relacionadas con la ejecución de un comando. Para obtener más información sobre estos estados, consulte [Estado de la ejecución del comando](iot-remote-command-concepts.md#iot-command-execution-status).
+ `IN_PROGRESS`: cuando el dispositivo comience a ejecutar el comando, podrá actualizar el estado a `IN_PROGRESS`.
+ `SUCCEEDED`: cuando el dispositivo procese correctamente el comando y termine de ejecutarlo, podrá publicar un mensaje en el tema de respuesta como `SUCCEEDED`.
+ `FAILED`: si el dispositivo no ha podido ejecutar el comando, puede publicar un mensaje en el tema de respuesta como `FAILED`.
+ `REJECTED`: si el dispositivo no ha podido aceptar el comando, puede publicar un mensaje en el tema de respuesta como `REJECTED`.
+ `TIMED_OUT`: el estado de ejecución del comando puede cambiar a `TIMED_OUT` debido a cualquiera de los siguientes motivos.
+ No se ha recibido el resultado de la ejecución del comando. Esto puede ocurrir porque la ejecución no se ha completado en el plazo especificado o si el dispositivo no ha podido publicar la información de estado en el tema de respuesta.
+ El dispositivo indica que se ha agotado el tiempo de espera al intentar ejecutar el comando.
Para obtener más información sobre el estado `TIMED_OUT`, consulte [Valor de tiempo de espera y estado de ejecución de `TIMED_OUT`](#iot-command-execution-timeout-status).
#### Consideraciones sobre el uso de la API `UpdateCommandExecution`
A continuación, se indican algunas consideraciones importantes a la hora de utilizar la API `UpdateCommandExecution`.
+ Sus dispositivos pueden usar un `statusReason` objeto opcional para proporcionar información adicional sobre la ejecución. Si sus dispositivos proporcionan este objeto, el `reasonCode` campo del objeto es obligatorio, pero el `reasonDescription` campo es opcional.
+ Cuando los dispositivos utilicen el `statusReason` objeto, `reasonCode` deberán utilizar el patrón `[A-Z0-9_-]+` y no superar los 64 caracteres de longitud. Si lo proporciona`reasonDescription`, asegúrese de que no supere los 1024 caracteres de longitud. Puede utilizar cualquier carácter excepto los caracteres de control, como las líneas nuevas.
+ Los dispositivos pueden usar un objeto de `result` opcional para proporcionar información sobre el resultado de la ejecución del comando, como, por ejemplo, el valor devuelto por una llamada a una función remota. Si proporciona el `result`, debe requerir al menos una entrada.
+ En el campo `result`, debe especificar las entradas como pares de clave-valor. En cada entrada, debe especificar la información del tipo de datos en forma de cadena, booleano o binario. Un tipo de datos de cadena debe usar la clave `s`, un tipo de datos booleano usa la clave `b` y un tipo de datos binario debe usar la clave `bin`. Asegúrese de que estas teclas estén en minúsculas.
+ Si encuentras un error al ejecutar la `UpdateCommandExecution` API, puedes ver el error en el grupo de `AWSIoTLogsV2` registros de Amazon CloudWatch. Para obtener más información sobre la habilitación de registros y la visualización de los registros, consulte [Configure el AWS IoT registro](configure-logging.md).
#### Ejemplo de la API `UpdateCommandExecution`
En el código siguiente se muestra un ejemplo de cómo un dispositivo puede utilizar la API `UpdateCommandExecution` para informar del estado de la ejecución, el campo `statusReason` para proporcionar información adicional sobre el estado y el campo de resultados para proporcionar información sobre el resultado de la ejecución, como, por ejemplo, el porcentaje de batería del automóvil en este caso.
```
{
"status": "IN_PROGRESS",
"statusReason": {
"reasonCode": "200",
"reasonDescription": "Execution_in_progress"
},
"result": {
"car_battery": {
"s": "car battery at 50 percent"
}
}
}
```
## Recuperación de la ejecución de un comando
Tras ejecutar un comando, puede recuperar información sobre la ejecución del comando desde la AWS IoT consola y mediante el AWS CLI. Puede obtener la siguiente información.
**nota**
Para recuperar el último estado de ejecución del comando, el dispositivo debe publicar la información de estado en el tema de respuesta mediante la API de MQTT `UpdateCommandExecution`, tal y como se describe a continuación. Hasta que el dispositivo publique este tema, la API `GetCommandExecution` indicará el estado como `CREATED` o `TIMED_OUT`.
Cada ejecución de comando que cree tendrá:
+ Un **ID de ejecución**, que es un identificador único de la ejecución del comando.
+ El **Estado** de la ejecución del comando. Al ejecutar el comando en el dispositivo de destino, la ejecución del comando entra en un estado `CREATED`. A continuación, puede pasar a otros estados de ejecución de comandos, tal y como se describe a continuación.
+ El **Resultado** de la ejecución del comando.
+ El **ID de comando** único y el dispositivo de destino para el que se han creado las ejecuciones.
+ La **Fecha de inicio**, que muestra el momento en que se creó la ejecución del comando.
### Recuperación de la ejecución de un comando (consola)
Puede recuperar una ejecución del comando desde la consola mediante cualquiera de los siguientes métodos.
+
**Desde la página Centro de comandos**
Vaya a la página [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) de la AWS IoT consola y lleve a cabo estos pasos.
1. Elija el comando para el que ha creado una ejecución en el dispositivo de destino.
1. En la página de detalles del comando, en la pestaña **Historial de comandos**, aparecerán las ejecuciones que ha creado. Elija la ejecución de la que desee recuperar información.
1. Si los dispositivos han utilizado la API `UpdateCommandExecution` para proporcionar la información de los resultados, puede encontrar esta información en la pestaña **Resultados** de esta página.
+
**Desde la página Centro de objetos**
Si has elegido AWS IoT algo como dispositivo de destino al ejecutar el comando, puedes ver los detalles de la ejecución en la página Thing Hub.
1. Ve a la página [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) de la AWS IoT consola y elige el objeto para el que has creado la ejecución del comando.
1. En la página de detalles del objeto, en la opción **Historial de comandos**, aparecerán las ejecuciones que ha creado. Elija la ejecución de la que desee recuperar información.
1. Si los dispositivos han utilizado la API `UpdateCommandExecution` para proporcionar la información de los resultados, puede encontrar esta información en la pestaña **Resultados** de esta página.
### Recuperación de la ejecución de un comando (CLI)
Utilice la operación de la API HTTP 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 Core 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`.
#### Ejemplo de política de IAM
Antes de usar esta operación de la API, asegúrese de que la política de IAM le autorice a realizar esta acción en el dispositivo. A continuación, se muestra un ejemplo de una política de IAM que permite a un usuario realizar la acción `GetCommandExecution`.
En este ejemplo, sustituya:
+ `region` con la Región de AWS, como, por ejemplo, `us-east-1`.
+ `account-id` con el número de la Cuenta de AWS , como, por ejemplo `123456789012`.
+ `command-id`con su identificador de AWS IoT comando único, como`LockDoor`.
+ `devices`con `thing` o en `client` función de si sus dispositivos se han registrado como AWS IoT cosas o se han especificado como clientes MQTT.
+ `device-id`con tu AWS IoT `thing-name` o. `client-id`
```
{
"Effect": "Allow",
"Action": [
"iot:GetCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
#### Ejemplo de recuperación de la ejecución de un comando
El siguiente ejemplo muestra cómo recuperar información sobre un comando que se ejecutó con el `start-command-execution` AWS CLI comando. En el siguiente ejemplo se muestra cómo puede recuperar información sobre un comando que se ha ejecutado para desactivar el modo volante.
En este ejemplo, sustituya:
+ *``* con el identificador de la ejecución del comando del que desea recuperar información.
+ *``* con el nombre de recurso de Amazon (ARN) del dispositivo al que se dirige la ejecución. Puede obtener esta información de la respuesta del comando `start-command-execution` de la CLI.
+ Si lo desea, si los dispositivos han utilizado la API `UpdateCommandExection` para proporcionar el resultado de la ejecución, puede especificar si desea incluir el resultado de la ejecución del comando en la respuesta de la API `GetCommandExecution` mediante la API `GetCommandExecution`.
```
aws iot get-command-execution
--execution-id \
--target-arn \
--include-result
```
La ejecución de este comando genera una respuesta que incluye información sobre el ARN de la ejecución del comando, el estado de la ejecución y el momento en que se inició y finalizó. También proporciona un objeto de `statusReason` que incluye información adicional sobre el estado. Para obtener más información sobre los distintos estados y el motivo del estado, consulte [Estado de la ejecución del comando](iot-remote-command-concepts.md#iot-command-execution-status).
En el siguiente código se muestra un ejemplo de respuesta de la solicitud de la API.
**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 de un estado `TIMED_OUT`, 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 [Consideraciones sobre el tiempo de espera de ejecución de comandos](#iot-command-execution-timeout).
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
"targetArn": "arn:aws:iot:us-east-1:123456789012:thing/myRegisteredThing",
"status": "SUCCEEDED",
"statusReason": {
"reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED",
"reasonDescription": "SUCCESS"
},
"result": {
"sn": { "s": "ABC-001" },
"digital": { "b": true }
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00"
}
```
## Visualización de actualizaciones de comandos mediante el cliente de prueba de MQTT
Puede usar el cliente de prueba de MQTT para ver el intercambio de mensajes a través de MQTT cuando se utiliza la característica de comandos. Una vez que el dispositivo establezca una conexión MQTT con AWS IoT, puede crear un comando, especificar la carga útil y, a continuación, ejecutarlo en el dispositivo. Al ejecutar el comando, si el dispositivo está suscrito al tema de solicitud reservada de comandos de MQTT, verá el mensaje de carga publicado en este tema.
A continuación, el dispositivo recibe las instrucciones de carga útil y realiza las operaciones especificadas en el dispositivo. AWS IoT A continuación, utiliza la `UpdateCommandExecution` API para publicar el resultado de la ejecución del comando y la información de estado en los temas de respuesta reservados de MQTT para los comandos. AWS IoT Device Management escucha las actualizaciones sobre los temas de respuesta, almacena la información actualizada y publica los registros en Amazon CloudWatch. AWS CloudTrail A continuación, puede recuperar la información más reciente sobre la ejecución de comandos desde la consola o mediante la `GetCommandExecution` API.
En los siguientes pasos se muestra cómo usar el cliente de prueba de MQTT para observar los mensajes.
1. Abra el [cliente de pruebas de MQTT](https://console.aws.amazon.com/iot/home#/test) en la AWS IoT consola.
1. En la pestaña **Suscribirse**, introduzca el siguiente tema y, a continuación, seleccione **Suscribirse**, que ** es el nombre del dispositivo con AWS IoT el que se ha registrado.
**nota**
Puedes encontrar el nombre del dispositivo en la página [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) de la AWS IoT consola. Si no has registrado el dispositivo como una cosa, puedes registrarlo al conectarte a AWS IoT desde la [página Conectar dispositivo](https://console.aws.amazon.com/iot/home#/connect-overview).
```
$aws/commands/things//executions/+/request
```
1. (Opcional) En la pestaña **Suscribirse**, también puede introducir los siguientes temas y seleccionar **Suscribirse**.
```
$aws/commands/things/+/executions/+/response/accepted/json
$aws/commands/things/+/executions/+/response/rejected/json
```
1. Después de iniciar la ejecución del comando, la carga útil del mensaje se enviará al dispositivo mediante el tema de solicitud al que se ha suscrito el dispositivo, `$aws/commands/things//executions/+/request`. En el cliente de prueba de MQTT, debería aparecer la carga útil del comando que incluye las instrucciones para que el dispositivo procese el comando.
1. Una vez que el dispositivo comience a ejecutar el comando, podrá publicar actualizaciones de estado en el siguiente tema de respuesta reservado de MQTT para comandos.
```
$aws/commands///executions//response/json
```
Por ejemplo, considere un comando que ejecutó para encender el aire acondicionado del automóvil y reducir la temperatura al valor deseado. En el siguiente JSON se muestra un mensaje de ejemplo que el vehículo publicó en el tema de respuesta, en el que se indica que no pudo ejecutar el comando.
```
{
"deviceId": "My_Car",
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"status": "FAILED",
"statusReason": {
"reasonCode": "CAR_LOW_ON_BATTERY",
"reasonDescription": "Car battery is lower than 5 percent"
}
}
```
En este caso, puede cargar la batería del automóvil y volver a ejecutar el comando.
## Enumera las ejecuciones de comandos en tu Cuenta de AWS
Tras ejecutar un comando, puede recuperar información sobre la ejecución del comando desde la AWS IoT consola y mediante el AWS CLI. Puede obtener la siguiente información.
+ Un **ID de ejecución**, que es un identificador único de la ejecución del comando.
+ El **Estado** de la ejecución del comando. Al ejecutar el comando en el dispositivo de destino, la ejecución del comando entra en un estado `CREATED`. A continuación, puede pasar a otros estados de ejecución de comandos, tal y como se describe a continuación.
+ El **ID de comando** único y el dispositivo de destino para el que se han creado las ejecuciones.
+ La **Fecha de inicio**, que muestra el momento en que se creó la ejecución del comando.
### Enumeración de las ejecuciones de comandos de la cuenta (consola)
Puede ver todas las ejecuciones de comandos desde la consola mediante cualquiera de los siguientes métodos.
+
**Desde la página Centro de comandos**
Vaya a la página [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) de la AWS IoT consola y lleve a cabo estos pasos.
1. Elija el comando para el que ha creado una ejecución en el dispositivo de destino.
1. En la página de detalles del comando, vaya a la pestaña **Historial de comandos** y aparecerá una lista de las ejecuciones que ha creado.
+
**Desde la página Centro de objetos**
Si has elegido un AWS IoT objeto como dispositivo de destino al ejecutar el comando y has creado varias ejecuciones de comandos para un solo dispositivo, puedes ver las ejecuciones del dispositivo en la página Thing Hub.
1. Ve a la página [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) de la AWS IoT consola y elige el objeto para el que has creado las ejecuciones.
1. En la página de detalles del objeto, en la opción **Historial de comandos**, aparecerá una lista de las ejecuciones que ha creado para el dispositivo.
### Enumeración de las ejecuciones de comandos de la cuenta (CLI)
Utilice 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 su cuenta.
#### Ejemplo de política de IAM
Antes de usar esta operación de la API, asegúrese de que la política de IAM le autorice a realizar esta acción en el dispositivo. A continuación, se muestra un ejemplo de una política de IAM que permite a un usuario realizar la acción `ListCommandExecutions`.
En este ejemplo, sustituya:
+ `region` con la Región de AWS, como, por ejemplo, `us-east-1`.
+ `account-id` con el número de la Cuenta de AWS , como, por ejemplo `123456789012`.
+ `command-id`con su identificador de AWS IoT comando único, como`LockDoor`.
```
{
"Effect": "Allow",
"Action": "iot:ListCommandExecutions",
"Resource": *
}
```
#### 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"
}
]
}
```
Para obtener más información sobre los distintos estados y el motivo del estado, consulte [Estado de la ejecución del comando](iot-remote-command-concepts.md#iot-command-execution-status).
## 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`.
Esta operación solo se puede realizar mediante la AWS IoT Core API o la AWS CLI. No está disponible en la consola.
### Ejemplo de política de IAM
Antes de usar esta operación de la API, asegúrese de que la política de IAM autorice al dispositivo a realizar estas acciones. A continuación, se muestra un ejemplo de política que autoriza al dispositivo a realizar la acción.
En este ejemplo, sustituya:
+ `Region`con tu Región de AWS, como`us-east-1`.
+ `AccountID` con el número de la Cuenta de AWS , como, por ejemplo *`123456789012`*.
+ `CommandID` con el identificador del comando para el que desea eliminar la ejecución.
+ `devices`con `thing` o en `client` función de si sus dispositivos se han registrado como AWS IoT cosas o se han especificado como clientes MQTT.
+ `device-id`con tu AWS IoT `thing-name` o. `client-id`
```
{
"Effect": "Allow",
"Action": [
"iot:DeleteCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
### Ejemplo de eliminación de una ejecución de comandos
En el siguiente ejemplo, se muestra cómo eliminar un comando mediante el `delete-command` AWS CLI comando. Según la aplicación, sustituya *``* por el identificador de la ejecución del comando que va a eliminar y el *``* por el ARN del dispositivo de destino.
```
aws iot delete-command-execution \
--execution-id \
--target-arn
```
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.