Iniciar e monitorar execuções de comando

Especifique o dispositivo de destino para receber e executar o Comando. Use um nome Thing para dispositivos registrados ou uma ID de cliente para dispositivos não registrados. Depois de receber a carga, o dispositivo executa o comando e executa as ações especificadas.

AWS IoT coisa

Os dispositivos de destino podem ser coisas registradas no AWS IoT registro. As coisas simplificam a pesquisa e o gerenciamento de dispositivos.

Registre dispositivos como Coisas na página do dispositivo Connect ou usando CreateThing. Encontre coisas existentes no Thing Hub ou usando DescribeThing. Consulte Gerenciando coisas com o registro para obter detalhes do registro.

ID de cliente

Para dispositivos não registrados, use o ID do cliente.

O ID do cliente é um identificador exclusivo que você atribui aos dispositivos. Definido no protocolo MQTT, ele contém caracteres alfanuméricos, sublinhados ou traços. Cada dispositivo conectado AWS IoT precisa de um ID de cliente exclusivo.

A ID do cliente é a ID do cliente MQTT que os dispositivos usam quando se conectam a. AWS IoT Core AWS IoT usa essa ID para identificar dispositivos e gerenciar conexões e assinaturas.

O tempo limite especifica a duração (em segundos) para que os dispositivos forneçam resultados de execução.

Depois de criar uma execução, um cronômetro é iniciado. Se o dispositivo ficar off-line ou não reportar os resultados dentro do tempo limite, a Execução expirará com o statusTIMED_OUT.

Padrão: 10 segundos. Máximo: 12 horas.

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

Tanto a nuvem quanto o dispositivo podem relatar o tempo limite.

Depois de enviar o Comando, um cronômetro é iniciado. Se nenhuma resposta do dispositivo chegar dentro do tempo limite, a nuvem definirá o status de execução como TIMED_OUT com o código do $NO_RESPONSE_FROM_DEVICE motivo.

Isso ocorre quando:

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 substitui o status de qualquer um dos status do terminal:SUCCEEDED,, FAILED ou. REJECTED A execução do comando então se torna terminal e não aceita mais atualizações.

Seu dispositivo também pode atualizar um TIMED_OUT status 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 emTIMED_OUT, mas o statusReason objeto é atualizado com base nas informações relatadas pelo dispositivo. A execução do comando então se torna terminal e nenhuma atualização adicional é aceita.

Usar sessões persistentes do MQTT

Você pode configurar sessões persistentes do MQTT para usar com o recurso de AWS IoT Device Management comandos. 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 para um valor que exceda essa duração, as execuções de comandos executadas por mais de 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 o comando no console, acesse a página do Command Hub do AWS IoT console 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 de aplicativo que você possui podem processar a mensagem de resposta e publicar o resultado em 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 não for JSON ou CBOR, o seguinte mostra o formato do tópico de solicitação de comandos.

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

Para ver uma lista das chaves de condição suportadasStartCommandExecution, consulte Chaves de condição AWS IoT no Guia do usuário do IAM.

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 (IPv4e IPv6), use o. iot:Data-ATS O iot:Jobs endpoint é IPv4 apenas para. Por exemplo, se você executar este comando:

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

Ele retorna 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 o start-command-execution AWS CLI comando.

Neste exemplo, substitua:

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 exemplos adicionais de políticas do IAM que permitem que o usuário execute a ação do UpdateCommandExecution MQTT, consulteExemplos 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. Eles <PayloadFormat> podem 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 plano de GetCommandExecution AWS IoT Core controle para recuperar informações sobre a execução de um 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 que foi executado usando o start-command-execution AWS CLI comando. 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:us-east-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:us-east-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 plano de ListCommandExecutions AWS IoT Core controle 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 o delete-command AWS CLI comando. 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.