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á. # Consultas do status de conectividade do dispositivo AWS IoT A indexação de frota oferece suporte à consulta de conectividade de dispositivos individuais, permitindo que você recupere com eficiência o status da conectividade e os metadados relacionados para dispositivos específicos. Esse recurso complementa os recursos existentes de indexação e consulta em toda a frota. ## Como funciona O suporte à consulta de conectividade de dispositivos pode ser usado para recuperação otimizada do status de conectividade de um único dispositivo. Essa API fornece acesso de baixa latência e alto throughput às informações mais recentes de conectividade específicas do dispositivo. Depois de habilitar a indexação de conectividade, você terá acesso a essa API de consulta, que será cobrada como consultas padrão. Para acessar mais informações, consulte [Preços do AWS IoT Device Management](https://aws.amazon.com/iot-device-management/pricing/#:~:text=Search%20queries%20(per%2010%2C000%20queries)). ## Recursos Com o suporte à consulta de conectividade de dispositivos, você pode: 1. Consultar o estado atual de conectividade (conectado ou desconectado) de determinado dispositivo usando o respectivo `thingName`. 1. Recuperar metadados adicionais de conectividade, incluindo: 1. Motivo da desconexão 1. Carimbos de data/hora do evento de conexão ou desconexão mais recente. 1. Informações da sessão, incluindo a duração do keep-alive 1. Informações da sessão no nível do soquete, incluindo endereço IP, porta e ID do VPC endpoint. Essas informações estão disponíveis somente quando as seguintes condições são atendidas: 1. Você ativa essa opção nas configurações de indexação de frotas. 1. Você tem a permissão correspondente na política do IAM ao invocar a API. **nota** A indexação da frota indexa o status de conectividade de um dispositivo cuja conexão `clientId` é a mesma de `thingName` de um objeto registrada no [Registro](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html). ## Benefícios 1. **Baixa latência:** reflete o estado mais recente de conectividade do dispositivo e oferece baixa latência para refletir as alterações do estado de conexão do IoT Core. O IoT Core determina que um dispositivo está desconectado assim que recebe uma solicitação de desconexão dele ou no caso de um dispositivo se desconectar sem enviar uma solicitação de desconexão. O IoT Core aguardará 1,5x do tempo de keep-alive configurado antes de decidir desconectar o cliente. A API de status da conectividade exibirá essas alterações normalmente em menos de um segundo após o IoT Core determinar a mudança de estado conectado de um dispositivo. 1. **Alto throughput:** aceita 350 transações por segundo (TPS) por padrão e pode ser ajustável para um valor maior mediante solicitação. 1. **Retenção de dados:** armazena dados de eventos indefinidamente quando o ConnectivityIndexing modo Fleet Indexing (FI) está ativado e o item não é excluído. Se você desabilitar a indexação de conectividade, os registros não serão retidos. **nota** Se a indexação do status de conectividade tiver sido habilitada antes do lançamento dessa API, o Fleet Indexing começará a rastrear as alterações do status de conectividade após o lançamento da API e exibirá o status atualizado com base nessas alterações. ## Pré-requisitos Para usar o suporte à consulta de conectividade do dispositivo: 1. [Configurar uma AWS conta](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html) 1. Integre e registre dispositivos AWS IoT Core na sua região preferida 1. [Habilite a indexação de frotas](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) com indexação de conectividade. Opcional: Opt-in para receber informações sobre o nível do soquete ativando a `includeSocketInformation` opção. **nota** Nenhuma configuração adicional é necessária se você já tiver a indexação de conectividade ativada. Para receber instruções detalhadas de configuração, consulte o [Guia do desenvolvedor da AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html). ## Exemplo **Comando CLI:** ``` aws iot get-thing-connectivity-data --include-socket-information --thing-name myThingName ``` **Resposta:** ``` { "thingName": "myThingName", "connected": true, "timestamp": "2024-12-19T10:00:00.000000-08:00", "disconnectReason": "NONE", "sourceIp": "192.0.2.1", "sourcePort": 52123, "targetIp": "198.51.100.1", "targetPort": 8883, "vpcEndpointId": "vpce-1234567890abcdef0", "keepAliveDuration": 60, "cleanSession": true, "clientId": "myThingName" } ``` **Parâmetros da API** + `thingName`: O nome do dispositivo registrado no AWS IoT Registro. Isso deve corresponder ao `clientId` usado para se conectar ao AWS IoT Core. + `includeSocketInformation`: o `includeSocketInformation` parâmetro controla se as informações de rede no nível do soquete estão incluídas na resposta da API. Quando definido como verdadeiro, a resposta inclui os seguintes campos:`sourceIp, sourcePort, targetIp, targetPort, vpcEndpointId`. Quando não `includeSocketInformation` é especificado ou definido como falso, esses campos de soquete são excluídos da resposta. Para impedir que usuários específicos do IAM acessem as informações do soquete, você precisará especificar isso na política do IAM definindo a chave de `includeSocketInformation` condição como falsa. **Campos de resposta** + `thingName`: O nome do dispositivo registrado no AWS IoT Registro. Isso deve corresponder ao `clientId` usado para se conectar ao AWS IoT Core. + `connected`: o valor booliano verdadeiro indicando que esse dispositivo está conectado no momento. + `disconnectReason`: motivo da desconexão. Será `NONE` para um dispositivo conectado e `UNKNOWN` para um dispositivo que nunca foi conectado. Para um dispositivo desconectado, isso indicará se a desconexão foi iniciada pelo cliente, iniciada pelo servidor, devido a authentication/authorization problemas ou devido a problemas de rede. Para obter os códigos de motivo da desconexão, consulte [LifeCycleEvents ](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html) + `timestamp`: o timestamp que representa o evento de conexão ou desconexão mais recente do dispositivo. + `clientId`: O ClientID do cliente MQTT. + `keepAliveDuration`: o intervalo de manutenção de atividade em segundos que o cliente especificou ao estabelecer a conexão. Isso determina a frequência com que o cliente envia mensagens de manutenção de atividade para manter a conexão. + `cleanSession`: indica se o cliente está usando uma sessão limpa. + `sessionExpiry`: a configuração persistente de expiração da sessão que o cliente especificou ao estabelecer a conexão. Isso determina por quanto tempo uma sessão permanecerá ativa após a desconexão do cliente. + `sourceIp`: o endereço IP do cliente que iniciou a conexão. Retornado somente se `includeSocketInformation` estiver definido como verdadeiro e o usuário estiver autorizado a recuperar essas informações. + `sourcePort`: o número da porta usada pelo cliente para a conexão. Retornado somente se `includeSocketInformation` estiver definido como verdadeiro e o usuário estiver autorizado a recuperar essas informações. + `targetIp`: o endereço IP para o qual a solicitação de conexão foi feita. Retornado somente se `includeSocketInformation` estiver definido como verdadeiro e o usuário estiver autorizado a recuperar essas informações + `targetPort`: o número da porta do endpoint AWS IoT Core ao qual o cliente se conectou. Retornado somente se `includeSocketInformation` estiver definido como verdadeiro e o usuário estiver autorizado a recuperar essas informações. + `vpcEndpointId`: o ID do VPC endpoint pelo qual o cliente se conectou, se aplicável. Retornado somente se `includeSocketInformation` estiver definido como verdadeiro e o usuário estiver autorizado a recuperar essas informações. **Permissões obrigatórias** Para usar a GetThingConnectivityData API, você precisa da seguinte permissão do IAM `iot:GetThingConnectivityData` Você pode definir o escopo dessa permissão para coisas específicas usando políticas baseadas em recursos. Use a `iot:IncludeSocketInformation` condição para implementar o controle de acesso granular nas informações do soquete. O exemplo de política abaixo demonstra um cenário em que você nega ao usuário o acesso às informações do soquete. Observe que esse exemplo funciona quando é a única política que concede acesso à ação GetThingConnectivityData. **Exemplos de políticas de autorização** ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:GetThingConnectivityData" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/*"], "Condition": { "Bool": { "iot:IncludeSocketInformation": "false" } } }] } ```