Iniciar e monitorar execuções de comando

Quando quiser executar o comando, você deverá especificar o dispositivo de destino que o receberá e seguir as instruções especificadas. O dispositivo de destino poderá ser uma coisa da AWS IoT ou o ID do cliente se o dispositivo não tiver sido registrado na AWS IoT. Depois de receber a carga útil do comando, o dispositivo pode começar a executá-lo e realizar as ações especificadas.

AWS IoTCoisa do

O dispositivo de destino para o comando pode ser uma coisa da AWS IoT que você tenha especificado no registro de coisas da AWS IoT. Coisas na AWS IoT facilitam a pesquisa e o gerenciamento de seus dispositivos.

Você pode registrar seu dispositivo como uma coisa ao conectá-lo à AWS IoT na página Conectar dispositivo ou usando a API CreateThing. Você pode encontrar uma coisa existente para a qual deseja executar o comando na página Hub de coisas do console da AWS IoT ou usando a API DescribeThing. Para acessar informações sobre como registrar o dispositivo como uma coisa da AWS IoT, consulte Managing things with the registry.

ID de cliente

Se o dispositivo não tiver sido registrado como uma coisa na AWS IoT, você poderá usar o ID do cliente.

O ID do cliente é um identificador exclusivo atribuído ao dispositivo ou ao cliente. O ID do cliente é definido no protocolo MQTT e pode conter caracteres alfanuméricos, sublinhados ou traços. Ele deve ser exclusivo para cada dispositivo que se conecta à AWS IoT.

O ID do cliente geralmente é o ID do cliente do MQTT que seus dispositivos podem usar ao se conectar ao AWS IoT Core. Esse ID é usado pela AWS IoT para identificar cada dispositivo específico e gerenciar conexões e assinaturas.

O tempo limite indica a duração em segundos na qual o dispositivo deve fornecer o resultado da execução do comando.

Depois de criar uma execução de comando, um temporizador é iniciado. Se o dispositivo ficar offline ou não relatar o resultado da execução dentro do tempo limite, a execução do comando atingirá o tempo limite e o status da execução será relatado como TIMED_OUT.

Esse campo é opcional e terá como padrão 10 segundos se você não especificar nenhum valor. Também é possível configurar o tempo limite como um valor máximo de 12 horas.

Valor do tempo limite e status de execução TIMED_OUT

Um tempo limite pode ser informado pela nuvem e pelo dispositivo.

Depois que o comando é enviado ao dispositivo, um temporizador é iniciado. Se não houve resposta recebida do dispositivo na duração do tempo limite especificado, conforme descrito acima. Nesse caso, a nuvem define o status de execução do comando como TIMED_OUT com o código do motivo como $NO_RESPONSE_FROM_DEVICE.

Isso pode ocorrer em qualquer um dos casos a seguir.

Nesse caso, quando o status de execução de TIMED_OUT é relatado na nuvem, a execução do comando não é terminal. Seu dispositivo pode publicar uma resposta que substitua o status em qualquer um dos status terminais, SUCCEEDED, FAILED ou REJECTED. A execução do comando agora se torna terminal e não aceita mais atualizações.

Seu dispositivo também pode atualizar um status TIMED_OUT iniciado pela nuvem relatando que ocorreu um tempo limite quando ele estava executando o comando. Nesse caso, o status de execução do comando permanece como TIMED_OUT, mas o objeto statusReason é atualizado com base nas informações relatadas pelo dispositivo. A execução do comando agora se tornará terminal e nenhuma atualização adicional será aceita.

Usar sessões persistentes do MQTT

É possível configurar as sessões persistentes do MQTT para usar com o recurso de comandos do AWS IoT Device Management. Esse recurso é especialmente útil quando, por exemplo, o dispositivo fica offline e você deseja garantir que o dispositivo ainda receba o comando quando voltar a ficar on-line antes do tempo limite e execute as instruções especificadas.

Por padrão, a expiração da sessão persistente do MQTT é definida como 60 minutos. Se o tempo limite de execução do comando estiver configurado como um valor que exceda essa duração, as execuções que excederem 60 minutos poderão ser rejeitadas pelo agente de mensagens e falhar. Para executar comandos com mais de 60 minutos de duração, você pode solicitar um aumento no tempo de expiração da sessão persistente.

Para começar a executar um comando no console, acesse a página Hub de comandos do console da AWS IoT e execute as etapas a seguir.

Use a operação da API do plano de dados HTTP StartCommandExecution para iniciar uma execução de comando. A solicitação e a resposta da API são correlacionadas pelo ID de execução do comando. Depois que o dispositivo concluir a execução do comando, ele poderá relatar o status e o resultado da execução para a nuvem publicando uma mensagem no tópico de resposta dos comandos. Para um código de resposta personalizado, os códigos da aplicação que você tem podem processar a mensagem de resposta e publicar o resultado na AWS IoT.

Se seus dispositivos assinaram o tópico de solicitação de comandos, a API StartCommandExecution publicará a mensagem de carga útil no tópico. A carga útil pode usar qualquer formato de sua escolha. Para obter mais informações, consulte Carga útil do comando.

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

Se o formato da carga útil não for JSON nem CBOR, o formato do tópico de solicitação de comandos será mostrado a seguir.

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

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 StartCommandExecution.

Neste exemplo, substitua:

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Acessar o endpoint do plano de dados específico da conta

Antes de executar o comando da API, você deve acessar o URL do endpoint específico da conta. Se você estiver usando endpoints de pilha dupla (IPv4 e IPv6), use o iot:Data-ATS. O endpoint iot:Jobs é somente para IPv4. Por exemplo, se você executar este comando:

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

Ele exibirá o URL do endpoint específico da conta, conforme mostrado no exemplo de resposta abaixo.

{
    "endpointAddress": "<account-specific-prefix>-ats.iot.<region>.api.com"
}

Iniciar um exemplo de execução de comando (AWS CLI)

O exemplo a seguir mostra como começar a executar um comando usando start-command-execution da AWS CLI.

Neste exemplo, substitua:

aws iot-jobs-data start-command-execution \ 
    --command-arn <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --execution-timeout-seconds 900

A execução desse comando exibe um ID de execução. Você pode usar esse ID para consultar o status, os detalhes e o histórico da execução do comando.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

Antes de usar essa operação da API, verifique se sua política do IAM autoriza seu dispositivo a realizar essas ações. Veja a seguir um exemplo de política que autoriza seu dispositivo a realizar a ação. Para ver exemplos adicionais de políticas do IAM que permitem ao usuário realizar a ação UpdateCommandExecution, consulte Exemplos de política para conectar e publicar.

Neste exemplo, substitua:

Exemplo de política do IAM para o ID do cliente do MQTT

O código a seguir mostra um exemplo de política de dispositivos ao usar o ID do cliente do MQTT.

Exemplo de política do IAM para uma coisa da IoT

O código a seguir mostra um exemplo de política de dispositivos ao usar uma coisa da AWS IoT.

Depois que a execução do comando é recebida no tópico da solicitação, o dispositivo processa o comando. Depois, ele usa a API UpdateCommandExecution para atualizar o status e o resultado da execução do comando para o tópico de resposta a seguir.

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

Neste exemplo, <DeviceID> é o identificador exclusivo do dispositivo de destino, e <execution-id> é o identificador da execução do comando no dispositivo de destino. O <PayloadFormat> pode ser JSON ou CBOR.

$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

O dispositivo relatou atualizações no status de execução

Seus dispositivos podem usar a API para relatar qualquer uma das atualizações de status a seguir na execução do comando. Para acessar mais informações sobre esses status, consulte Status de execução do comando.

Para acessar mais informações sobre o status TIMED_OUT, consulte Valor do tempo limite e status de execução TIMED_OUT.

Considerações ao usar a API UpdateCommandExecution

Veja a seguir algumas considerações importantes ao usar a API UpdateCommandExecution.

Exemplo de API UpdateCommandExecution

O código a seguir mostra um exemplo de como seu dispositivo pode usar a API UpdateCommandExecution para relatar o status da execução, o campo statusReason para fornecer informações adicionais sobre o status e o campo de resultados para fornecer informações sobre o resultado da execução, como a porcentagem da bateria do carro, nesse caso.

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}

Você pode recuperar uma execução de comando do console usando qualquer um dos métodos a seguir.

Use a operação da API HTTP do ambiente de gerenciamento GetCommandExecution do AWS IoT Core para recuperar informações sobre uma execução de comando. Você já deve ter executado esse comando usando a operação da API StartCommandExecution.

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 GetCommandExecution.

Neste exemplo, substitua:

{
  "Effect": "Allow",
  "Action": [
      "iot:GetCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Exemplo de como recuperar uma execução de comando

O exemplo a seguir mostra como recuperar informações sobre um comando executado usando start-command-execution da AWS CLI. O exemplo a seguir mostra como recuperar informações sobre um comando executado para desativar o modo do volante.

Neste exemplo, substitua:

aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <target-arn> \
    --include-result

A execução desse comando gera uma resposta que contém informações sobre o ARN da execução do comando, o status da execução e a hora em que ela foi iniciada e concluída. Ela também fornece um objeto statusReason que contém informações adicionais sobre o status. Para acessar mais informações sobre os diferentes status e os respectivos motivos, consulte Status de execução do comando.

O código a seguir mostra um exemplo de resposta da solicitação da API.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/myRegisteredThing",
    "status": "SUCCEEDED",
    "statusReason": {
        "reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED",
        "reasonDescription": "SUCCESS"
    },
    "result": {
        "sn": { "s": "ABC-001" },
        "digital": { "b": true }        
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "completedAt": "2024-03-23T00:50:10.095000-07:00"    
}

Você pode recuperar todas as execuções de comandos do console usando qualquer um dos métodos a seguir.

Use a operação da API HTTP do ambiente de gerenciamento ListCommandExecutionsAWS IoT Core para listar todas as execuções de comandos em sua conta.

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 ListCommandExecutions.

Neste exemplo, substitua:

{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

Exemplo de como listar as execuções de comandos

O exemplo a seguir mostra como listar as execuções de comandos na Conta da AWS.

Ao executar o comando, você deve especificar se deseja filtrar a lista para exibir somente execuções de comandos que foram criadas para um dispositivo específico usando o targetArn ou execuções para um comando especificado usando o commandArn.

Neste exemplo, substitua:

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<after>}' \
--sort-order "ASCENDING"

A execução desse comando gera uma resposta com uma lista das execuções de comando criadas, a hora em que elas começaram a ser realizadas e quando foram concluídas. Ela também fornece informações de status e o objeto statusReason que contém informações adicionais sobre o status.

{
    "commandExecutions": [
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "TIMED_OUT",
            "createdAt": "2024-11-24T14:39:25.791000-08:00",
            "startedAt": "2024-11-24T14:39:25.791000-08:00"
        },
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "IN_PROGRESS",
            "createdAt": "2024-11-24T14:05:36.021000-08:00",
            "startedAt": "2024-11-24T14:05:36.021000-08:00"
        }
    ]
}

Para acessar mais informações sobre os diferentes status e os respectivos motivos, consulte Status de execução do comando.

Antes de usar essa operação da API, verifique se sua política do IAM autoriza seu dispositivo a realizar essas ações. Veja a seguir um exemplo de política que autoriza seu dispositivo a realizar a ação.

Neste exemplo, substitua:

{
  "Effect": "Allow",
  "Action": [
      "iot:DeleteCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

O exemplo a seguir mostra como excluir um comando usando delete-command da AWS CLI. Dependendo da sua aplicação, substitua <execution-id> pelo identificador da execução do comando que você está excluindo e <target-arn> pelo ARN do dispositivo de destino.

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

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