Inicio y supervisión de las ejecuciones de comandos

Cuando desee ejecutar el comando, debe especificar el dispositivo de destino que recibirá el comando y ejecutar las instrucciones especificadas. El dispositivo de destino puede ser un objeto de AWS IoT o el ID de cliente si el dispositivo no se ha registrado en el registro de AWS IoT. Tras recibir la carga útil del comando, el dispositivo puede empezar a ejecutar el comando y realizar las acciones especificadas.

AWS IoTObjeto

El dispositivo de destino del comando puede ser un objeto de AWS IoT que haya registrado en el registro de objetos de AWS IoT. Los objetos de AWS IoT facilitan la búsqueda y la administración de los dispositivos.

Puede registrar el dispositivo como un objeto al conectarlo a AWS IoT en la página Conexión del dispositivo o mediante la API CreateThing. Puede encontrar un objeto existente para el que desee ejecutar el comando en la página Centro de objetos de la consola de AWS IoT o mediante la API DescribeThing. Para obtener más información sobre cómo registrar el dispositivo como un objeto de AWS IoT, consulte Administración de objetos con el registro.

ID de cliente

Si el dispositivo no se ha registrado como objeto con AWS IoT, puede usar el ID de cliente en su lugar.

El ID de cliente es un identificador único que se asigna a su dispositivo o cliente. El ID de cliente se define en el protocolo MQTT y puede incluir caracteres alfanuméricos, guiones bajos o guiones. Debe ser exclusivo de cada dispositivo que se conecte a AWS IoT.

El ID de cliente suele ser el ID de cliente de MQTT que los dispositivos pueden usar al conectarse a AWS IoT Core. Este ID lo usa AWS IoT para identificar cada dispositivo específico y administrar las conexiones y suscripciones.

El tiempo de espera indica el tiempo en segundos en el que el dispositivo debe proporcionar el resultado de la ejecución del comando.

Tras crear la ejecución de un comando, se inicia un temporizador. Si el dispositivo se desconectó o no notificó el resultado de la ejecución dentro del tiempo de espera, se agotará el tiempo de ejecución del comando y se indicará el estado de ejecución como TIMED_OUT.

Este campo es opcional y tendrá un valor predeterminado de 10 segundos si no especifica ningún valor. También puede configurar el tiempo de espera en un valor máximo de 12 horas.

Valor de tiempo de espera y estado de ejecución de TIMED_OUT

La nube y el dispositivo pueden informar sobre un tiempo de espera.

Una vez que se envía el comando al dispositivo, se iniciará un temporizador. Si no se ha recibido ninguna respuesta del dispositivo dentro del tiempo de espera especificado, tal y como se describió anteriormente. En este caso, la nube establece el estado de ejecución del comando como TIMED_OUT con el código de motivo como $NO_RESPONSE_FROM_DEVICE.

Esto sucede en cualquiera de los siguientes casos.

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 finales: SUCCEEDED, FAILED o REJECTED. La ejecución del comando ahora pasa a ser final y no acepta más actualizaciones.

El dispositivo también puede actualizar un estado TIMED_OUT iniciado por la nube informando de que se ha agotado el tiempo de espera mientras se ejecutaba el comando. En este caso, el estado de ejecución del comando permanece en TIMED_OUT, pero el objeto statusReason se actualizará en función de la información proporcionada por el dispositivo. La ejecución del comando ahora pasa a ser final y no aceptará más actualizaciones.

Uso de las sesiones persistentes de MQTT

Puede configurar las sesiones persistentes de MQTT para usar con la característica de comandos de AWS IoT Device Management. 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 del comando se ha configurado en un valor que supera esta duración, el agente de mensajes puede rechazar las ejecuciones del comando, por lo que se puede 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.

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

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 sean de su propiedad pueden procesar el mensaje de respuesta y publicar el resultado en 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, se mostrará a continuación el formato de 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:

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

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

Devolverá la URL del punto de conexión específico de la cuenta, tal y como se muestra en el ejemplo de respuesta que aparece a continuación.

{
    "endpointAddress": "<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 comando start-command-execution de la AWS CLI.

En este ejemplo, sustituya:

aws iot-jobs-data start-command-execution \ 
    --command-arn <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --execution-timeout-seconds 900

La ejecución de este comando devuelve un ID de ejecución del comando. Puede usar este ID para consultar el estado de ejecución del comando, los detalles y el historial de ejecución del comando.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

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 conceden al usuario permiso para realizar la acción UpdateCommandExecution, consulte Ejemplos de políticas de conexión y publicación.

En este ejemplo, sustituya:

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.

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.

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> puede ser JSON o CBOR.

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

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.

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

Puede recuperar una ejecución del comando desde la consola mediante cualquiera de los siguientes métodos.

Utilice la operación de la API del plano de control HTTP GetCommandExecution 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:

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

En el siguiente ejemplo se muestra cómo recuperar información sobre un comando que se ha ejecutado mediante el comando start-command-execution de la AWS CLI. 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:

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.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/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"    
}

Puede ver todas las ejecuciones de comandos desde la consola mediante cualquiera de los siguientes métodos.

Utilice la operación de la API HTTP del plano de control ListCommandExecutionsAWS IoT Core para enumerar todas las ejecuciones de comandos de la 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:

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

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.

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:

{
  "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 comando delete-command de la AWS CLI. 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.