View a markdown version of this page

Inicio y supervisión de las ejecuciones de comandos - AWS IoT Core
Inicio de la ejecución de un comandoActualización del resultado de la ejecución de un comandoRecuperación de la ejecución de un comandoVisualización de actualizaciones de comandos mediante el cliente de prueba de MQTTEnumera las ejecuciones de comandos en tu Cuenta de AWSEliminación de una ejecución de comandos

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. Recupere y supervise el estado de ejecución desde su cuenta.

Inicie y supervise los comandos mediante la AWS IoT consola o AWS CLI.

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:

  • Has creado un comando en el espacio de AWS IoT nombres con la información de la carga útil. Al iniciar la ejecución, el dispositivo procesa las instrucciones de la carga útil y realiza las acciones especificadas. Consulte Creación de un recurso de comandos para obtener información sobre la 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 esta solicitud reservada de MQTT. Tema:

    <devices>pueden ser clientes de Things o MQTT. <DeviceID>es el nombre de la cosa o el identificador de cliente. <PayloadFormat>Valores admitidos: JSON y CBOR. Para obtener más información, consulte Temas de comandos.

    $aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

    Si no lo son JSON/CBOR <PayloadFormat>, usa este formato de tema de comandos:

    $aws/commands/<devices>/<DeviceID>/executions/+/request

Especifique el dispositivo de destino para recibir y ejecutar el comando. Utilice un nombre de cosa para los dispositivos registrados o un identificador de cliente para los dispositivos no registrados. Tras recibir la carga útil, el dispositivo ejecuta el comando y realiza las acciones especificadas.

AWS IoT thing

Los dispositivos de destino pueden ser cosas registradas en el AWS IoT registro. Las cosas simplifican la búsqueda y la administración de dispositivos.

Registra los dispositivos como cosas desde la página de conexión de dispositivos o usando CreateThing. Encuentra cosas existentes en Thing Hub o usando DescribeThing. Consulta Gestionar cosas con el registro para obtener más información sobre el registro.

ID de cliente

Para los dispositivos no registrados, usa 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 conecte 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 seleccionar 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 al que los dispositivos se conectan. AWS IoT Core AWS IoT usa este ID para identificar los dispositivos y administrar las conexiones y suscripciones.

El tiempo de espera especifica la duración (en segundos) durante la cual los dispositivos proporcionan 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, se agota el tiempo de espera de la ejecución con el estadoTIMED_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 indicar que se ha agotado 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 en TIMED_OUT con un 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 el estado cuando se agotó el 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 a 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 agotó el tiempo de espera cuando ejecutaba el comando. En este caso, el estado de ejecución del comando permanece igualTIMED_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 usarlas 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 supere esta duración, el intermediario de mensajes puede rechazar las ejecuciones de comandos que duran más de 60 minutos y fallar. 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 asegurarte de que estás utilizando correctamente la función de sesiones persistentes de MQTT, establece el indicador Clean Start en cero. Para obtener más información, consulte Sesiones persistentes de MQTT.

Para empezar a ejecutar el comando desde la consola, vaya a la página Command Hub de la AWS IoT consola y lleve a cabo los siguientes pasos.

  1. Para ejecutar el comando que ha creado, elija Ejecutar comando.

  2. Revise la información sobre el comando que ha creado, incluidos los temas reservados de MQTT y los parámetros, si corresponde.

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

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

  4. (Opcional) Configure un valor de tiempo de espera para el comando que determine durante cuánto tiempo 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.

  5. Elija Run command (Ejecutar comando).

Utilice la operación de la API del plano de datos StartCommandExecution 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. En el caso de 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 StartCommandExecutionI 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.

$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

Si el formato de carga útil no es JSON ni CBOR, a continuación se muestra el formato del tema de solicitud del comando.

$aws/commands/<devices>/<DeviceID>/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-idcon un identificador único para tu AWS IoT comando, como. LockDoor Si desea enviar más de un comando, puede especificarlos en la política de IAM.

  • devicescon thing o client dependiendo de si tus dispositivos se han registrado como AWS IoT cosas o si están especificados como clientes de MQTT.

  • device-idcon 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 compatiblesStartCommandExecution, consulte las claves de condición de AWS IoT 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 usa puntos de conexión de doble pila (IPv4 e IPv6), utilice iot:Data-ATS. El punto de conexión iot:Jobs es solo para IPv4. Por ejemplo, si ejecuta este comando:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

Devuelve la URL de punto final específica de la cuenta, tal y como se muestra en el ejemplo de respuesta que aparece a continuación.

{
    "endpointAddress":
    "<account-specific-prefix>-ats.iot.<region>.api.com"
}

Inicie un ejemplo de ejecución de comandos (AWS CLI)

El siguiente ejemplo muestra cómo empezar a ejecutar un comando mediante el start-command-execution AWS CLI comando.

En este ejemplo, sustituya:

  • <command-arn> 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.

  • <target-arn> 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.

  • <endpoint-url> 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, 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 APIStartCommandExecution. 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 <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --execution-timeout-seconds 900

  • (Opcional) En el caso de los comandos dinámicos, especifique los parámetros y sus valores que se van a utilizar para la sustitución. Debe proporcionar un valor para los parámetros que no tengan un valor predeterminado establecido en el momento de la creación del comando. Si un parámetro tiene un valor predeterminado, el valor del parámetro que se proporciona aquí tiene prioridad. Para los parámetros que tienen configuradas las condiciones de valor, el valor del parámetro proporcionado 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 <endpoint-url> \
    --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 High-level flujo de trabajo de comandos.

  • Ya debe haber ejecutado este comando mediante la operación de la API StartCommandExecution.

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

En este ejemplo, sustituya:

  • Regioncon su Región de AWS, por ejemplo. us-east-1

  • AccountID con el número de la Cuenta de AWS , como, por ejemplo 123456789012.

  • ThingNamecon el nombre de la AWS IoT cosa para la que tiene como objetivo la ejecución del comando, por ejemplomyRegisteredThing.

  • commands-request-topicy commands-response-topic con los nombres de los temas de solicitud y respuesta de los AWS IoT comandos. Para obtener más información, consulte High-level flujo de trabajo de comandos.

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}"
    }
  ]
}

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/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

En este ejemplo, <DeviceID> es el identificador único del dispositivo de destino y <execution-id> es el identificador de la ejecución del comando en el dispositivo de destino. <PayloadFormat>Pueden ser JSON o CBOR.

nota

Si no has registrado tu dispositivo con él AWS IoT, puedes usar el ID de cliente como identificador en lugar de un nombre de cosa.

$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

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.

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

Consideraciones sobre el uso de la API UpdateCommandExecution

A continuación, se indican algunas consideraciones importantes a la hora de utilizar la API UpdateCommandExecution.

  • Los 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 sus dispositivos usen el statusReason objeto, reasonCode deben usar el patrón [A-Z0-9_-]+ y no superar los 64 caracteres de longitud. Si lo proporcionasreasonDescription, asegúrate de que no supere los 1024 caracteres. Puede usar cualquier carácter excepto caracteres de control, como 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 Configuración AWS IoT registrar.

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"
        }
    }
}
nota

Cuando se produce un error en la solicitud de UpdateCommandExecution MQTT, el servicio publica una respuesta de error /rejected sobre el tema. Para obtener una lista completa de los códigos de error y una guía de solución de problemas, consulteAWS IoT Solución de problemas de comandos.

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.

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 de Command Hub 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.

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

    3. 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 una AWS IoT cosa como dispositivo de destino al ejecutar el comando, puedes ver los detalles de la ejecución en la página de Thing Hub.

    1. Ve a la página de Thing Hub de la AWS IoT consola y elige la cosa para la que creaste la ejecución del comando.

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

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

Usa la operación de la API HTTP del plano de GetCommandExecution 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-idcon tu identificador de AWS IoT comando único, comoLockDoor.

  • devicescon thing o client dependiendo de si sus dispositivos se han registrado como AWS IoT cosas o si están especificados como clientes MQTT.

  • device-idcon 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 ese 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:

  • <execution-id> con el identificador de la ejecución del comando del que desea recuperar información.

  • <target-arn> 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 <execution-id> \ 
    --target-arn <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.

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.

{
    "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. Cuando 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 se suscribió al tema de solicitud reservada de comandos de MQTT, verá el mensaje de carga útil 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 AWS CloudTrail y Amazon. CloudWatch 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 prueba MQTT en la AWS IoT consola.

  2. En la pestaña Suscribirse, introduzca el siguiente tema y, a continuación, seleccione Suscribirse, donde <thingId> aparece el nombre del dispositivo con AWS IoT el que se ha registrado.

    nota

    Puedes encontrar el nombre de la cosa para tu dispositivo en la página Thing Hub de la AWS IoT consola. Si no has registrado tu dispositivo como una cosa, puedes registrarlo cuando te conectes AWS IoT desde la página Conectar el dispositivo.

    $aws/commands/things/<thingId>/executions/+/request

  3. (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

  4. 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/<thingId>/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.

  5. 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/<devices>/<device-id>/executions/<executionId>/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.

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 de Command Hub 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.

    2. 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 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 central de Thing.

    1. Ve a la página de Thing Hub de la AWS IoT consola y elige la cosa para la que has creado las ejecuciones.

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

Usa la operación de la API HTTP del plano de ListCommandExecutions AWS IoT Core control para ver una lista de todas las ejecuciones de comandos en tu 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-idcon tu identificador de AWS IoT comando único, comoLockDoor.

{
  "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:

  • <target-arn> 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.

  • <target-arn> 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.

  • <after> 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 <target-arn> \ 
--started-time-filter '{after=<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.

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.

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:

  • Regioncon tu Región de AWS, por ejemplous-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.

  • devicescon thing o client dependiendo de si sus dispositivos se han registrado como AWS IoT cosas o si están especificados como clientes MQTT.

  • device-idcon 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"
  ]
}

El siguiente ejemplo muestra cómo eliminar un comando mediante el delete-command AWS CLI comando. Según la aplicación, sustituya <execution-id> por el identificador de la ejecución del comando que va a eliminar y el <target-arn> por el ARN del dispositivo de destino. 

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <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.