Creación y administración de comandos - AWS IoT Core
Creación de un recurso de comandosRecuperación de información sobre un comandoEnumere los comandos de su Cuenta de AWSActualización de un recurso de comandosObsolescencia o restauración de un recurso de comandosEliminación de un recurso 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.

Creación y administración de comandos

Usa AWS IoT Device Management los comandos para configurar acciones remotas reutilizables o envía instrucciones inmediatas a los dispositivos. Cree y gestione comandos desde la AWS IoT consola o mediante el AWS CLI.

Creación de un recurso de comandos

Proporcione la siguiente información al crear un comando:

  • Información general

    Proporcione un identificador de comando único para identificar el comando cuando lo ejecute en los dispositivos de destino. Si lo desea, especifique un nombre para mostrar, una descripción y etiquetas para la administración.

  • Carga útil

    En el caso de los comandos estáticos, proporciona una carga útil que defina las acciones del dispositivo. Especifique el tipo de formato de carga útil para una interpretación correcta del dispositivo.

    Para ver los comandos dinámicos, consulte el atributo de plantilla Payload.

  • Plantilla de carga útil

    Para los comandos dinámicos, proporciona una plantilla de carga útil con marcadores de posición y parámetros. Si lo desea, proporcione condicionesdefaultValue. AWS IoT Device Management Los comandos sustituyen a los marcadores de posición en tiempo de ejecución. Los parámetros que faltan utilizan su DefaultValue. Todos los valores deben cumplir las condiciones definidas.

    Se admiten los siguientes tipos de marcadores de posición que distinguen mayúsculas de minúsculas:

    • ${aws:iot:commandexecution::parameter:parameter1}— Un marcador de posición para el valor de un parámetro con el nombre. parameter1

    • ${aws:iot:commandexecution::executionTimeoutSec}— Un marcador de posición para el parámetro de tiempo de espera de ejecución del comando que se proporciona en tiempo de ejecución.

Comandos reservados Los temas utilizan un formato basado en el tipo de formato de carga útil.

  • Para nuestros application/json tipos de application/cbor contenido, utilice este tema de solicitud:

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

  • Para otros tipos de contenido o formatos no especificados, utilice este tema de solicitud. El formato de carga útil aparece en el encabezado del mensaje MQTT.

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

El tema de respuesta a los comandos utiliza json o cbor formatea independientemente del tipo de carga útil. <PayloadFormat>debe ser json ocbor:

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

En las siguientes secciones se describen las consideraciones sobre el formato de carga útil y la creación de comandos desde la consola.

Formato de carga útil de comandos estáticos

La carga útil admite cualquier formato de hasta 32 KB. Especifique el tipo de formato de carga útil para una interpretación segura y correcta del dispositivo.

Especifique el tipo de formato de carga útil mediante el type/subtype formato (p. ej., application/json oapplication/cbor). Predeterminado: application/octet-stream. Consulta los tipos MIME más comunes para ver los formatos compatibles.

Formato de carga útil de comandos dinámicos

La plantilla de carga útil debe ser un archivo JSON válido con al menos un marcador de posición (32 KB como máximo).

En el caso AwsJsonSubstitution del preprocesador, AWS IoT Device Management Commands envía las notificaciones en formato JSON o CBOR en función de la configuración del preprocesador.

Cómo crear un comando (consola)

Para crear un comando desde la consola, vaya al Centro de comandos y siga estos pasos:

  1. Seleccione Crear comando.

  2. Especifique un ID de comando único.

  3. (Opcional) Especifique el nombre para mostrar, la descripción y las etiquetas.

  4. Cargue el archivo de carga útil que contiene las acciones del dispositivo. Especifique el tipo de formato de carga útil para una interpretación correcta del dispositivo.

  5. (Opcional) En el caso de las plantillas de carga útil JSON con marcadores de posición, los parámetros se rellenan previamente en la tabla integrada para su edición.

  6. (Opcional) Configure el tipo de valor del parámetro (obligatorio), el valor predeterminado y las condiciones.

  7. Seleccione Crear comando.

Utilice el comando CreateCommandAPI o create-commandCLI para crear un comando.

Carga útil de comandos

Proporcione una carga útil estática o una plantilla de carga útil. Las cargas útiles estáticas están codificadas en base64. En el caso de las plantillas de carga útil, la carga útil final se genera en tiempo de ejecución mediante valores de parámetros. Los dispositivos procesan la carga útil y realizan acciones específicas. Especifique el tipo de contenido de la carga útil para una correcta recepción del dispositivo.

nota

Las cargas útiles no se pueden modificar después de la creación del comando. Crea un comando nuevo para modificar la carga útil.

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, 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 ID de AWS IoT comando, comoLockDoor. Si desea enviar más de un comando, puede especificarlos en la sección Recursos de la política de IAM.

{
    "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 comandos estáticos

El siguiente ejemplo muestra cómo se puede crear un comando estático. En función de la aplicación, sustituya:

  • <command-id> por un identificador único para el comando. Por ejemplo, para bloquear la puerta de su casa, puede especificarloLockDoor. 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. Para obtener información sobre el uso de esta función AWS IoT FleetWise, consulte Comandos remotos

  • 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:us-east-1:123456789012:command/LockDoor"
}

Ejemplo de creación dinámica de comandos

El siguiente ejemplo muestra cómo se puede crear un comando dinámico. En función de la aplicación, sustituya:

  • <command-id> por un identificador único para el comando. Por ejemplo, para establecer el estado de alimentación de la luz, puede especificarloLight_Power_Status. 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 Turn a light ON or OFF.

  • namespace, que puede utilizar para especificar el espacio de nombres del comando. Debe ser AWS-IoT. Para obtener información sobre el uso de esta función AWS IoT FleetWise, consulte Comandos remotos

  • payloadTemplatecontiene la plantilla de reproducción en formato JSON con marcadores de posición.

  • preprocessorcontiene la configuración del preprocesador que determina cómo se debe procesar la plantilla de carga útil.

  • mandatoryParametercontiene los parámetros correspondientes a los marcadores de posición de la plantilla de carga útil, su tipo, los valores predeterminados y las condiciones.

aws iot create-command \
    --command-id Light_Power_Status \
    --description "Turn a light ON or OFF" \
    --namespace AWS-IoT \
    --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \
    --preprocessor awsJsonSubstitution={outputFormat=JSON} \
    --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]"

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 Light_Power_Status durante la creación, a continuación se muestra un ejemplo del resultado de la ejecución del comando.

{
    "commandId": "Light_Power_Status",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status"
}

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 o la plantilla de carga útil que has proporcionado.

  • El preprocesador que ha proporcionado.

  • Los parámetros obligatorios que ha proporcionado.

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

Usa la operación de la API del plano de control GetCommandHTTP o el get-command AWS CLI comando para recuperar información sobre un recurso de comando. 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, us-east-1.

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

  • command-idcon su identificador de comando AWS IoT único, como LockDoor oLight_Power_Status. Si desea recuperar más de un comando, puede especificarlos en la sección Recursos de la política de IAM.

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

El siguiente ejemplo muestra cómo recuperar información sobre un comando mediante get-command AWS CLI. 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
}

Enumere los comandos de su 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 AWS IoT consola, puedes encontrar la lista de comandos que has 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, us-east-1.

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

{
    "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 AWS IoT consola 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 API del plano de UpdateCommandcontrol o la update-command AWS CLI 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, us-east-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.

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

El siguiente ejemplo muestra cómo actualizar la información sobre un comando mediante el update-command AWS CLI comando. 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:us-east-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 de la consola, vaya al centro de comandos de la AWS IoT consola 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 API del plano de control DeleteCommand HTTP o el delete-command AWS CLI comando para eliminar un recurso de comando. 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, us-east-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.

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

Los siguientes ejemplos muestran cómo eliminar un comando mediante el delete-command AWS CLI comando. 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.