Flujo de trabajo de comandos de alto nivel - AWS IoT Core
Creación y administración de comandosSelección de los dispositivos de destino y suscripción a los temasInicio y supervisión de las ejecuciones de comandos(Opcional) Habilitación de las notificaciones para los eventos de comandos

Flujo de trabajo de comandos de alto nivel

Los siguientes pasos proporcionan una descripción general del flujo de trabajo de comandos entre los dispositivos y los comandos de AWS IoT Device Management. Al utilizar cualquiera de las operaciones de la API HTTP de los comandos, la solicitud se firma con las credenciales de Sigv4.

Descripción general del flujo de trabajo de alto nivel de los comandos del dispositivo AWS IoT Device Management

Creación y administración de comandos

Para crear y administrar comandos para los dispositivos, siga los pasos que se indican a continuación.

  1. Creación de un recurso de comandos

    Antes de enviar el comando a los dispositivos, cree un recurso de comando en el Centro de comandos de la consola de AWS IoT o utilice la operación de la API del plano de control CreateCommand.

  2. Especificación de la carga útil

    Al crear el comando, debe proporcionar una carga útil para el comando. El contenido de carga útil puede usar cualquier formato de su elección. Para garantizar que el dispositivo interpreta correctamente la carga útil, le recomendamos que especifique también el tipo de contenido de la carga útil.

  3. (Opcional) Administración de los comandos creados

    Una vez creado el comando, puede actualizar el nombre y la descripción del comando para mostrar. También puede marcar un comando como obsoleto si ya no lo va a usar o eliminarlo por completo de la cuenta. Si desea modificar la información de la carga útil, debe crear un nuevo comando y cargar el nuevo archivo de carga útil.

Selección del dispositivo de destino para los comandos y suscripción a los temas de MQTT

Para preparar el flujo de trabajo de los comandos, elija el dispositivo de destino y especifique los temas reservados de MQTT de AWS IoT para recibir los comandos y publicar los mensajes de respuesta.

  1. Selección del dispositivo de destino para el comando

    Para preparar el flujo de trabajo de los comandos, elija el dispositivo de destino que recibirá el comando y realice las acciones especificadas. El dispositivo de destino puede ser un objeto de AWS IoT que haya registrado en el registro de AWS IoT o puede especificarse mediante el ID de cliente de MQTT, si el dispositivo no se ha registrado en AWS IoT. Para obtener más información, consulte Consideraciones sobre los dispositivos de destino.

  2. Configuración de la política de dispositivos de IoT

    Para que el dispositivo pueda recibir ejecuciones de comandos y publicar actualizaciones, debe utilizar una política de IAM que conceda permisos para realizar estas acciones. Para ver ejemplos de políticas que puede utilizar en función de si el dispositivo está registrado como objeto de AWS IoT o si se ha especificado como un ID de cliente de MQTT, consulte Ejemplo de política de IAM.

  3. Establecimiento de una conexión con MQTT

    Para preparar los dispositivos para que usen la característica de comandos, primero deben conectarse al agente de mensajes y suscribirse a los temas de solicitud y respuesta. El dispositivo debe tener permiso para realizar la acción iot:Connect para conectarse a AWS IoT Core y establecer una conexión con MQTT con el agente de mensajes. Para encontrar el punto de conexión del plano de datos de la Cuenta de AWS, utilice la API DescribeEndpoint o el comando de la CLI describe-endpoint, tal y como se muestra a continuación.

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

    Al ejecutar este comando, se devolverá el punto de conexión del plano de datos específico de la cuenta, tal como se muestra a continuación.

    account-specific-prefix.iot.region.amazonaws.com
  4. Suscripción a los temas de comandos

    Una vez establecida una conexión, los dispositivos pueden suscribirse al tema de solicitud de comandos. Al crear un comando e iniciar la ejecución del mismo en el dispositivo de destino, el agente de mensajes publicará el mensaje de carga útil en el tema de solicitud. A continuación, el dispositivo podrá recibir el mensaje de carga útil y procesar el comando.

    (Opcional) Los dispositivos también pueden suscribirse a estos temas de respuesta de los comandos (accepted o rejected) para recibir un mensaje que indique si el servicio en la nube ha aceptado o rechazado la respuesta del dispositivo.

    En este ejemplo, sustituya:

    • <device> con thing o client en función de si el dispositivo al que se dirige se ha registrado como un objeto de IoT o se ha especificado como un cliente de MQTT.

    • <DeviceID> con el identificador único del dispositivo de destino. Este ID puede ser el ID único de cliente de MQTT o el nombre de un objeto.

    nota

    Si el tipo de carga útil no es JSON ni CBOR, es posible que el campo <PayloadFormat> no esté presente en el tema de solicitud de comandos. Para obtener el formato de carga útil, le recomendamos que utilice MQTT 5 para obtener la información de formato de los encabezados de los mensajes de MQTT. Para obtener más información, consulte Temas de comandos.

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

Inicio y supervisión de las ejecuciones de comandos en el dispositivo de destino

Una vez creados los comandos y especificado los destinos del comando, puede iniciar la ejecución en el dispositivo de destino realizando los siguientes pasos.

  1. Inicio de la ejecución de comandos en el dispositivo de destino

    Inicie la ejecución del comando en el dispositivo de destino en el Centro de comandos de la consola de AWS IoT o mediante la API del plano de datos StartCommandExecution con el punto de conexión específico de la cuenta. 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.

    La API publica el mensaje de carga útil en el tema de solicitud de comandos mencionado anteriormente al que se ha suscrito el dispositivo.

    nota

    Si el dispositivo estaba sin conexión cuando se envió el comando desde la nube y utiliza sesiones persistentes de MQTT, el comando esperará en el agente de mensajes. Si el dispositivo vuelve a conectarse antes de que se agote el tiempo de espera y se ha suscrito al tema de solicitud de comandos, el dispositivo puede procesar el comando y publicar el resultado en el tema de respuesta de los comandos. Si el dispositivo no vuelve a conectarse antes de que se agote el tiempo de espera, se agotará el tiempo de espera de la ejecución del comando y es posible que el mensaje de carga útil caduque y el agente de mensajes lo descarte.

  2. Actualización del resultado de la ejecución de comandos

    El dispositivo recibe ahora el mensaje de carga útil y puede procesar el comando y realizar las acciones especificadas y, a continuación, publicar el resultado de la ejecución del comando en el siguiente tema de respuesta de los comandos mediante la API UpdateCommandExecution. Si el dispositivo se ha suscrito a los temas de respuesta aceptada y rechazada de los comandos, recibirá un mensaje en el que se indicará si el servicio en la nube ha aceptado o rechazado la respuesta.

    En función de cómo se especifique en el tema de solicitud, <devices> pueden ser objetos o clientes y <DeviceID> puede ser el nombre del objeto de IoT o el ID del cliente de MQTT.

    nota

    <PayloadFormat> solo puede ser JSON o CBOR en el tema de respuesta de los comandos.

    $aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>
  3. (Opcional) Recuperación del resultado de la ejecución de comandos

    Para recuperar el resultado de la ejecución del comando, puede ver el historial de comandos en la consola de AWS IoT o utilizar la operación de la API del plano de control GetCommandExecution. Para obtener la información más reciente, el dispositivo debe haber publicado el resultado de la ejecución del comando en el tema de respuesta de los comandos. También puede obtener información adicional sobre los datos de ejecución, como, por ejemplo, cuándo se actualizaron por última vez, el resultado de la ejecución y cuándo se completó la ejecución.

(Opcional) Habilitación de las notificaciones para los eventos de comandos

Puede suscribirse a los eventos de comandos para recibir notificaciones cuando cambie el estado de la ejecución de un comando. En los siguientes pasos se muestra cómo suscribirse a los eventos de comandos y, a continuación, procesarlos.

  1. Creación de una regla del tema

    Puede suscribirse al tema de eventos de comandos y recibir notificaciones cuando cambie el estado de la ejecución de un comando. También puede crear una regla de tema para dirigir los datos procesados por el dispositivo a otros servicios de AWS IoT compatibles con las reglas, como, por ejemplo, AWS Lambda, Amazon SQS y AWS Step Functions. Puede crear una regla de tema mediante la consola de AWS IoT o la operación de la API del plano de control CreateTopicRule de AWS IoT Core. Para obtener más información, consulte Creación de una regla de AWS IoT.

    En este ejemplo, sustituya <CommandID> por el identificador del comando del que desea recibir notificaciones y <CommandExecutionStatus> por el estado de la ejecución del comando.

    $aws/events/commandExecution/<CommandID>/<CommandExecutionStatus>
    nota

    Para recibir notificaciones de todos los comandos y estados de ejecución de los comandos, puede utilizar caracteres comodín y suscribirse al tema siguiente.

    $aws/events/commandExecution/+/#
  2. Recepción y procesamiento de los eventos de comandos

    Si ha creado una regla de tema en el paso anterior para suscribirse a los eventos de comandos, puede administrar las notificaciones push sobre los comandos que reciba y crear una aplicación basada en estos servicios.

En el siguiente código se muestra un ejemplo de carga útil para las notificaciones de eventos de comandos que recibirá.

{
    "executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554",
    "status":"FAILED",
    "statusReason": {
         "reasonCode": "DEVICE_TOO_BUSY",
         "reasonDescription": ""
    },
    "eventType": "COMMAND_EXECUTION",
    "commandArn":"arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086",
    "targetArn":"arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd",
    "timestamp":1717708862107
}