Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Indexación de datos de ubicación
Puede usar la [indexación de flotas de AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/iot-indexing.html) para indexar los últimos datos de ubicación enviados por sus dispositivos y buscar dispositivos realizando consultas geográficas. Esta característica resuelve los casos de uso de la supervisión y la administración de dispositivos, como el seguimiento de la ubicación y la búsqueda de proximidad. La indexación de ubicaciones funciona de manera similar a otras características de indexación de flotas y con configuraciones adicionales que puede especificar en la [indexación de objetos](managing-fleet-index.md).
Los casos de uso más comunes son: buscar y añadir dispositivos ubicados dentro de los límites geográficos deseados, obtener información específica de la ubicación mediante términos de consulta relacionados con los metadatos y el estado del dispositivo a partir de orígenes de datos indexados, proporcionar una vista granular, como filtrar los resultados según un área geográfica específica para reducir los retrasos de representación en los mapas de supervisión de la flota y rastrear la ubicación del último dispositivo notificado, e identificar los dispositivos que están fuera de los límites deseados y generar alarmas utilizando las [métricas de flota](iot-fleet-metrics.md). Para empezar a utilizar la indexación de ubicaciones y las geoconsultas, consulte [Tutorial introductorio](location-indexing-tutorial.md).
## Formatos de datos admitidos
AWS IoT La indexación de flotas admite los siguientes formatos de datos de ubicación:
1.
**Una representación de texto muy conocida de sistemas de coordenadas de referencia**
Es una cadena que sigue el formato [Geographic information - Well-known text representation of coordinate reference systems](https://docs.ogc.org/is/12-063r5/12-063r5.html). Por ejemplo, `"POINT(long lat)"`.
1.
**Una cadena que representa las coordenadas**
Es una cadena con el formato `"latitude, longitude"` o `"longitude, latitude"`. Si usa `"longitude, latitude"`, también debe especificar `order` en `geoLocations`. Por ejemplo, `"41.12,-71.34"`.
1.
**Un objeto con claves de lat (latitud) y lon (longitud)**
Este formato se aplica tanto a la sombra clásica como a la sombra con nombre. Claves admitidas: `lat`, `latitude`, `lon`, `long` y `longitude`. Por ejemplo, `{"lat": 41.12, "lon": -71.34}`.
1.
**Una matriz que representa las coordenadas**
Una matriz con el formato `[lat,lon]` o `[lon,lat]`. Si utiliza el formato `[lon,lat]`, que es el mismo que el de las coordenadas de [GeoJSON](https://geojson.org/) (aplicable a la sombra clásica y a la sombra con nombre), también debe especificar `order` y `geoLocations`.
Por ejemplo:
```
{
"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"
}
}
}
```
## Cómo indexar los datos de ubicación
Los siguientes pasos muestran cómo actualizar la configuración de indexación de los datos de ubicación y cómo usar consultas geográficas para buscar dispositivos.
1.
**Saber dónde se almacenan los datos de ubicación**
Actualmente, la indexación de flotas permite indexar los datos de ubicación almacenados en sombras clásicas o sombras con nombre.
1.
**Utilizar los formatos de datos de ubicación compatibles**
Asegúrese de que el formato de los datos de ubicación siga uno de los [formatos de datos compatibles](#location-indexing-format).
1.
**Actualizar la configuración de indexación**
Como mínimo, active la configuración de indexación de objetos (registro). También debe activar la indexación en la sombra clásica o en la sombra con nombre que contenga sus datos de ubicación. Al actualizar la indexación de objetos, debe incluir los datos de ubicación en la configuración de indexación.
1.
**Crear y ejecutar geoconsultas**
Según los casos de uso, cree geoconsultas y ejecútelas para buscar dispositivos. La geoconsulta que componga debe seguir la [sintaxis de consulta](https://docs.aws.amazon.com//iot/latest/developerguide/query-syntax.html). Encontrará algunos ejemplos en [Ejemplo de geoconsultas](#location-indexing-geoqueries).
## Actualización de la configuración de indexación de objetos
Para indexar los datos de ubicación, debe actualizar la configuración de indexación e incluir los datos de ubicación. Según dónde estén almacenados los datos de ubicación, siga los pasos para actualizar la configuración de indexación:
### Los datos de ubicación se almacenan en sombras clásicas
Si los datos de ubicación se almacenan en una sombra clásica, debe establecer el `thingIndexingMode` en `REGISTRY_AND_SHADOW` y especificar los datos de ubicación en los campos `geoLocations` (`name` y `order`) de [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html).
En el siguiente ejemplo de configuración de indexación de objetos, se especifica la ruta de los datos de ubicación `shadow.reported.coordinates` como `name` y `LonLat` como `order`.
```
{
"thingIndexingMode": "REGISTRY_AND_SHADOW",
"filter": {
"geoLocations": [
{
"name": "shadow.reported.coordinates",
"order": "LonLat"
}
]
}
}
```
+ `thingIndexingMode`
El modo de indexación controla si el registro o la sombra están indexados. Cuando `thingIndexingMode` se establece en `OFF`, la indexación de objetos está desactivada.
Para indexar los datos de ubicación almacenados en una sombra clásica, debe configurar el `thingIndexingMode` en `REGISTRY_AND_SHADOW`. Para obtener más información, consulte [Modos de indexación de objetos](managing-index.md#index-mode).
+ `filter`
El filtro de indexación proporciona selecciones adicionales para las sombras con nombre y los datos de geolocalización. Para obtener más información, consulte [Filtro de indexación](managing-index.md#thing-indexing-filter).
+ `geoLocations`
Es la lista de objetivos de geolocalización que selecciona para indexar. El número máximo predeterminado de objetivos de geolocalización para la indexación es `1`. Para solicitar un aumento de límite, consulte [AWS IoT Device Management Quotas](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#fleet-indexing-limits).
+ `name`
Es el nombre del campo objetivo de geolocalización. Un ejemplo de valor de `name` puede ser la ruta de los datos de ubicación de la sombra: `shadow.reported.coordinates`.
+ `order`
Es el orden del campo objetivo de geolocalización. Los valores válidos son `LatLon` y `LonLat`. `LatLon` significa latitud y longitud. `LonLat` significa longitud y latitud. Este campo es opcional. El valor predeterminado es `LatLon`.
### Los datos de ubicación se almacenan en sombras con nombre
Si los datos de ubicación se almacenan en una sombra con nombre, defina el `namedShadowIndexingMode` en `ON`, añada los nombres de la sombra con nombre al campo `namedShadowNames` en [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html) y especifique la ruta de los datos de ubicación en el campo `geoLocations` en [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html).
En el siguiente ejemplo de configuración de indexación de objetos, se especifica la ruta de los datos de ubicación `shadow.name.namedShadow1.reported.coordinates` como `name` y `LonLat` como `order`.
```
{
"thingIndexingMode": "REGISTRY",
"namedShadowIndexingMode": "ON",
"filter": {
"namedShadowNames": [
"namedShadow1"
],
"geoLocations": [
{
"name": "shadow.name.namedShadow1.reported.coordinates",
"order": "LonLat"
}
]
}
}
```
+ `thingIndexingMode`
El modo de indexación controla si el registro o la sombra están indexados. Cuando `thingIndexingMode` se establece en `OFF`, la indexación de objetos está desactivada.
Para indexar los datos de ubicación almacenados en una sombra con nombre, debe configurar el `thingIndexingMode` en `REGISTRY` (o `REGISTRY_AND_SHADOW`). Para obtener más información, consulte [Modos de indexación de objetos](managing-index.md#index-mode).
+ `filter`
El filtro de indexación proporciona selecciones adicionales para las sombras con nombre y los datos de geolocalización. Para obtener más información, consulte [Filtro de indexación](managing-index.md#thing-indexing-filter).
+ `geoLocations`
Es la lista de objetivos de geolocalización que selecciona para indexar. El número máximo predeterminado de objetivos de geolocalización para la indexación es `1`. Para solicitar un aumento de límite, consulte [AWS IoT Device Management Quotas](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#fleet-indexing-limits).
+ `name`
Es el nombre del campo objetivo de geolocalización. Un ejemplo de valor de `name` puede ser la ruta de los datos de ubicación de la sombra: `shadow.name.namedShadow1.reported.coordinates`.
+ `order`
Es el orden del campo objetivo de geolocalización. Los valores válidos son `LatLon` y `LonLat`. `LatLon` significa latitud y longitud. `LonLat` significa longitud y latitud. Este campo es opcional. El valor predeterminado es `LatLon`.
## Ejemplo de geoconsultas
Tras completar la configuración de indexación de los datos de ubicación, ejecute geoconsultas para buscar dispositivos. También puede combinar las geoconsultas con otras cadenas de consulta. Para obtener más información, consulte [Sintaxis de la consulta](query-syntax.md) y [Ejemplo de consultas de objetos](example-queries.md).
**Ejemplo de consulta 1**
En este ejemplo, se parte de la base de que los datos de ubicación se almacenan en una sombra con nombre `gps-tracker`. El resultado de este comando es la lista de dispositivos que se encuentran a una distancia radial de 15,5 km del punto central de las 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"
```
**Ejemplo de consulta 2**
En este ejemplo, se parte de la base de que los datos de ubicación se almacenan en una sombra clásica. El resultado de este comando es la lista de dispositivos que se encuentran a una distancia radial de 15,5 km del punto central de las coordenadas (47.6204, -122.3491).
```
aws iot search-index --query-string \
"shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
**Ejemplo de consulta 3**
En este ejemplo, se parte de la base de que los datos de ubicación se almacenan en una sombra clásica. El resultado de este comando es la lista de dispositivos que no están conectados y se encuentran fuera de la distancia radial de 15,5 km del punto central de las 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 introductorio
En este tutorial se explica cómo utilizar la [indexación de flotas](iot-indexing.md) para [indexar los datos de ubicación](location-indexing-geoquery.md). Para simplificar, puede crear un objeto que represente su dispositivo y almacenar los datos de ubicación en una sombra con nombre, actualizar la configuración de indexación de objetos para la indexación de ubicaciones y ejecutar geoconsultas de ejemplo para buscar dispositivos dentro de un límite radial.
Para completar este tutorial se necesitan aproximadamente 15 minutos.
**Topics**
+ [
## Requisitos previos
](#location-indexing-tutorial-prerequisites)
+ [
## Creación de objetos y sombras
](#location-indexing-create-resources)
+ [
## Actualización de la configuración de indexación de objetos
](#location-indexing-update-configuration)
+ [
## Ejecución de una geoconsulta
](#location-indexing-run-geoquery)
## Requisitos previos
+ Instale la versión más reciente de [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).
+ Familiarícese con la [indexación de ubicaciones y las geoconsultas](https://docs.aws.amazon.com/iot/latest/developerguide/location-indexing-geoquery.html), la [administración de la indexación de objetos](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) y la [sintaxis de las consultas](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html).
## Creación de objetos y sombras
Cree un objeto para representar su dispositivo y una sombra con nombre para almacenar sus datos de ubicación (coordenadas 47.61564, -122.33584).
1. Ejecute el siguiente comando para crear un objeto que represente la bicicleta llamada Bike-1. *Para obtener más información sobre cómo crear algo mediante el uso 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"}}'
```
El resultado de este comando puede tener un aspecto similar al siguiente.
```
{
"thingName": "Bike-1",
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/Bike-1",
"thingId": "df9cf01d-b0c8-48fe-a2e2-e16cff6b23df"
}
```
1. Ejecute el siguiente comando para crear una sombra con nombre para almacenar los datos de ubicación de Bike-1 (coordenadas 47.61564, -122.33584). *Para obtener más información sobre cómo crear una sombra con nombre utilizando AWS CLI, consulte [update-thing-shadow](https://docs.aws.amazon.com//cli/latest/reference/iot-data/update-thing-shadow.html)From *AWS CLI*Reference.*
```
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" \
```
Este comando no proporciona ninguna salida. Para ver la sombra con nombre que ha creado, puede ejecutar el comando CLI [list-named-shadows-for-thing](https://docs.aws.amazon.com//cli/latest/reference/iot-data/list-named-shadows-for-thing.html).
```
aws iot-data list-named-shadows-for-thing --thing-name Bike-1
```
El resultado de este comando puede tener un aspecto similar al siguiente.
```
{
"results": [
"Bike1-shadow"
],
"timestamp": 1699574309
}
```
## Actualización de la configuración de indexación de objetos
Para indexar los datos de ubicación, debe actualizar la configuración de indexación de objetos para incluir los datos de ubicación. Como en este tutorial los datos de ubicación se almacenan en una sombra con nombre, defina el `thingIndexingMode` en `REGISTRY` (con un requisito mínimo), defina el `namedShadowIndexingMode` en `ON` y añada los datos de ubicación a la configuración. En este ejemplo, debe añadir el nombre de la sombra con nombre y la ruta de los datos de ubicación de la sombra al `filter`.
1. Ejecute el comando para actualizar la configuración de indexación para indexar las ubicaciones.
```
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"}] } }'
```
El comando no genera ningún resultado. Puede que tenga que esperar un momento hasta que se complete la actualización. Para comprobar el estado, ejecute el comando de la CLI [describe-index](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-index.html). Si ve que `indexStatus` muestra `ACTIVE`, significa que se ha completado la actualización de la indexación de objetos.
1. Ejecute el comando para comprobar la configuración de la indexación. Este paso es opcional.
```
aws iot get-indexing-configuration
```
El resultado puede ser similar al siguiente:
```
{
"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"
}
}
```
## Ejecución de una geoconsulta
Ahora ha actualizado su configuración de indexación de objetos para incluir los datos de ubicación. Intente crear algunas geoconsultas y ejecútelas para ver si puede obtener los resultados de búsqueda deseados. Una geoconsulta debe seguir la [sintaxis de consulta](query-syntax.md). Puede consultar algunos ejemplos útiles de geoconsultas en [Ejemplo de geoconsultas](location-indexing-geoquery.md#location-indexing-geoqueries).
En el siguiente comando de ejemplo, se utiliza la geoconsulta `shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km` para buscar dispositivos que se encuentren dentro de una distancia radial de 15,5 km desde el punto central de las 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 tiene un dispositivo ubicado en las coordenadas lat: 47.6153, lon: -122.3333, que se encuentra a una distancia de 15,5 km del punto central, debería ver este dispositivo (Bike-1) en el resultado. El resultado puede ser similar al siguiente:
```
{
"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 obtener más información, consulte [Indexación de datos de ubicación](location-indexing-geoquery.md).