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. Recupera y supervisa el estado de ejecución de tu 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 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 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:

    <devices>pueden ser clientes Things o MQTT. <DeviceID>es el nombre de la cosa o el ID 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 es JSON/CBOR<PayloadFormat>, utilice 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 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 o utilizando CreateThing. Encuentra cosas existentes en Thing Hub o usándolas DescribeThing. Consulte Administrar cosas con el registro 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.

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

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

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

  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. 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 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 de comandos.

$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 el AWS IoT comando, como. LockDoor Si desea enviar más de un comando, puede especificarlos en la política de IAM.

  • devicescon 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-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 AWS IoT 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":
    "<account-specific-prefix>-ats.iot.<region>.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:

  • <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 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 <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 Flujo de trabajo de comandos de.

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

  • ThingNamecon el nombre de la AWS IoT cosa a la que apunta la ejecución del comando, por ejemplomyRegisteredThing.

  • commands-request-topicy 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.

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 AWS IoT, puedes usar el ID de cliente como identificador en lugar del nombre de una 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.

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

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.

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 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 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 de la AWS IoT consola y elige el objeto para el que has creado 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.

Utilice 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 su identificador de AWS IoT comando único, comoLockDoor.

  • devicescon 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-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 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:

  • <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. 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 en la AWS IoT consola.

  2. En la pestaña Suscribirse, introduzca el siguiente tema y, a continuación, seleccione Suscribirse, que <thingId> 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 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.

    $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 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 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 de la AWS IoT consola y elige el objeto para el 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.

Utilice la operación de la API HTTP del plano de ListCommandExecutions 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-idcon su 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, comous-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 en client función de si sus dispositivos se han registrado como AWS IoT cosas o se han especificado 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"
  ]
}

En el siguiente ejemplo, se 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.