Iniciar y supervisar las ejecuciones de comandos

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

AWS IoT cosa

El dispositivo de destino del comando puede ser cualquier AWS IoT cosa que haya registrado en el registro de AWS IoT cosas. Las características AWS IoT facilitan la búsqueda y la administración de sus dispositivos.

Puede registrar su dispositivo como una cosa al conectarlo AWS IoT desde la página Conectar dispositivo o utilizando el CreateThingAPI. Puede encontrar un elemento existente para el que desee ejecutar el comando en la página Thing Hub de la AWS IoT consola o utilizando el DescribeThingAPI. Para obtener información sobre cómo registrar un dispositivo como una AWS IoT cosa, consulte Administrar cosas con el registro.

ID de cliente

Si tu dispositivo no se ha registrado como un elemento AWS IoT, puedes usar el ID de cliente en su lugar.

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

El ID de cliente suele ser el ID de MQTT cliente que tus dispositivos pueden usar al conectarse 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 durante el que el dispositivo puede 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 pudo informar del resultado de la ejecución dentro del tiempo de espera, se agotará el tiempo de espera de la ejecución del comando y el estado de la ejecución se mostrará comoTIMED_OUT.

Este campo es opcional y tendrá un valor predeterminado de 10 segundos si no especificas 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 TIMED_OUT de ejecución

Tanto la nube como el dispositivo pueden informar de un tiempo de espera.

Una vez que se envía el comando al dispositivo, se inicia un temporizador. Si no se recibe ninguna respuesta del dispositivo dentro del tiempo de espera especificado, tal y como se ha descrito 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 podría ocurrir en cualquiera de los siguientes casos.

En este caso, cuando el estado de ejecución de TIMED_OUT se informa desde la nube, la ejecución del comando no es terminal. 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 ahora pasa 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 actualizará en función de la información proporcionada por el dispositivo. La ejecución del comando pasará a ser terminal y no se aceptarán más actualizaciones.

Uso de sesiones MQTT persistentes

Puede configurar sesiones MQTT persistentes para utilizarlas con la función de AWS IoT Device Management comandos. Esta función resulta especialmente útil en casos como cuando el dispositivo se queda sin conexión y quiere asegurarse de que el dispositivo sigue recibiendo el comando cuando vuelve a conectarse antes de que se agote el tiempo de espera y sigue las instrucciones especificadas.

De forma predeterminada, la caducidad de la sesión MQTT persistente está establecida en 60 minutos. Si el tiempo de espera de ejecución del comando está configurado en un valor que supera esta duración, las ejecuciones de comandos que se ejecuten durante más de 60 minutos pueden ser rechazadas por el agente de mensajes y provocar un error. Para ejecutar comandos que duren más de 60 minutos, puedes 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 Command Hub de la AWS IoT consola y lleve a cabo los siguientes pasos.

Utilice la API operación del plano de StartCommandExecutionHTTPdatos para iniciar la ejecución de un comando. La API solicitud y la respuesta se correlacionan mediante el identificador de ejecución del comando. Una vez que el dispositivo termina 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 ellos AWS IoT.

Si tus dispositivos están suscritos al tema de solicitud de comandos, StartCommandExecution API publicarán el mensaje de carga útil en ese tema. La carga útil puede utilizar cualquier formato de tu elección. Para obtener más información, consulte Carga útil del comando.

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

Si el formato de la carga útil no es JSON oCBOR, a continuación se muestra el formato del tema de solicitud de comandos.

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

Ejemplo de política IAM

Antes de usar esta API operación, asegúrate de que tu IAM política te autorice a realizar esta acción en el dispositivo. En el siguiente ejemplo, se muestra una IAM política que permite al usuario realizar la StartCommandExecution acción.

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

Obtenga el punto final del plano de datos específico de la cuenta

Antes de ejecutar el API comando, debe obtener el punto final específico de la cuenta para el punto finalURL. iot:Jobs Por ejemplo, si ejecuta este comando:

aws iot describe-endpoint --endpoint-type iot:Jobs

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

{
    "endpointAddress": "<account-specific-prefix>.jobs.iot.<region>.amazonaws.com"
}

Ejemplo de inicio de la ejecución de un comando ()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:

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

La ejecución de este comando devuelve un identificador 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 API operación, asegúrate de que tu IAM política 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 IAM políticas que otorgan al usuario permiso para realizar la UpdateCommandExecution acción, consulteEjemplos de políticas de conexión y publicación.

En este ejemplo, sustituya:

Ejemplo de IAM política para la identificación del MQTT cliente

El siguiente código muestra un ejemplo de política de dispositivo cuando se utiliza el ID de MQTT cliente.

{
  "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 IAM de política para IoT

El siguiente código muestra un ejemplo de política de dispositivos cuando se usa una AWS IoT cosa.

{
  "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 la solicitud, el dispositivo procesa el comando. A continuación, utiliza el UpdateCommandExecution API para actualizar el estado y el resultado de la ejecución del comando al 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 oCBOR.

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

El dispositivo informó de actualizaciones en el estado de ejecución

Sus dispositivos pueden utilizarla API para informar sobre cualquiera de las siguientes actualizaciones de estado relacionadas con la ejecución del comando. Para obtener más información sobre estos estados, consulteEstado de ejecución del comando.

Para obtener más información sobre el TIMED_OUT estado, consulteValor de tiempo de espera y estado TIMED_OUT de ejecución.

Consideraciones a la hora de utilizar el UpdateCommandExecution API

Las siguientes son algunas consideraciones importantes a la hora de utilizar el UpdateCommandExecutionAPI.

UpdateCommandExecutionAPIejemplo

El código siguiente muestra un ejemplo de cómo el dispositivo puede utilizar el campo UpdateCommandExecution API para informar del estado de la ejecución, el statusReason campo 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 el porcentaje de batería del coche en este caso.

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}

Puede recuperar la ejecución de un comando de la consola mediante uno de los métodos siguientes.

Utilice la HTTP API operación del plano de GetCommandExecution AWS IoT Core control para recuperar información sobre la ejecución de un comando. Debe haber ejecutado ya este comando mediante la StartCommandExecution API operación.

Ejemplo de IAM política

Antes de usar esta API operación, asegúrate de que tu IAM política te autorice a realizar esta acción en el dispositivo. En el siguiente ejemplo, se muestra una IAM política que permite al usuario realizar la GetCommandExecution acción.

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

Recupera un ejemplo de ejecución de comandos

El siguiente ejemplo muestra cómo recuperar información sobre un comando que se ejecutó con el start-command-execution AWS CLI comando. El siguiente ejemplo muestra cómo se puede recuperar información sobre un comando que se ejecutó para desactivar el modo de 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 contiene información sobre la ejecución ARN del comando, el estado de la ejecución y la hora en que comenzó a ejecutarse y cuándo se completó. También proporciona un statusReason objeto que contiene información adicional sobre el estado. Para obtener más información sobre los distintos estados y el motivo del estado, consulteEstado de ejecución del comando.

El código siguiente muestra un ejemplo de respuesta a la API solicitud.

{
    "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 uno de los siguientes métodos.

Utilice la HTTP API operación del plano de ListCommandExecutions AWS IoT Core control para enumerar todas las ejecuciones de comandos en su cuenta.

Ejemplo de IAM política

Antes de usar esta API operación, asegúrate de que tu IAM política te autorice a realizar esta acción en el dispositivo. En el siguiente ejemplo, se muestra una IAM política que permite al usuario realizar la ListCommandExecutions acción.

En este ejemplo, sustituya:

{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

Enumere un ejemplo de ejecuciones de comandos

El siguiente ejemplo muestra cómo enumerar las ejecuciones de comandos en su 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 dispositivo concreto mediante eltargetArn, o las ejecuciones de un comando concreto especificado mediante elcommandArn.

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 contiene una lista de las ejecuciones de comandos que ha creado y la hora en que las ejecuciones comenzaron a ejecutarse y en que finalizaron. También proporciona información de estado y el statusReason objeto que contiene 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, consulteEstado de ejecución del comando.

Antes de usar esta API operación, asegúrate de que tu IAM política 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 delete-command AWS CLI comando. En función de la aplicación, <execution-id> sustitúyala por el identificador de la ejecución del <target-arn> comando que vayas a eliminar y por el ARN del dispositivo de destino.

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

Si la API solicitud se realiza correctamente, la ejecución del comando genera un código de estado de 200. Puede utilizar el GetCommandExecution API para comprobar que la ejecución del comando ya no existe en su cuenta.