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á. # Indexação de dados de localização Você pode usar a [indexação de frotas da AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/iot-indexing.html) para indexar os últimos dados de localização enviados dos seus dispositivos e pesquisar dispositivos usando consultas geográficas. Esse atributo resolve casos de uso de monitoramento e gerenciamento de dispositivos, como rastreamento de localização e pesquisa de proximidade. A indexação de localização funciona de maneira semelhante a outros recursos de indexação de frotas e com configurações adicionais para especificar na [indexação de objetos](managing-fleet-index.md). Os casos de uso comuns incluem: pesquisar e agregar dispositivos localizados dentro dos limites geográficos desejados, obter informações específicas da localização usando termos de consulta relacionados aos metadados e ao estado do dispositivo de fontes de dados indexadas, fornecer uma visão granular, como a filtragem de resultados para uma área geográfica específica, reduzir os atrasos de renderização nos mapas de monitoramento da frota e rastrear a localização do último dispositivo relatado, identificar dispositivos que estão fora dos limites desejados e gerar alarmes usando [métricas de frota.](iot-fleet-metrics.md) Para começar com indexação de localização e geoconsultas, consulte [Tutorial de inicialização](location-indexing-tutorial.md). ## Formatos de dados compatíveis AWS IoT a indexação de frotas suporta os seguintes formatos de dados de localização: 1. **Representação de texto bem conhecida de sistemas de referência de coordenadas** Uma string que segue o formato [Informações geográficas: representação de texto bem conhecida de sistemas de referência de coordenadas](https://docs.ogc.org/is/12-063r5/12-063r5.html). Um exemplo pode ser `"POINT(long lat)"`. 1. **Uma string que representa as coordenadas** Uma string com o formato `"latitude, longitude"` ou `"longitude, latitude"`. Se você usar `"longitude, latitude"`, também deverá especificar `order` em `geoLocations`. Um exemplo pode ser `"41.12,-71.34"`. 1. **Um objeto com chaves lat(latitude), lon(longitude)** Esse formato se aplica à sombra clássica e à sombra nomeada. Chaves compatíveis: `lat`, `latitude`, `lon`, `long`, `longitude`. Um exemplo pode ser `{"lat": 41.12, "lon": -71.34}`. 1. **Uma matriz que representa as coordenadas** Uma matriz com o formato `[lat,lon]` ou`[lon,lat]`. Se você usar o formato `[lon,lat]`, que é o mesmo das coordenadas em [GeoJSON](https://geojson.org/) (aplicável à sombra clássica e à sombra nomeada), você também deve especificar `order` em `geoLocations`. Um exemplo pode ser: ``` { "location": { "coordinates": [ **Longitude**, **Latitude** ], "type": "Point", "properties": { "country": "United States", "city": "New York", "postalCode": "*****", "horizontalAccuracy": 20, "horizontalConfidenceLevel": 0.67, "state": "New York", "timestamp": "2023-01-04T20:59:13.024Z" } } } ``` ## Como indexar dados de localização As etapas a seguir mostram como atualizar a configuração de indexação dos dados de localização e usar consultas geográficas para pesquisar dispositivos. 1. **Saiba onde seus dados de localização estão armazenados** Atualmente, a indexação de frotas oferece suporte à indexação de dados de localização armazenados em sombras clássicas ou sombras nomeadas. 1. **Usar formatos de dados de localização compatíveis** Verifique se o formato dos dados de localização segue um dos [formatos de dados compatíveis](#location-indexing-format). 1. **Atualizar configuração de indexação** Se necessário, habilite a configuração de indexação de itens (registro). Você também deve ativar a indexação na sombra clássica ou na sombra nomeada que contenha seus dados de localização. Ao atualizar sua indexação de itens, você deve incluir seus dados de localização na configuração de indexação. 1. **Criar e executar consultas geográficas** Dependendo dos seus casos de uso, crie geoconsultas e execute-as para pesquisar dispositivos. A consulta geográfica que você compõe deve seguir a [Sintaxe da consulta](https://docs.aws.amazon.com//iot/latest/developerguide/query-syntax.html). É possível encontrar alguns exemplos em [Exemplo de consultas geográficas](#location-indexing-geoqueries). ## Atualizar a configuração da indexação de objeto Para indexar dados de localização, atualize a configuração de indexação e inclua seus dados de localização. Dependendo de onde seus dados de localização estão, siga as etapas para atualizar sua configuração de indexação: ### Dados de localização armazenados em sombras clássicas Se seus dados de localização estiverem armazenados em uma sombra clássica, você deverá definir `thingIndexingMode` como `REGISTRY_AND_SHADOW` e especificar seus dados de localização nos campos `geoLocations` (`name` e `order`) em [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html). No exemplo de configuração de indexação a seguir, você especifica o caminho dos dados de localização `shadow.reported.coordinates` como `name` e `LonLat` como `order`. ``` { "thingIndexingMode": "REGISTRY_AND_SHADOW", "filter": { "geoLocations": [ { "name": "shadow.reported.coordinates", "order": "LonLat" } ] } } ``` + `thingIndexingMode` O modo de indexação controla se o Registro ou a sombra é indexado. Quando `thingIndexingMode` é definido como `OFF`, a indexação de itens é desativada. Para indexar dados de localização armazenados em uma sombra clássica, você deve definir `thingIndexingMode` como `REGISTRY_AND_SHADOW`. Para obter mais informações, consulte [Modos de indexação de objetos](managing-index.md#index-mode). + `filter` O filtro de indexação fornece seleções adicionais para sombras nomeadas e dados de localização geográfica. Para obter mais informações, consulte [Filtro de indexação](managing-index.md#thing-indexing-filter). + `geoLocations` A lista de destinos de localização geográfica que você seleciona para indexar. O número máximo padrão de destinos de localização geográfica para indexação é `1`. Para aumentar o limite, consulte [Cotas de AWS IoT Device Management](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#fleet-indexing-limits). + `name` O nome do campo de destino de localização geográfica. Um exemplo de valor de `name` pode ser o caminho dos dados de localização de sua sombra: `shadow.reported.coordinates`. + `order` A ordem do campo de destino de localização geográfica. Valores válidos: `LatLon` e `LonLat`. `LatLon` significa latitude e longitude. `LonLat` significa longitude e latitude. Esse campo é opcional. O valor padrão é `LatLon`. ### Dados de localização armazenados em sombras nomeadas Se seus dados de localização estiverem armazenados em uma sombra nomeada, defina `namedShadowIndexingMode` como `ON`, adicione seus nomes de sombra nomeados ao campo `namedShadowNames` em [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html) e especifique seu caminho de dados de localização no campo `geoLocations` em [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html). No exemplo de configuração de indexação a seguir, você especifica o caminho dos dados de localização `shadow.name.namedShadow1.reported.coordinates` como `name` e `LonLat` como `order`. ``` { "thingIndexingMode": "REGISTRY", "namedShadowIndexingMode": "ON", "filter": { "namedShadowNames": [ "namedShadow1" ], "geoLocations": [ { "name": "shadow.name.namedShadow1.reported.coordinates", "order": "LonLat" } ] } } ``` + `thingIndexingMode` O modo de indexação controla se o Registro ou a sombra é indexado. Quando `thingIndexingMode` é definido como `OFF`, a indexação de itens é desativada. Para indexar dados de localização armazenados em uma sombra nomeada, você deve definir `thingIndexingMode` como `REGISTRY` (ou `REGISTRY_AND_SHADOW`). Para obter mais informações, consulte [Modos de indexação de objetos](managing-index.md#index-mode). + `filter` O filtro de indexação fornece seleções adicionais para sombras nomeadas e dados de localização geográfica. Para obter mais informações, consulte [Filtro de indexação](managing-index.md#thing-indexing-filter). + `geoLocations` A lista de destinos de localização geográfica que você seleciona para indexar. O número máximo padrão de destinos de localização geográfica para indexação é `1`. Para aumentar o limite, consulte [Cotas de AWS IoT Device Management](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#fleet-indexing-limits). + `name` O nome do campo de destino de localização geográfica. Um exemplo de valor de `name` pode ser o caminho dos dados de localização de sua sombra: `shadow.name.namedShadow1.reported.coordinates`. + `order` A ordem do campo de destino de localização geográfica. Valores válidos: `LatLon` e `LonLat`. `LatLon` significa latitude e longitude. `LonLat` significa longitude e latitude. Esse campo é opcional. O valor padrão é `LatLon`. ## Exemplo de consultas geográficas Depois de concluir a configuração de indexação dos dados de localização, execute consultas geográficas para pesquisar dispositivos. Você também pode combinar suas consultas geográficas com outras cadeias de caracteres de consulta. Para obter mais informações, consulte [Sintaxe de consulta](query-syntax.md) e [Exemplo de consultas de objetos](example-queries.md). **Consulta de exemplo 1** Este exemplo pressupõe que os dados de localização estão armazenados em uma sombra nomeada `gps-tracker`. A saída desse comando é a lista de dispositivos que estão dentro da distância radial de 15,5 km do ponto central com coordenadas (47,6204,-122,3491). ``` aws iot search-index --query-string \ "shadow.name.gps-tracker.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km" ``` **Consulta de exemplo 2** Este exemplo pressupõe que os dados de localização estão armazenados em uma sombra clássica. A saída desse comando é a lista de dispositivos que estão dentro da distância radial de 15,5 km do ponto central com coordenadas (47,6204,-122,3491). ``` aws iot search-index --query-string \ "shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km" ``` **Consulta de exemplo 3** Este exemplo pressupõe que os dados de localização estão armazenados em uma sombra clássica. A saída desse comando é a lista de dispositivos que não estão conectados e estão fora da distância radial de 15,5 km do ponto central com coordenadas (47,6204,-122,3491). ``` aws iot search-index --query-string \ "connectivity.connected:false AND (NOT shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km)" ``` # Tutorial de inicialização Este tutorial demonstra como usar a [indexação de frotas](iot-indexing.md) para [indexar seus dados de localização](location-indexing-geoquery.md). Para simplificar, você cria um objeto para representar seu dispositivo e armazena os dados de localização em uma sombra nomeada, atualiza a configuração de indexação do objeto para indexação de localização e executa exemplos de consultas geográficas para pesquisar dispositivos dentro de um limite radial. Este tutorial leva cerca de 15 minutos para ser concluído. **Topics** + [Pré-requisitos](#location-indexing-tutorial-prerequisites) + [Criar objeto e sombra](#location-indexing-create-resources) + [Atualizar a configuração da indexação de objeto](#location-indexing-update-configuration) + [Executar consulta geográfica](#location-indexing-run-geoquery) ## Pré-requisitos + Instale a versão mais recente da [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html). + Familiarize-se com [Indexação de localização e consultas geográficas](https://docs.aws.amazon.com/iot/latest/developerguide/location-indexing-geoquery.html), [Gerenciar indexação de objeto](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) e [Sintaxe de consulta](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html). ## Criar objeto e sombra Você cria um objeto para representar seu dispositivo e uma sombra nomeada para armazenar seus dados de localização (coordenadas 47,61564,-122,33584). 1. Execute o comando apresentado a seguir para criar o que representa a bicicleta com o nome Bike-1. *Para obter mais informações sobre como criar algo usando AWS CLI, consulte [create-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/create-thing.html) from Reference. *AWS CLI** ``` aws iot create-thing --thing-name "Bike-1" \ --attribute-payload '{"attributes": {"model":"OEM-2302-12", "battery":"35", "acqDate":"06/09/23"}}' ``` A saída desse comando pode ser semelhante à seguinte: ``` { "thingName": "Bike-1", "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/Bike-1", "thingId": "df9cf01d-b0c8-48fe-a2e2-e16cff6b23df" } ``` 1. Execute o comando a seguir para criar uma sombra nomeada para armazenar os dados de localização da Bike-1 (coordenadas 47.61564, -122.33584). Para obter mais informações sobre como criar uma sombra nomeada usando AWS CLI, consulte [update-thing-shadow](https://docs.aws.amazon.com//cli/latest/reference/iot-data/update-thing-shadow.html)em *AWS CLI**Referência*. ``` aws iot-data update-thing-shadow \ --thing-name Bike-1 \ --shadow-name Bike1-shadow \ --cli-binary-format raw-in-base64-out \ --payload '{"state":{"reported":{"coordinates":{"lat": 47.6153, "lon": -122.3333}}}}' \ "output.txt" \ ``` Esse comando não retorna nenhuma saída. Para ver a sombra nomeada que você criou, você pode executar o comando [list-named-shadows-for-thing](https://docs.aws.amazon.com//cli/latest/reference/iot-data/list-named-shadows-for-thing.html) CLI. ``` aws iot-data list-named-shadows-for-thing --thing-name Bike-1 ``` A saída desse comando pode ser semelhante à seguinte: ``` { "results": [ "Bike1-shadow" ], "timestamp": 1699574309 } ``` ## Atualizar a configuração da indexação de objeto Para indexar dados de localização, atualize sua configuração de indexação para incluir os dados de localização. Como seus dados de localização estão armazenados em uma sombra nomeada neste tutorial, defina `thingIndexingMode` como `REGISTRY` (com um requisito mínimo), defina `namedShadowIndexingMode` como `ON` e adicione seus dados de localização à configuração. Neste exemplo, você deve adicionar o nome da sombra nomeada e o caminho dos dados de localização da sombra para `filter`. 1. Execute o comando para atualizar sua configuração de indexação para indexação de localização. ``` aws iot update-indexing-configuration --cli-input-json '{ "thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY", "thingConnectivityIndexingMode": "OFF", "deviceDefenderIndexingMode": "OFF", "namedShadowIndexingMode": "ON", "filter": { "namedShadowNames": ["Bike1-shadow"], "geoLocations":[{ "name":"shadow.name.Bike1-shadow.reported.coordinates" }] }, "customFields": [ { "name":"attributes.battery", "type":"Number"}] } }' ``` O comando não produz saída. Talvez seja necessário aguardar um instante até a atualização ser concluída. Para verificar o status, execute o comando da CLI [describe-index](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-index.html). Se você vê `indexStatus` mostrar: `ACTIVE`, sua atualização de indexação de objeto está concluída. 1. Execute o comando para verificar a configuração de indexação. Esta etapa é opcional. ``` aws iot get-indexing-configuration ``` A saída poderá ser parecida com o seguinte: ``` { "thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY", "thingConnectivityIndexingMode": "OFF", "deviceDefenderIndexingMode": "OFF", "namedShadowIndexingMode": "ON", "managedFields": [ { "name": "shadow.name.*.hasDelta", "type": "Boolean" }, { "name": "registry.version", "type": "Number" }, { "name": "registry.thingTypeName", "type": "String" }, { "name": "registry.thingGroupNames", "type": "String" }, { "name": "shadow.name.*.version", "type": "Number" }, { "name": "thingName", "type": "String" }, { "name": "thingId", "type": "String" } ], "customFields": [ { "name": "attributes.battery", "type": "Number" } ], "filter": { "namedShadowNames": [ "Bike1-shadow" ], "geoLocations": [ { "name": "shadow.name.Bike1-shadow.reported.coordinates", "order": "LatLon" } ] } }, "thingGroupIndexingConfiguration": { "thingGroupIndexingMode": "OFF" } } ``` ## Executar consulta geográfica Agora você atualizou sua configuração de indexação para incluir os dados de localização. Tente criar algumas consultas geográficas e executá-las para ver se você consegue obter os resultados de pesquisa desejados. Uma consulta geográfica deve seguir a [Sintaxe da consulta](query-syntax.md). Você pode encontrar alguns exemplos úteis de geoconsultas em [Exemplo de consultas geográficas](location-indexing-geoquery.md#location-indexing-geoqueries). No comando de exemplo a seguir, você usa a consulta geográfica `shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km` para pesquisar dispositivos que estão dentro da distância radial de 15,5 km do ponto central com coordenadas (47,6204, -122,3491). ``` aws iot search-index --query-string "shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km" ``` Como você tem um dispositivo localizado nas coordenadas “lat”: 47.6153, “lon”: -122.3333, que fica a uma distância de 15,5 km do ponto central, você deve conseguir ver esse dispositivo (Bike-1) na saída. A saída poderá ser parecida com o seguinte: ``` { "things": [ { "thingName": "Bike-1", "thingId": "df9cf01d-b0c8-48fe-a2e2-e16cff6b23df", "attributes": { "acqDate": "06/09/23", "battery": "35", "model": "OEM-2302-12" }, "shadow": "{\"reported\":{\"coordinates\":{\"lat\":47.6153,\"lon\":-122.3333}},\"metadata\":{\"reported\":{\"coordinates\":{\"lat\":{\"timestamp\":1699572906},\"lon\":{\"timestamp\":1699572906}}}},\"hasDelta\":false,\"version\":1}" } ] } ``` Para obter mais informações, consulte [Indexação de dados de localização](location-indexing-geoquery.md).