Criar um recurso de comando Recuperar informações sobre um comando Liste os comandos em seu Conta da AWS Atualizar um recurso de comando Suspender ou restaurar um recurso de comando Excluir um recurso de comando

Criar e gerenciar comandos

Use AWS IoT Device Management comandos para configurar ações remotas reutilizáveis ou enviar instruções imediatas aos dispositivos. Crie e gerencie comandos no AWS IoT console ou usando AWS CLI o.

Operações de criar e gerenciar comandos

Criar um recurso de comando
Recuperar informações sobre um comando
Liste os comandos em seu Conta da AWS
Atualizar um recurso de comando
Suspender ou restaurar um recurso de comando
Excluir um recurso de comando

Criar um recurso de comando

Forneça as seguintes informações ao criar um Comando:

Informações gerais

Forneça um ID de comando exclusivo para identificar o comando ao executá-lo nos dispositivos de destino. Opcionalmente, especifique um nome de exibição, descrição e tags para gerenciamento.
Carga útil

Para comandos estáticos, forneça uma carga que defina as ações do dispositivo. Especifique o tipo de formato do Payload para a interpretação correta do dispositivo.

Para comandos dinâmicos, consulte o atributo do modelo Payload.
Modelo de carga

Para comandos dinâmicos, forneça um PayloadTemplate com espaços reservados e parâmetros. Opcionalmente, forneça defaultValue e condicione. AWS IoT Device Management Os comandos substituem os espaços reservados em tempo de execução. Os parâmetros ausentes usam seu DefaultValue. Todos os valores devem satisfazer as condições definidas.

Os seguintes tipos de espaço reservado com distinção entre maiúsculas e minúsculas são compatíveis:
- ${aws:iot:commandexecution::parameter:parameter1}— Um espaço reservado para o valor de um parâmetro com o nomeparameter1.
- ${aws:iot:commandexecution::executionTimeoutSec}— Um espaço reservado para o parâmetro de tempo limite de execução do comando fornecido em tempo de execução.

Comandos reservados Os tópicos usam um formato baseado no tipo de formato Payload.

Para application/json nossos tipos de application/cbor conteúdo, use este tópico de solicitação:
```
$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>
```
Para outros tipos de conteúdo ou formato não especificado, use este tópico de solicitação. O formato Payload aparece no cabeçalho da mensagem MQTT.
```
$aws/commands/<devices>/<DeviceID>/executions/+/request
```

O tópico de resposta dos comandos usa json ou cbor formata independentemente do tipo de carga útil. <PayloadFormat>deve ser json oucbor:


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

As seções a seguir descrevem as considerações sobre o formato de carga útil e a criação de comandos a partir do console.

Tópicos

Formato de carga útil de comando estático
Formato de carga útil de comando dinâmico
Como criar um comando (console)

Formato de carga útil de comando estático

O Payload suporta qualquer formato de até 32 KB. Especifique o tipo de formato do Payload para uma interpretação segura e correta do dispositivo.

Especifique o tipo de formato de carga usando o type/subtype formato (por exemplo, application/json ouapplication/cbor). Padrão: application/octet-stream. Consulte Tipos comuns de MIME para ver os formatos compatíveis.

Formato de carga útil de comando dinâmico

O PayloadTemplate deve ser um JSON válido com pelo menos um espaço reservado, de até 32 KB.

Para o AwsJsonSubstitution pré-processador, o AWS IoT Device Management Commands envia notificações no formato JSON ou CBOR com base na configuração do pré-processador.

Como criar um comando (console)

Para criar um comando a partir do console, acesse o Command Hub e siga estas etapas:

Escolha Criar comando.
Especifique um ID de comando exclusivo.
(Opcional) Especifique o nome de exibição, a descrição e as tags.
Faça upload do arquivo Payload contendo as ações do dispositivo. Especifique o tipo de formato do Payload para a interpretação correta do dispositivo.
(Opcional) Para modelos de carga útil JSON com espaços reservados, os parâmetros são pré-preenchidos na tabela embutida para edição.
(Opcional) Configure o tipo de valor do parâmetro (obrigatório), o valor padrão e as condições.
Escolha Criar comando.

Use o comando CreateCommandda API ou da create-commandCLI para criar um comando.

Carga útil do comando

Forneça uma carga estática ou um modelo de carga útil. As cargas estáticas são codificadas em base64. Para modelos de carga útil, a carga útil final é gerada em tempo de execução usando valores de parâmetros. Os dispositivos processam a carga e executam ações especificadas. Especifique o tipo de conteúdo do Payload para a recepção correta do dispositivo.

nota

As cargas não podem ser modificadas após a criação do Comando. Crie um novo comando para modificar a 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:

region por sua Região da AWS, como us-east-1.
account-id pelo número de sua Conta da AWS , como 123456789012.
command-idcom um identificador exclusivo para seu ID de AWS IoT comando, comoLockDoor. Se quiser enviar mais de um comando, você poderá especificá-los na seção Recursos na política do IAM.


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

Exemplo de criação de comando estático

O exemplo a seguir mostra como você pode criar um comando estático. Dependendo da sua aplicação, substitua:

<command-id> por um identificador exclusivo para o comando. Por exemplo, para trancar a porta da sua casa, você pode especificarLockDoor. Recomendamos usar o UUID. Você também pode usar caracteres alfanuméricos, “-” e “_”.
(Opcional) <display-name> e <description>, que são campos opcionais que você pode usar para fornecer um nome amigável e uma descrição significativa para o comando, como Lock the doors of my home.
namespace, que você pode usar para especificar o namespace do comando. Deve ser AWS-IoT. Para obter informações sobre como usar esse recurso para AWS IoT FleetWise, consulte Comandos remotos
payload contém informações sobre a carga útil que você deseja usar ao executar o comando e seu tipo de conteúdo.


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

Exemplo de criação de comando dinâmico

O exemplo a seguir mostra como você pode criar um comando dinâmico. Dependendo da sua aplicação, substitua:

<command-id> por um identificador exclusivo para o comando. Por exemplo, para definir o status da energia da luz, você pode especificarLight_Power_Status. Recomendamos usar o UUID. Você também pode usar caracteres alfanuméricos, “-” e “_”.
(Opcional) <display-name> e <description>, que são campos opcionais que você pode usar para fornecer um nome amigável e uma descrição significativa para o comando, como Turn a light ON or OFF.
namespace, que você pode usar para especificar o namespace do comando. Deve ser AWS-IoT. Para obter informações sobre como usar esse recurso para AWS IoT FleetWise, consulte Comandos remotos
payloadTemplatecontém o modelo de carga de reprodução formatado em JSON com espaços reservados.
preprocessorcontém a configuração do pré-processador que determina como o PayloadTemplate deve ser processado.
mandatoryParametercontém os parâmetros correspondentes aos espaços reservados no PayloadTemplate, seu tipo, valores padrão e condições.


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

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 Light_Power_Status durante a criação, o trecho seguinte mostra um exemplo de saída da execução dele.


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

Recuperar informações sobre um comando

Depois de criar um comando, você pode recuperar informações sobre ele no console da AWS IoT e usando a AWS CLI. Você pode acessar as informações a seguir.

O ID do comando, o nome do recurso da Amazon (ARN), qualquer nome de exibição e a descrição que você especificou para o comando.
O estado que indica se um comando está disponível para execução no dispositivo de destino, ou se ele está sendo suspenso ou foi excluído.
A carga ou o PayloadTemplate que você forneceu.
O pré-processador que você forneceu.
Os parâmetros obrigatórios que você forneceu.
A hora em que o comando foi criado e atualizado pela última vez.

Para recuperar um comando do console, acesse o Command Hub do AWS IoT console 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 plano de controle GetCommandHTTP ou o get-command AWS CLI comando 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

Neste exemplo, substitua:

region por sua Região da AWS, como us-east-1.
account-id pelo número de sua Conta da AWS , como 123456789023.
command-idcom seu identificador de comando AWS IoT exclusivo, como LockDoor ouLight_Power_Status. Se quiser recuperar mais de um comando, você poderá especificá-los na seção Recurso na política do IAM.


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

Recuperar um exemplo de comando (AWS CLI)

O exemplo a seguir mostra como recuperar informações sobre um comando usando o. get-command 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
}

Liste os comandos em seu Conta da AWS

Depois de criar comandos, você pode visualizá-los na sua conta. Na lista, você encontrará informações sobre:

O ID dos comandos e todos os nomes de exibição que você especificou para eles.
O nome do recurso da Amazon (ARN) dos comandos.
O estado que indica se os comandos estão disponíveis para execução no dispositivo de destino ou se foram suspensos.

nota
A lista não mostra os que estão sendo excluídos da sua conta. Se os comandos estiverem com a exclusão pendente, você ainda poderá visualizar os respectivos detalhes usando o ID do comando.
A hora em que os comandos foram criados e atualizados pela última vez.

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

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

Neste exemplo, substitua:

region por sua Região da AWS, como us-east-1.
account-id pelo número de sua Conta da AWS , como 123456789012.


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

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.

Atualizar um recurso de comando

Depois de criar um comando, você pode atualizar o nome de exibição e a descrição dele.

nota

Não é possível atualizar a carga útil do comando. Para atualizar essas informações ou usar uma carga útil modificada, você precisará criar outro comando.

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

Para atualizar um recurso de comando existente, escolha o comando a ser atualizado e, em Ações, escolha Editar.
Especifique o nome de exibição e a descrição que você deseja usar e os pares de nome-valor como tags para seu comando.
Escolha Editar para salvar o comando com as novas configurações.

Use a operação da API do plano de UpdateCommandcontrole ou a update-command AWS CLI para atualizar um recurso de comando. Usando essa API, você pode:

Editar o nome de exibição e a descrição de um comando criado por você.
Suspender um recurso de comando ou restaurar um comando que já tenha sido suspenso.

Exemplo de política do IAM

Neste exemplo, substitua:

region por sua Região da AWS, como us-east-1.
account-id pelo número de sua Conta da AWS , como 123456789012.
command-id pelo seu identificador de comando exclusivo da AWS IoT , como LockDoor. Se quiser recuperar mais de um comando, você poderá especificá-los na seção Recurso na política do IAM.


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

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

O exemplo a seguir mostra como atualizar as informações sobre um comando usando o update-command AWS CLI comando. 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: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"
}

Suspender ou restaurar um recurso de comando

Depois de criar um comando, se não quiser mais usá-lo, você poderá marcá-lo como suspenso. Quando você suspende um comando, todas as execuções pendentes dele continuam sendo executadas no dispositivo de destino até atingirem o status terminal. Depois que um comando for suspenso, se você quiser usá-lo para enviar uma nova execução para o dispositivo de destino, deverá restaurá-lo.

nota

Você não pode editar um comando suspenso nem realizar novas execuções dele. Para executar novos comandos no dispositivo, você deve restaurá-lo para que o estado do comando mude para Disponível.

Para acessar informações adicionais sobre a suspensão e a restauração de um comando e considerações sobre ele, consulte Suspender um recurso de comando.

Excluir um recurso de comando

Se você não quiser mais usar um comando, poderá removê-lo permanentemente da sua conta. Se a ação de exclusão for bem-sucedida:

Se o comando permanecer suspenso por um período maior que o tempo limite máximo de 12 horas, ele será excluído imediatamente.
Se o comando não foi suspenso ou permanecer suspenso por um período menor que o valor do tempo limite máximo, ele entrará no estado pending deletion. Ele será removido automaticamente da sua conta após o tempo limite máximo de 12 horas.

nota

O comando poderá ser excluído mesmo se houver alguma execução pendente. O comando estará em um estado de exclusão pendente e será removido da sua conta automaticamente.

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

Escolha o comando a ser excluído e, em Ações, selecione Excluir.
Confirme que você deseja excluir o comando e, depois, selecione Excluir.

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 plano de controle DeleteCommand HTTP ou o delete-command AWS CLI comando 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

Neste exemplo, substitua:

region por sua Região da AWS, como us-east-1.
account-id pelo número de sua Conta da AWS , como 123456789012.
command-id pelo seu identificador de comando exclusivo da AWS IoT , como LockDoor. Se quiser recuperar mais de um comando, você poderá especificá-los na seção Recurso na política do IAM.


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

Exemplo de como excluir um comando (AWS CLI)

Os exemplos a seguir mostram como excluir um comando usando o delete-command AWS CLI comando. 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.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Fluxo de trabalho de comandos

Iniciar e monitorar execuções de comando

Criar e gerenciar comandos

Operações de criar e gerenciar comandos

Criar um recurso de comando

Informações gerais

Tópicos

Formato de carga útil de comando estático

Formato de carga útil de comando dinâmico

Como criar um comando (console)

Tópicos

Carga útil do comando

nota

Exemplo de política do IAM

Exemplo de criação de comando estático

Exemplo de criação de comando dinâmico

Recuperar informações sobre um comando

Exemplo de política do IAM

Recuperar um exemplo de comando (AWS CLI)

Liste os comandos em seu Conta da AWS

nota

Exemplo de política do IAM

Exemplo de como listar comandos em sua conta

Atualizar um recurso de comando

nota

Exemplo de política do IAM

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

Suspender ou restaurar um recurso de comando

nota

Excluir um recurso de comando

nota

Exemplo de política do IAM

Exemplo de como excluir um comando (AWS CLI)