Crie e gerencie comandos - AWS IoT Core
Crie um recurso de comandoRecuperar informações sobre um comandoListe os comandos em seu Conta da AWSAtualizar um recurso de comandoDescontinuar ou restaurar um recurso de comandoExcluir um recurso de comando

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Crie e gerencie comandos

Você pode usar o recurso de AWS IoT Device Management comandos para configurar ações remotas reutilizáveis ou enviar instruções únicas e imediatas para seus dispositivos. As seções a seguir mostram como você pode criar e gerenciar comandos a partir do AWS IoT console e usando AWS CLI o.

Crie um recurso de comando

Ao criar um comando, você deve fornecer as seguintes informações.

  • Informações gerais

    Ao criar um comando, você deve fornecer um ID de comando, que é um identificador exclusivo para ajudá-lo a identificar o comando quando quiser executá-lo no dispositivo de destino. Opcionalmente, você também pode especificar um nome de exibição, descrição e tags para ajudá-lo ainda mais a gerenciar o comando.

  • Carga útil

    Você também deve fornecer uma carga útil que defina as ações que o dispositivo deve executar. Embora opcional, recomendamos que você especifique o tipo de formato da carga para que o dispositivo interprete corretamente a carga.

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

  • Se você especificar um tipo de conteúdo de carga útil de application/json ouapplication/cbor, o tópico da solicitação será o seguinte.

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

  • Se você especificar um tipo de conteúdo de carga útil diferente de application/json ouapplication/cbor, ou se não especificar o tipo de formato de carga útil, o tópico da solicitação será o seguinte. Nesse caso, o formato da carga útil será incluído no cabeçalho da MQTT mensagem.

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

O tópico de resposta dos comandos retornará um formato que usa json ou cbor independe do tipo de formato de carga útil. O tópico de resposta usará o seguinte formato, onde <PayloadFormat> deve ser json oucbor.

$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 a partir do console.

Formato de carga útil do comando

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

Você especifica o tipo de formato da carga usando o type/subtype formato, como application/json ouapplication/cbor. Por padrão, ele será definido comoapplication/octet-stream. Para obter informações sobre os formatos de carga que você pode especificar, consulte MIMETipos comuns.

Como criar um comando (console)

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

  1. Para criar um novo recurso de comando, escolha Criar comando.

  2. Especifique um ID de comando exclusivo para ajudá-lo a identificar o comando que você deseja executar no dispositivo de destino.

  3. (Opcional) Especifique um nome de exibição opcional, uma descrição e quaisquer pares de nome-valor como tags para seu comando.

  4. Faça upload do arquivo de carga útil do seu armazenamento local que contém as ações que o dispositivo precisa realizar. Embora opcional, recomendamos que você especifique o tipo de formato da carga para que o dispositivo interprete corretamente o arquivo e processe as instruções.

  5. Escolha Criar comando.

Esta seção descreve a API operação do plano de HTTP CreateCommandcontrole e o AWS CLI comando correspondente create-commandque você pode executar para criar um recurso de comando.

Carga útil do comando

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

nota

Depois de criar o comando, você não pode modificar a carga. Para modificar a carga, você precisará criar um novo comando.

IAMPolítica de amostra

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

Neste exemplo, substitua:

  • regioncom o seu Região da AWS, comoap-south-1.

  • account-idcom seu Conta da AWS número, como123456789012.

  • command-idcom um identificador exclusivo para seu ID de AWS IoT comando, comoLockDoor. Se quiser enviar mais de um comando, você pode especificar esses comandos na seção Recurso da IAM política.

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:CreateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"          
    }
}

Crie um exemplo de comando

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

  • <command-id>com um identificador exclusivo para o comando. Por exemplo, para bloquear o histórico documental de sua casa, você pode especificar. LockDoor 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, comoLock the doors of my home.

  • namespace, que você pode usar para especificar o namespace do comando. Deve serAWS-IoT.

  • payloadconté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 ARN (nome do recurso da Amazon) do comando. Por exemplo, se você especificou o LockDoor comando durante a criação, o seguinte mostra um exemplo de saída da execução do comando.

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

Recuperar informações sobre um comando

Depois de criar um comando, você pode recuperar informações sobre ele no AWS IoT console e usando o. AWS CLI Você pode obter as seguintes informações.

  • O ID do comando, o nome do recurso da Amazon (ARN), qualquer nome de exibição e descrição que você especificou para o comando.

  • O estado do comando, que indica se um comando está disponível para execução no dispositivo de destino ou se está sendo descontinuado ou excluído.

  • A carga que você forneceu e seu tipo de formato.

  • 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 do comando, que fornece informações sobre as execuções do comando no dispositivo de destino. Depois de executar esse comando no dispositivo, você pode encontrar informações sobre as execuções nessa guia.

Use a API operação do plano de GetCommandHTTPcontrole 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 CreateCommand API solicitação ou create-command CLI o.

IAMPolítica de amostra

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

Neste exemplo, substitua:

  • regioncom o seu Região da AWS, comoap-south-1.

  • account-idcom seu Conta da AWS número, como123456789023.

  • command-idcom seu identificador de comando AWS IoT exclusivo, comoLockDoor. Se quiser recuperar mais de um comando, você pode especificar esses comandos na seção Recurso da IAM política.

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:GetCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"          
    }
}

Recupere 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 do seu aplicativo, <command-id> substitua pelo identificador do comando para o qual você deseja recuperar informações. Você pode obter essas informações na resposta do create-commandCLI.

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

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

Por exemplo, 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 os comandos, você pode ver os comandos que você criou na sua conta. Na lista, você pode encontrar informações sobre:

  • O ID do comando e qualquer nome de exibição que você especificou para os comandos.

  • O nome do recurso Amazon (ARN) dos comandos.

  • O estado do comando que indica se os comandos estão disponíveis para execução no dispositivo de destino ou se estão obsoletos.

    nota

    A lista não exibe os que estão sendo excluídos da sua conta. Se os comandos estiverem pendentes de exclusão, você ainda poderá visualizar os detalhes desses comandos 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 ListCommandsAPIoperação ou list-commandsCLIo.

IAMPolítica de amostra

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

Neste exemplo, substitua:

  • regioncom o seu Região da AWS, comoap-south-1.

  • account-idcom seu Conta da AWS número, como123456789012.

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:ListCommands",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/*"          
    }
}

Exemplo de lista de comandos em sua conta

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

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

A execução desse comando gera uma resposta que contém uma lista dos comandos que você criou, a hora em que os comandos foram criados e quando foram atualizados pela última vez. Ele também fornece as informações do estado do comando, que indicam se um comando foi descontinuado ou está disponível para execução no dispositivo de destino. Para obter mais informações sobre os diferentes status e o motivo do status, consulteStatus 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 do comando.

nota

A carga útil do comando não pode ser atualizada. Para atualizar essas informações ou usar uma carga modificada, você precisará criar um novo comando.

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

  1. Para atualizar um recurso de comando existente, escolha o comando que você deseja atualizar e, em Ações, escolha Editar.

  2. Especifique o nome de exibição e a descrição que você deseja usar e quaisquer pares de nome-valor como tags para seu comando.

  3. Escolha Editar para salvar o comando com as novas configurações.

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

  • Edite o nome de exibição e a descrição de um comando que você criou.

  • Deprecie um recurso de comando ou restaure um comando que já tenha sido descontinuado.

IAMPolítica de amostra

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

Neste exemplo, substitua:

  • regioncom o seu Região da AWS, comoap-south-1.

  • account-idcom seu Conta da AWS número, como123456789012.

  • command-idcom seu identificador de comando AWS IoT exclusivo, comoLockDoor. Se quiser recuperar mais de um comando, você pode especificar esses comandos na seção Recurso da IAM política.

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:UpdateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/<command-id>"          
    }
}

Atualizar informações sobre um comando examples (AWS CLI)

O exemplo a seguir mostra como atualizar as informações sobre um comando usando o update-command AWS CLI comando. Para obter informações sobre como você pode usar isso API para descontinuar 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 do seu aplicativo, <command-id> substitua pelo identificador do comando para o qual você deseja recuperar informações.

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

A execução desse comando gera uma resposta que contém as informações atualizadas sobre o comando e a hora em que ele foi atualizado pela última vez. 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 AC.

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

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

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

Descontinuar ou restaurar um recurso de comando

Depois de criar um comando, se não quiser mais continuar usando o comando, você pode marcá-lo como obsoleto. Quando você descontinuar um comando, todas as execuções de comandos pendentes continuarão sendo executadas no dispositivo de destino até atingirem o status do terminal. Depois que um comando for descontinuado, se você quiser usá-lo para enviar uma nova execução de comando para o dispositivo de destino, deverá restaurá-lo.

nota

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

Para obter informações adicionais sobre a descontinuação e a restauração de um comando e considerações sobre ele, consulte. Descontinuar 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 tiver sido descontinuado por um período maior que o tempo limite máximo de 12 horas, ele será excluído imediatamente.

  • Se o comando não estiver obsoleto ou tiver sido preterido por um período menor que o tempo limite máximo, o comando estará em um estado. pending deletion Ele será removido automaticamente da sua conta após o tempo limite máximo de 12 horas.

nota

O comando pode ser excluído mesmo se houver alguma execução de comando 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.

  1. Escolha o comando que você deseja excluir e, em Ações, escolha Excluir.

  2. Confirme que você deseja excluir o comando e escolha Excluir.

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

Use a API operação do plano de DeleteCommand HTTP controle 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 HTTP statusCode de 204 ou 202, e o comando será excluído da sua conta automaticamente após o tempo limite máximo de 12 horas. No caso do status 204, isso indica que o comando foi excluído.

IAMPolítica de amostra

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

Neste exemplo, substitua:

  • regioncom o seu Região da AWS, comoap-south-1.

  • account-idcom seu Conta da AWS número, como123456789012.

  • command-idcom seu identificador de comando AWS IoT exclusivo, comoLockDoor. Se quiser recuperar mais de um comando, você pode especificar esses comandos na seção Recurso da IAM política.

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:DeleteCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"          
    }
}

Excluir um exemplo de comando (AWS CLI)

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

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

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