Fluxo de trabalho de comandos de alto nível - AWS IoT Core
Criar e gerenciar comandosEscolher destinos e assinar tópicosIniciar e monitorar execuções de comando(Opcional) Habilitar notificações para eventos de comandos

Fluxo de trabalho de comandos de alto nível

As etapas a seguir fornecem uma visão geral do fluxo de trabalho de comandos entre seus dispositivos e comandos do AWS IoT Device Management. Quando você usa qualquer um dos comandos das operações da API HTTP, a solicitação é assinada usando credenciais do Sigv4.

Visão geral do fluxo de trabalho de alto nível de comandos do dispositivo AWS IoT Device Management.

Criar e gerenciar comandos

Para criar e gerenciar comandos para seus dispositivos, realize as etapas a seguir.

  1. Criar um recurso de comando

    Antes de enviar o comando aos seus dispositivos, crie um recurso no Hub de comandos do console da AWS IoT ou use a operação da API do ambiente de gerenciamento CreateCommand.

  2. Especificar a carga útil

    Ao criar o comando, forneça uma carga útil para ele. O conteúdo da carga útil pode usar qualquer formato de sua escolha. Para garantir que o dispositivo interprete corretamente a carga útil, recomendamos que você também especifique o tipo de conteúdo dela.

  3. (Opcional) Gerenciar os comandos criados

    Depois de criar o comando, atualize o nome de exibição e a descrição dele. Você também poderá marcar um comando como suspenso se não quiser mais usá-lo ou removê-lo completamente da sua conta. Se desejar modificar as informações da carga útil, crie um comando e carregue o arquivo da carga.

Escolher o dispositivo de destino para os comandos e assinar os tópicos do MQTT

Para se preparar para o fluxo de trabalho de comandos, escolha o dispositivo de destino e especifique os tópicos reservados do MQTT da AWS IoT para receber comandos e publicar mensagens de resposta.

  1. Escolher o dispositivo de destino para o comando

    Para se preparar para o fluxo de trabalho de comandos, escolha o dispositivo de destino que receberá o comando e realizará as ações especificadas. O dispositivo de destino pode ser uma coisa da AWS IoT que você tenha incluído no registro da AWS IoT ou pode ser especificado usando o ID do cliente do MQTT, caso seu dispositivo não tenha sido registrado na AWS IoT. Para obter mais informações, consulte Considerações sobre dispositivos de destino.

  2. Configurar a política de dispositivos de IoT

    Para que seu dispositivo possa receber execuções de comandos e publicar atualizações, ele deve usar uma política do IAM que conceda permissões para realizar essas ações. Para ter acesso a exemplos de políticas que você pode usar dependendo de seu dispositivo estar registrado como uma coisa da AWS IoT ou especificado como um ID de cliente do MQTT, consulte Exemplo de política do IAM.

  3. Estabelecer uma conexão do MQTT

    Para preparar seus dispositivos para usar o recurso de comandos, eles devem primeiro se conectar ao agente de mensagens e assinar os tópicos de solicitação e resposta. Seu dispositivo deve ter permissão para realizar a ação iot:Connect de se conectar ao AWS IoT Core e estabelecer uma conexão do MQTT com o agente de mensagens. Para encontrar o endpoint do plano de dados da Conta da AWS, use a API DescribeEndpoint ou o comando describe-endpoint da CLI, conforme mostrado a seguir.

    aws iot describe-endpoint --endpoint-type iot:Data-ATS

    A execução desse comando exibe o endpoint do plano de dados específico da conta, conforme mostrado abaixo.

    account-specific-prefix.iot.region.amazonaws.com
  4. Assinar tópicos de comandos

    Depois de estabelecer conexão, seus dispositivos poderão assinar o tópico de solicitação de comandos. Quando você cria um comando e inicia a execução dele no dispositivo de destino, a mensagem de carga útil é publicada no tópico da solicitação pelo agente de mensagens. Seu dispositivo pode então receber a mensagem de carga útil e processar o comando.

    (Opcional) Seus dispositivos também podem assinar esses tópicos de resposta de comandos (accepted ou rejected) para receber uma mensagem indicando se o serviço de nuvem aceitou ou rejeitou a resposta do dispositivo.

    Neste exemplo, substitua:

    • <device> por thing ou client dependendo de o dispositivo que você está considerando ter sido registrado como uma coisa da IoT ou especificado como um cliente do MQTT.

    • <DeviceID> pelo identificador exclusivo do seu dispositivo de destino. Esse ID pode ser o exclusivo do cliente do MQTT ou o nome de uma coisa.

    nota

    Se o tipo de carga útil não for JSON nem CBOR, o campo <PayloadFormat> talvez não esteja presente no tópico de solicitação de comandos. Para saber o formato da carga útil, recomendamos que você use o MQTT 5 para receber as informações de formato dos cabeçalhos das mensagens do MQTT. Para obter mais informações, consulte Tópicos de comandos.

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

Iniciar e monitorar as execuções de comando para o dispositivo de destino

Depois de criar os comandos e especificar os destinos deles, você pode iniciar a execução no dispositivo de destino realizando as etapas a seguir.

  1. Iniciar a execução do comando no dispositivo de destino

    Inicie a execução do comando no dispositivo de destino por meio do Hub de comandos do console da AWS IoT ou usando a API StartCommandExecution do plano de dados com o endpoint específico da sua conta. Se você estiver usando endpoints de pilha dupla (IPv4 e IPv6), use o iot:Data-ATS. O endpoint iot:Jobs é somente para IPv4.

    A API publica a mensagem de carga útil no tópico de solicitação de comandos mencionado acima, que o dispositivo assinou.

    nota

    Se o dispositivo estava offline quando o comando foi enviado da nuvem e se ele usa sessões persistentes do MQTT, o comando espera no agente de mensagens. Se o dispositivo voltar a ficar on-line antes do tempo limite e se tiver assinado o tópico de solicitação de comandos, ele poderá processar o comando e publicar o resultado no tópico de resposta de comandos. Se o dispositivo não voltar a ficar on-line antes do tempo limite, a execução do comando atingirá o tempo limite, e a mensagem de carga útil poderá expirar e ser descartada pelo agente de mensagens.

  2. Atualizar o resultado da execução do comando

    O dispositivo agora recebe a mensagem de carga útil, pode processar o comando e realizar as ações especificadas e, depois, publicar o resultado da execução do comando no tópico de resposta de comandos a seguir usando a API UpdateCommandExecution. Se o seu dispositivo assinou os tópicos de resposta aceitos e rejeitados dos comandos, ele receberá uma mensagem indicando se a resposta foi aceita ou rejeitada pelo serviço de nuvem.

    Dependendo de sua especificação no tópico da solicitação, <devices> podem ser coisas ou clientes, e <DeviceID> pode ser o nome da sua coisa da IoT ou o ID do cliente do MQTT.

    nota

    O <PayloadFormat> pode ser apenas JSON ou CBOR no tópico de resposta dos comandos.

    $aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>
  3. (Opcional) Recuperar o resultado da execução do comando

    Para recuperar o resultado da execução do comando, você pode visualizar o histórico do comando no console da AWS IoT ou usar a operação da API GetCommandExecution do ambiente de gerenciamento. Para recuperar as informações mais recentes, seu dispositivo deve ter publicado o resultado da execução do comando no tópico de resposta dos comandos. Você também pode receber informações adicionais sobre os dados de execução, como quando foram atualizados pela última vez, o resultado da execução e quando ela foi concluída.

(Opcional) Habilitar notificações para eventos de comandos

É possível assinar eventos de comandos para receber notificações quando o status de uma execução é alterado. As etapas a seguir mostram como assinar eventos de comandos e processá-los.

  1. Criar uma regra de tópico

    É possível assinar eventos de tópicos de comandos e receber notificações quando o status de uma execução de comando é alterado. Você também pode criar uma regra de tópico para direcionar os dados processados pelo dispositivo para outros serviços da AWS IoT compatíveis com regras, como AWS Lambda, Amazon SQS e AWS Step Functions. É possível criar uma regra de tópico usando o console da AWS IoT ou a operação da API CreateTopicRule do ambiente de gerenciamento do AWS IoT Core. Para obter mais informações, consulte Criar uma regra de AWS IoT.

    Neste exemplo, substitua <CommandID> pelo identificador do comando para o qual você deseja receber notificações e <CommandExecutionStatus> pelo status da execução do comando.

    $aws/events/commandExecution/<CommandID>/<CommandExecutionStatus>
    nota

    Para receber notificações de todos os comandos e os status de execução deles, você pode usar caracteres curinga e assinar o tópico a seguir.

    $aws/events/commandExecution/+/#
  2. Receber e processar eventos de comandos

    Se você criou uma regra de tópico na etapa anterior para assinar eventos de comandos, poderá gerenciar as notificações por push de comandos recebidas e criar aplicações com base nesses serviços.

O código a seguir mostra um exemplo de carga útil para as notificações de eventos de comandos que você receberá.

{
    "executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554",
    "status":"FAILED",
    "statusReason": {
         "reasonCode": "DEVICE_TOO_BUSY",
         "reasonDescription": ""
    },
    "eventType": "COMMAND_EXECUTION",
    "commandArn":"arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086",
    "targetArn":"arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd",
    "timestamp":1717708862107
}