本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 为位置数据编制索引
您可以使用 [Amazon IoT 实例集索引](https://docs.amazonaws.cn//iot/latest/developerguide/iot-indexing.html)将设备上次发送的位置数据编入索引，并使用地理查询搜索设备。此特征解决了设备监控和管理使用案例，例如位置跟踪和邻近搜索。位置索引的工作原理与其他实例集索引特征类似，并且需要在[事物索引](managing-fleet-index.md)中指定其他配置。
常见使用案例包括：搜索和聚合位于所需地理边界内的设备；使用编入索引的数据来源中与设备元数据和状态相关的查询词获取特定位置的见解；提供精细视图，例如筛选特定地理区域的结果，以减少实例集监控地图中的渲染延迟并跟踪上次报告的设备位置；以及识别超出所需边界限制的设备并使用[实例集指标](iot-fleet-metrics.md)生成警报。要开始使用位置索引和地理查询，请参阅 [入门教程](location-indexing-tutorial.md)。
## 支持的数据格式
Amazon IoT 舰队索引支持以下位置数据格式：
1.
**坐标参考系的已知文本表示**
遵循 [Geographic information - Well-known text representation of coordinate reference systems](https://docs.ogc.org/is/12-063r5/12-063r5.html) 格式的字符串。例如 `"POINT(long lat)"`。
1.
**表示坐标的字符串**
格式为 `"latitude, longitude"` 或 `"longitude, latitude"` 的字符串。如果使用 `"longitude, latitude"`，还必须指定在 `geoLocations` 中指定 `order`。例如 `"41.12,-71.34"`。
1.
**由纬度、经度键组成的对象**
这种格式适用于经典影子和命名影子。支持的键：`lat`、`latitude`、`lon`、`long`、`longitude`。例如 `{"lat": 41.12, "lon": -71.34}`。
1.
**表示坐标的数组**
格式为 `[lat,lon]` 或 `[lon,lat]` 的数组。如果您使用与 [GeoJSON](https://geojson.org/) 中的坐标相同的 `[lon,lat]` 格式（适用于经典影子和命名影子），则还必须在 `geoLocations` 中指定 `order`。
例如：
```
{
"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"
}
}
}
```
## 如何为位置数据编制索引
以下步骤说明如何更新位置数据的索引配置，以及如何使用地理查询来搜索设备。
1.
**知道您的位置数据存储在什么位置**
实例集索引目前支持为存储在经典影子或命名影子中的位置数据编制索引。
1.
**使用支持的位置数据格式**
确保您的位置数据格式遵循[支持的数据格式](#location-indexing-format)之一。
1.
**更新索引配置**
至少需要启用事物（注册表）索引配置。您还必须对包含您位置数据的经典影子或命名影子启用索引编制。更新事物索引时，应在索引配置中包含位置数据。
1.
**创建并运行地理查询**
根据您的使用案例，创建地理查询并运行这些查询来搜索设备。您编写的地理查询必须遵循[查询语法](https://docs.amazonaws.cn//iot/latest/developerguide/query-syntax.html)。您可以在 [地理查询示例](#location-indexing-geoqueries) 中找到一些示例。
## 更新事物索引配置
要为位置数据编制索引，您必须更新索引配置并包含您的位置数据。根据您位置数据的存储位置，请按照以下步骤更新您的索引配置：
### 位置数据存储在经典影子中
如果您的位置数据存储在经典影子中，则必须将 `thingIndexingMode` 设置为 `REGISTRY_AND_SHADOW`，并在 [https://docs.amazonaws.cn//iot/latest/apireference/API_IndexingFilter.html](https://docs.amazonaws.cn//iot/latest/apireference/API_IndexingFilter.html) 中的 `geoLocations` 字段（`name` 和 `order`）中指定您的位置数据。
在以下事物索引配置示例中，您可以将位置数据路径 `shadow.reported.coordinates` 指定为 `name`，将 `LonLat` 指定为 `order`。
```
{
"thingIndexingMode": "REGISTRY_AND_SHADOW",
"filter": {
"geoLocations": [
{
"name": "shadow.reported.coordinates",
"order": "LonLat"
}
]
}
}
```
+ `thingIndexingMode`
索引模式控制是否对注册表或影子编制索引。如果 `thingIndexingMode` 设置为 `OFF`，则禁用事物索引。
要为存储在经典影子中的位置数据编制索引，必须将 `thingIndexingMode` 设置为 `REGISTRY_AND_SHADOW`。有关更多信息，请参阅 [事物索引模式](managing-index.md#index-mode)。
+ `filter`
索引筛选器为命名影子和地理位置数据提供了其他选择。有关更多信息，请参阅 [索引筛选器](managing-index.md#thing-indexing-filter)。
+ `geoLocations`
您选择要编制索引的地理位置目标列表。要编制索引的默认最大地理位置目标数量为 `1`。要提高限制，请参阅 [Amazon IoT Device Management 限额](https://docs.amazonaws.cn//general/latest/gr/iot_device_management.html#fleet-indexing-limits)。
+ `name`
地理位置目标字段的名称。`name` 的示例值可以是影子的位置数据路径：`shadow.reported.coordinates`。
+ `order`
地理位置目标字段的顺序。有效值：`LatLon` 和 `LonLat`。`LatLon` 表示纬度和经度。`LonLat` 表示经度和纬度。该字段是可选的。默认值为 `LatLon`。
### 位置数据存储在命名影子中
如果您的位置数据存储在命名影子中，请将 `namedShadowIndexingMode` 设置为 `ON`，将您的命名影子名称添加到 [https://docs.amazonaws.cn//iot/latest/apireference/API_IndexingFilter.html](https://docs.amazonaws.cn//iot/latest/apireference/API_IndexingFilter.html) 的 `namedShadowNames` 字段中，并在 [https://docs.amazonaws.cn//iot/latest/apireference/API_IndexingFilter.html](https://docs.amazonaws.cn//iot/latest/apireference/API_IndexingFilter.html) 的 `geoLocations` 字段中指定您的位置数据路径。
在以下事物索引配置示例中，您可以将位置数据路径 `shadow.name.namedShadow1.reported.coordinates` 指定为 `name`，将 `LonLat` 指定为 `order`。
```
{
"thingIndexingMode": "REGISTRY",
"namedShadowIndexingMode": "ON",
"filter": {
"namedShadowNames": [
"namedShadow1"
],
"geoLocations": [
{
"name": "shadow.name.namedShadow1.reported.coordinates",
"order": "LonLat"
}
]
}
}
```
+ `thingIndexingMode`
索引模式控制是否对注册表或影子编制索引。如果 `thingIndexingMode` 设置为 `OFF`，则禁用事物索引。
要为存储在命名影子中的位置数据编制索引，必须将 `thingIndexingMode` 设置为 `REGISTRY`（或 `REGISTRY_AND_SHADOW`）。有关更多信息，请参阅 [事物索引模式](managing-index.md#index-mode)。
+ `filter`
索引筛选器为命名影子和地理位置数据提供了其他选择。有关更多信息，请参阅 [索引筛选器](managing-index.md#thing-indexing-filter)。
+ `geoLocations`
您选择要编制索引的地理位置目标列表。要编制索引的默认最大地理位置目标数量为 `1`。要提高限制，请参阅 [Amazon IoT Device Management 限额](https://docs.amazonaws.cn//general/latest/gr/iot_device_management.html#fleet-indexing-limits)。
+ `name`
地理位置目标字段的名称。`name` 的示例值可以是影子的位置数据路径：`shadow.name.namedShadow1.reported.coordinates`。
+ `order`
地理位置目标字段的顺序。有效值：`LatLon` 和 `LonLat`。`LatLon` 表示纬度和经度。`LonLat` 表示经度和纬度。该字段是可选的。默认值为 `LatLon`。
## 地理查询示例
完成位置数据的索引配置后，请运行地理查询来搜索设备。您也可以将地理查询与其他查询字符串合并。有关更多信息，请参阅[查询语法](query-syntax.md)和[事物查询示例](example-queries.md)。
**示例查询 1**
此示例假设位置数据存储在命名影子 `gps-tracker` 中。此命令的输出是距坐标为（47.6204,-122.3491）的中心点的径向距离在 15.5 千米内的设备列表。
```
aws iot search-index --query-string \
"shadow.name.gps-tracker.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
**示例查询 2**
此示例假设位置数据存储在经典影子中。此命令的输出是距坐标为（47.6204,-122.3491）的中心点的径向距离在 15.5 千米内的设备列表。
```
aws iot search-index --query-string \
"shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
**示例查询 3**
此示例假设位置数据存储在经典影子中。此命令的输出是未连接且距坐标为（47.6204,-122.3491）的中心点的径向距离在 15.5 千米以外的设备列表。
```
aws iot search-index --query-string \
"connectivity.connected:false AND (NOT shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km)"
```