Creación y administración de comandos - AWS IoT Core
Creación de un recurso de comandosRecuperación de información sobre un comandoEnumeración de los comandos de la Cuenta de AWSActualización de un recurso de comandosObsolescencia o restauración de un recurso de comandosEliminación de un recurso de comandos

Creación y administración de comandos

Puede usar la característica de comandos de AWS IoT Device Management para configurar acciones remotas reutilizables o enviar instrucciones únicas e inmediatas a los dispositivos. En las siguientes secciones se muestra cómo crear y administrar comandos desde la consola de AWS IoT y mediante la AWS CLI.

Creación de un recurso de comandos

Al crear un comando, debe proporcionar la siguiente información:

  • Información general

    Al crear un comando, debe proporcionar un ID de comando, que es un identificador único que le ayudará a identificar el comando cuando desee ejecutarlo en el dispositivo de destino. Si lo desea, también puede especificar un nombre para mostrar, una descripción y etiquetas para facilitar aún más la administración del comando.

  • Carga

    También debe proporcionar una carga útil que defina las acciones que debe realizar el dispositivo. Si bien es opcional, le recomendamos que especifique el tipo de formato de la carga útil para que el dispositivo la interprete correctamente.

Los temas reservados de comandos utilizan un formato que depende del tipo de formato de la carga útil.

  • Si especifica un tipo de contenido de carga útil application/json o application/cbor, el tema de la solicitud será el siguiente.

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

  • Si especifica un tipo de contenido de carga útil que no sea application/json ni application/cbor, o si no especifica el tipo de formato de carga útil, el tema de la solicitud será el siguiente. En este caso, el formato de la carga útil se incluirá en el encabezado del mensaje de MQTT.

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

El tema de respuesta de comandos devolverá un formato que utiliza json o cbor, con independencia del tipo de formato de la carga útil. El tema de respuesta utilizará el siguiente formato donde <PayloadFormat> debe ser json ocbor.

$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

En las siguientes secciones se muestran consideraciones sobre el formato de la carga útil de los comandos y cómo crear comandos desde la consola.

Formato de la carga útil de los comandos

La carga útil puede usar cualquier formato de su elección. El tamaño máximo de la carga útil no debe superar los 32 KB. Para garantizar que el dispositivo puede interpretar de forma segura y correcta la carga útil, le recomendamos que especifique también el tipo de formato de la carga útil.

Especifique el tipo de formato de la carga útil mediante el formato type/subtype, como, por ejemplo, application/json o application/cbor. De forma predeterminada, se establecerá como application/octet-stream. Para obtener más información sobre los formatos de la carga útil que puede especificar, consulte Tipos de MIME comunes.

Cómo crear un comando (consola)

Para crear un comando desde la consola, vaya al Centro de comandos de la consola de AWS IoT y lleve a cabo los siguientes pasos.

  1. Para crear un nuevo recurso de comandos, elija Crear comando.

  2. Especifique un ID de comando único que le ayude a identificar el comando que desea ejecutar en el dispositivo de destino.

  3. (Opcional) Especifique un nombre para mostrar, una descripción y cualquier par de nombre y valor opcionales como etiquetas para el comando.

  4. Cargue el archivo de carga útil desde su almacenamiento local que incluye las acciones que debe realizar el dispositivo. Si bien es opcional, le recomendamos que especifique el tipo de formato de la carga útil para que el dispositivo interprete correctamente el archivo y procese las instrucciones.

  5. Seleccione Crear comando.

En esta sección se describe la operación de la API del plano de control HTTP, CreateCommand, y el correspondiente comando de la AWS CLI, create-command, que puede ejecutar para crear un recurso de comandos.

Carga útil de comandos

Al crear el comando, debe proporcionar una carga útil. La carga útil que proporciona tiene codificación base64. Cuando los dispositivos reciben el comando, la lógica del dispositivo puede procesar la carga útil y realizar las acciones especificadas. Para garantizar que los dispositivos reciban correctamente el comando y la carga útil, le recomendamos que especifique el tipo de contenido de la carga útil.

nota

Tras crear el comando, no puede modificar la carga útil. Para modificar la carga útil, deberá crear un comando nuevo.

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

En este ejemplo, sustituya:

  • region con la Región de AWS, como, por ejemplo, ap-south-1.

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

  • command-id con un identificador único parea el ID del comando de AWS IoT, como, por ejemplo, LockDoor. Si desea enviar más de un comando, puede especificarlos en la sección Recursos de la política de IAM.

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:CreateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Ejemplo de creación de un comando

En el ejemplo siguiente se muestra cómo crear un comando. En función de la aplicación, sustituya:

  • <command-id> por un identificador único para el comando. Por ejemplo, para bloquear el historial de revisión de su casa, puede especificar LockDoor. Le recomendamos que utilice UUID. También puede utilizar caracteres alfanuméricos, “-” y “_”.

  • (Opcional) <display-name> y <description>, que son campos opcionales que puede usar para proporcionar un nombre descriptivo y una descripción significativa para el comando, como, por ejemplo Lock the doors of my home.

  • namespace, que puede utilizar para especificar el espacio de nombres del comando. Debe ser AWS-IoT.

  • payload incluye información sobre la carga útil que desea utilizar al ejecutar el comando y su tipo de contenido.

aws iot create-command \ 
    --command-id <command-id> \
    --display-name <display-name> \
    --description <description> \ 
    --namespace AWS-IoT \ 
    --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}'

La ejecución de este comando genera una respuesta que incluye el ID y el ARN (nombre de recurso de Amazon) del comando. Por ejemplo, si ha especificado el comando LockDoor durante la creación, a continuación se muestra un ejemplo del resultado de la ejecución del comando.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor"
}

Recuperación de información sobre un comando

Tras crear un comando, puede recuperar información sobre este desde la consola de AWS IoT y mediante la AWS CLI. Puede obtener la siguiente información.

  • El ID del comando, el nombre de recurso de Amazon (ARN) y cualquier nombre y descripción visibles que haya especificado para el comando.

  • El estado del comando que indica si un comando está disponible para ejecutarse en el dispositivo de destino o si se va a quedar obsoleto o se va a eliminar.

  • La carga útil que proporcionó y su tipo de formato.

  • El momento en que se creó el comando y se actualizó por última vez.

Para recuperar un comando de la consola, vaya al Centro de comandos de la consola de AWS IoT y, a continuación, elija el comando que creó para ver sus detalles.

Además de los detalles del comando, puede ver el historial de comandos, que proporciona información sobre las ejecuciones del comando en el dispositivo de destino. Tras ejecutar este comando en el dispositivo, encontrará información sobre las ejecuciones en esta pestaña.

Utilice la operación de la API del plano de control HTTP GetCommand o el comando de la AWS CLI get-command para recuperar información sobre un recurso de comandos. Debe haber creado ya el comando mediante la solicitud de la API CreateCommand o de la CLI create-command.

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

En este ejemplo, sustituya:

  • region con la Región de AWS, como, por ejemplo, ap-south-1.

  • account-id con el número de la Cuenta de AWS, como, por ejemplo 123456789023.

  • command-id con el identificador único del comando de AWS IoT, como, por ejemplo, LockDoor. Si desea recuperar más de un comando, puede especificarlos en la sección Recursos de la política de IAM.

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:GetCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Ejemplo de recuperación de un comando (AWS CLI)

En el siguiente ejemplo se muestra cómo recuperar información sobre un comando mediante la AWS CLI get-command. En función de la aplicación, sustituya <command-id> por el identificador del comando para el que desea recuperar la información. Puede obtener esta información de la respuesta de la CLI create-command.

aws iot get-command --command-id <command-id>

Al ejecutar este comando, se genera una respuesta que incluye información sobre el comando, la carga útil y el momento de creación y de la última actualización. También proporciona información que indica si un comando ha quedado obsoleto o se va a eliminar.

En el siguiente código se muestra una respuesta de ejemplo. 

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:<region>:<account>:command/LockDoor",
    "namespace": "AWS-IoT",
    "payload":{
        "content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=",
        "contentType": "application/json"
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
    "deprecated": false,
    "pendingDeletion": false
}

Enumeración de los comandos de la Cuenta de AWS

Una vez que haya creado los comandos, podrá ver los comandos que ha creado en la cuenta. En la lista, puede encontrar información sobre:

  • El ID del comando y cualquier nombre para mostrar que haya especificado para los comandos.

  • El nombre de recurso de Amazon (ARN) de los comandos.

  • El estado del comando que indica si los comandos están disponibles para ejecutarse en el dispositivo de destino o si se van a quedar obsoletos.

    nota

    En la lista no se muestran los comandos que se van a eliminar de la cuenta. Si los comandos están pendientes de eliminación, aún puede ver los detalles de estos comandos mediante el ID de comando.

  • El momento en que se crearon los comandos y su última actualización.

En la consola de AWS IoT, puede encontrar la lista de comandos que ha creado y sus detalles en el Centro de comandos.

Para enumerar los comandos que ha creado, utilice la operación de la API ListCommands o la CLI list-commands.

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

En este ejemplo, sustituya:

  • region con la Región de AWS, como, por ejemplo, ap-south-1.

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

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:ListCommands",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/*"
    }
}

Ejemplo de enumeración de los comandos de la cuenta

En el siguiente comando se muestra cómo enumerar los comandos de la cuenta.

aws iot list-commands --namespace "AWS-IoT"

Al ejecutar este comando, se genera una respuesta que incluye una lista de los comandos que ha creado, el momento de creación de los comandos y su última actualización. También proporciona información sobre el estado del comando, que indica si un comando ha quedado obsoleto o si está disponible para ejecutarse en el dispositivo de destino. Para obtener más información sobre los distintos estados y el motivo del estado, consulte Estado de la ejecución del comando.

Actualización de un recurso de comandos

Una vez creado un comando, puede actualizar el nombre para mostrar y la descripción del comando.

nota

No se puede actualizar la carga útil del comando. Para actualizar esta información o usar una carga útil modificada, tendrá que crear un comando nuevo.

Para actualizar un comando desde la consola, vaya al Centro de comandos de la consola de AWS IoT y lleve a cabo los siguientes pasos.

  1. Para actualizar un recurso de comandos existente, elija el comando que desee actualizar y, a continuación, en Acciones, seleccione Editar.

  2. Especifique un nombre para mostrar, una descripción y cualquier par de nombre y valor como etiquetas para el comando.

  3. Seleccione Editar para guardar el comando con la nueva configuración.

Utilice la operación de la API del plano de control UpdateCommand o la AWS CLI update-command para actualizar un recurso de comandos. Con esta API, podrá:

  • Editar el nombre para mostrar y la descripción de un comando que haya creado.

  • Dar de baja un recurso de comandos o restaurar un comando que ya haya quedado obsoleto.

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

En este ejemplo, sustituya:

  • region con la Región de AWS, como, por ejemplo, ap-south-1.

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

  • command-id con el identificador único del comando de AWS IoT, como, por ejemplo, LockDoor. Si desea recuperar más de un comando, puede especificarlos en la sección Recursos de la política de IAM.

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:UpdateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Ejemplos de actualización de la información sobre un comando (AWS CLI)

En el siguiente ejemplo se muestra cómo actualizar información sobre un comando mediante el comando update-command de la AWS CLI. Para obtener más información sobre cómo usar esta API para dar de baja o restaurar un recurso de comandos, consulte Actualización de un recurso de comandos (CLI).

En el ejemplo se muestra cómo se puede actualizar el nombre para mostrar y la descripción de un comando. En función de la aplicación, sustituya <command-id> por el identificador del comando para el que desea recuperar la información.

aws iot update-command \ 
    --command-id <command-id>    
    --displayname <display-name> \
    --description <description>

Al ejecutar este comando, se genera una respuesta que incluye información sobre el comando y el momento de su última actualización. En el siguiente código se muestra un ejemplo de solicitud y respuesta para actualizar el nombre para mostrar y la descripción de un comando que desactiva la CA.

aws iot update-command \ 
    --command-id <LockDoor> \ 
    --displayname <Secondary lock door> \
    --description <Locks doors to my home>

La ejecución de este comando genera la siguiente respuesta.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "displayName": "Secondary lock door",
    "description": "Locks doors to my home",
    "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00"
}

Obsolescencia o restauración de un recurso de comandos

Una vez creado un comando, si ya no desea seguir utilizándolo, puede marcarlo como obsoleto. Al marcar como obsoleto un comando, todas las ejecuciones de comandos pendientes seguirán ejecutándose en el dispositivo de destino hasta que alcancen el estado final. Una vez que un comando haya quedado obsoleto, si quiere usarlo, por ejemplo, para enviar una nueva ejecución de comando al dispositivo de destino, debe restaurarlo.

nota

No puede editar un comando obsoleto ni ejecutarlo. Para ejecutar nuevos comandos en el dispositivo, debe restaurarlo para que el estado del comando cambie a Disponible.

Para obtener información adicional sobre la obsolescencia y la restauración de un comando, así como otros aspectos que hay que tener en cuenta, consulte Obsolescencia de un recurso de comandos.

Eliminación de un recurso de comandos

Si ya no quiere usar un comando, puede eliminarlo permanentemente de la cuenta. Si la acción de eliminación se realiza correctamente:

  • Si el comando ha quedado obsoleto durante un periodo superior al tiempo de espera máximo de 12 horas, se eliminará inmediatamente.

  • Si el comando no ha quedado obsoleto o ha dejado de utilizarse durante un periodo inferior al tiempo de espera máximo, el comando pasará al estado pending deletion. Se eliminará automáticamente de la cuenta una vez transcurrido el tiempo de espera máximo de 12 horas.

nota

Es posible que el comando se elimine incluso si hay alguna ejecución pendiente de ejecución. El comando estará en un estado pendiente de eliminación y se eliminará automáticamente de la cuenta.

Para eliminar un comando desde la consola, vaya al Centro de comandos de la consola de AWS IoT y lleve a cabo los siguientes pasos.

  1. Elija el comando que desea eliminar y, a continuación, en Acciones y elija Eliminar.

  2. Confirme que desea eliminar el comando y, a continuación, seleccione Eliminar.

El comando se marcará para su eliminación y se eliminará permanentemente de la cuenta después de 12 horas.

Utilice la operación de la API del plano de control HTTP DeleteCommand o el comando delete-command de la AWS CLI para eliminar un recurso de comandos. Si la acción de eliminación se realiza correctamente, aparecerá un statusCode de HTTP de 204 o 202 y el comando se eliminará automáticamente de la cuenta una vez transcurrido el tiempo máximo de espera de 12 horas. En el caso del estado 204, indica que el comando se ha eliminado.

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

En este ejemplo, sustituya:

  • region con la Región de AWS, como, por ejemplo, ap-south-1.

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

  • command-id con el identificador único del comando de AWS IoT, como, por ejemplo, LockDoor. Si desea recuperar más de un comando, puede especificarlos en la sección Recursos de la política de IAM.

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:DeleteCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Ejemplo de eliminación de un comando (AWS CLI)

En los siguientes ejemplos se muestra cómo eliminar un comando mediante el comando delete-command de la AWS CLI. En función de la aplicación, sustituya <command-id> por el identificador del comando que vaya a eliminar.

aws iot delete-command --command-id <command-id>

Si la solicitud a la API se realiza correctamente, el comando generará un código de estado 202 o 204. Puede usar la API GetCommand para comprobar que el comando ya no existe en la cuenta.