Criar e gerenciar comandos

Os tópicos reservados dos comandos usam um formato que depende do tipo de formato da carga útil.

O tópico de resposta dos comandos exibirá um formato que usa json ou cbor independe do tipo de formato de carga útil. O tópico de resposta usará o formato a seguir, em que <PayloadFormat> deve ser json ou cbor.

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

As seções a seguir mostram as considerações sobre o formato da carga útil do comando e como criar comandos no console.

Formato de carga útil do comando

A carga útil pode usar qualquer formato de sua escolha. O tamanho máximo da carga útil não deve exceder 32 KB. Para garantir que o dispositivo interprete de forma segura e correta a carga útil, recomendamos que você especifique o tipo de formato dela.

Você especifica o tipo de formato de carga útil usando o formato type/subtype, como application/json ou application/cbor. Por padrão, ele será definido como application/octet-stream. Para ter informações sobre os formatos de carga útil que você pode especificar, consulte Tipos comuns de MIME.

Como criar um comando (console)

Para criar um comando no console, acesse o Hub de comandos do console da AWS IoT e realize as etapas a seguir.

Esta seção descreve a operação da API do ambiente de gerenciamento HTTP, o CreateCommand e o comando da AWS CLI correspondente, create-command que você pode executar para criar um recurso de comando.

Carga útil do comando

Ao criar o comando, forneça uma carga útil. A carga útil fornecida é codificada em base64. Quando seus dispositivos recebem o comando, a lógica do lado do dispositivo pode processar a carga útil e realizar as ações especificadas. Para garantir que os dispositivos recebam corretamente o comando e a carga útil, recomendamos que você especifique o tipo de conteúdo da carga.

Exemplo de política do IAM

Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação CreateCommand.

Neste exemplo, substitua:

Exemplo de criação de comando

O exemplo a seguir mostra como criar um comando. Dependendo da sua aplicação, substitua:

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

A execução desse comando gera uma resposta que contém o ID e o ARN (nome do recurso da Amazon) do comando. Por exemplo, se você especificou o comando LockDoor durante a criação, o trecho seguinte mostra um exemplo de saída da execução dele.

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

Para recuperar um comando do console, acesse o Hub de comandos do console da AWS IoT e escolha o comando que você criou para ver seus detalhes.

Além dos detalhes do comando, você pode ver o histórico dele, que fornece informações sobre as execuções no dispositivo de destino. Depois de executar esse comando no dispositivo, você encontrará informações sobre as execuções nessa guia.

Use a operação da API do ambiente de gerenciamento HTTP GetCommand ou o comando get-commandAWS CLI para recuperar informações sobre um recurso de comando. Você já deve ter criado o comando usando a solicitação de API CreateCommand ou a CLI create-command.

Exemplo de política do IAM

Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação GetCommand.

Neste exemplo, substitua:

Recuperar um exemplo de comando (AWS CLI)

O exemplo a seguir mostra como recuperar informações sobre um comando usando o get-command da AWS CLI. Dependendo da sua aplicação, substitua <command-id> pelo identificador do comando para o qual você deseja recuperar informações. Você pode acessar essas informações na resposta da CLI create-command.

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

A execução desse comando gera uma resposta com informações sobre ele, bem como a carga útil e a hora em que ele foi criado e atualizado pela última vez. Ela também fornece informações que indicam se um comando foi suspenso ou está sendo excluído.

O código a seguir mostra um exemplo de resposta.

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

No console da AWS IoT, você pode encontrar a lista de comandos que você criou e os respectivos detalhes acessando o Hub de comandos.

Para listar os comandos que você criou, use a operação de API ListCommands ou a CLI list-commands.

Exemplo de política do IAM

Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação ListCommands.

Neste exemplo, substitua:

Exemplo de como listar comandos em sua conta

O comando a seguir mostra como listar comandos em sua conta.

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

A execução desse comando gera uma resposta que contém uma lista dos comandos criados, a hora em que eles foram criados e quando foram atualizados pela última vez. Ele também fornece as informações de estado do comando, que indicam se ele foi suspenso ou se está disponível para execução no dispositivo de destino. Para acessar mais informações sobre os diferentes status e os respectivos motivos, consulte Status de execução do comando.

Para atualizar um comando no console, acesse o Hub de comandos do console da AWS IoT e execute as etapas a seguir.

Use a operação da API do ambiente de gerenciamento UpdateCommand ou a update-commandAWS CLI para atualizar um recurso de comando. Usando essa API, você pode:

Exemplo de política do IAM

Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação UpdateCommand.

Neste exemplo, substitua:

Exemplos de como atualizar informações sobre um comando (AWS CLI)

O exemplo a seguir mostra como atualizar informações sobre um comando usando o comando update-command da AWS CLI. Para ter informações sobre como você pode usar essa API para suspender ou restaurar um recurso de comando, consulte Atualizar um recurso de comando (CLI).

O exemplo mostra como você pode atualizar o nome de exibição e a descrição de um comando. Dependendo da sua aplicação, substitua <command-id> pelo identificador do comando cujas informações você deseja recuperar.

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

A execução desse comando gera uma resposta com as informações atualizadas sobre ele e a respectiva atualização mais recente. O código a seguir mostra um exemplo de solicitação e resposta para atualizar o nome de exibição e a descrição de um comando que desliga o ar condicionado.

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

A execução desse comando gera a resposta a seguir.

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

Para excluir um comando no console, acesse o Hub de comandos do console da AWS IoT e execute as etapas a seguir.

O comando será marcado para exclusão e será removido permanentemente da sua conta após 12 horas.

Use a operação da API do ambiente de gerenciamento HTTP DeleteCommand ou o comando delete-command da AWS CLI para excluir um recurso de comando. Se a ação de exclusão for bem-sucedida, você verá um statusCode HTTP de 204 ou 202, e o comando será excluído da sua conta automaticamente após o tempo limite máximo de 12 horas. O status 204 indica que o comando foi excluído.

Exemplo de política do IAM

Antes de usar essa operação de API, garanta que sua política do IAM autorize você a realizar essa ação no dispositivo. O exemplo a seguir mostra uma política do IAM que permite ao usuário realizar a ação DeleteCommand.

Neste exemplo, substitua:

Exemplo de como excluir um comando (AWS CLI)

Os exemplos a seguir mostram como excluir um comando usando delete-command da AWS CLI. Dependendo da sua aplicação, substitua <command-id> pelo identificador do comando que você está excluindo.

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

Se a solicitação da API for bem-sucedida, o comando gerará um código de status 202 ou 204. Você pode usar a API GetCommand para verificar se o comando não existe mais na sua conta.