本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 入门教程
本教程演示了如何使用[实例集索引](iot-indexing.md)来[为您的位置数据编制索引](location-indexing-geoquery.md)。为简单起见，您可以创建一个代表您设备的事物，并将位置数据存储在命名影子中，更新位置索引的事物索引配置，并运行示例地理查询来搜索径向边界内的设备。
完成本教程需要大约 15 分钟。
**Topics**
+ [先决条件](#location-indexing-tutorial-prerequisites)
+ [创建事物和影子](#location-indexing-create-resources)
+ [更新事物索引配置](#location-indexing-update-configuration)
+ [运行地理查询](#location-indexing-run-geoquery)
## 先决条件
+ 安装 [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) 的最新版本。
+ 自行熟悉[位置索引和地理查询](https://docs.aws.amazon.com/iot/latest/developerguide/location-indexing-geoquery.html)、[管理事物索引](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html)和[查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
## 创建事物和影子
您可以创建一个代表您设备的事物，以及一个命名影子来存储其位置数据，坐标为（47.61564,-122.33584）。
1. 运行以下命令来创建代表您自行车（名为 Bike-1）的事物。*有关如何使用创建事物的更多信息 AWS CLI，请参阅通过参考[创建事物*AWS CLI*](https://docs.aws.amazon.com//cli/latest/reference/iot/create-thing.html)。*
```
aws iot create-thing --thing-name "Bike-1" \
--attribute-payload '{"attributes": {"model":"OEM-2302-12", "battery":"35", "acqDate":"06/09/23"}}'
```
此命令的输出可能如下所示：
```
{
"thingName": "Bike-1",
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/Bike-1",
"thingId": "df9cf01d-b0c8-48fe-a2e2-e16cff6b23df"
}
```
1. 运行以下命令创建一个命名影子来存储 Bike-1 的位置数据，坐标为（47.61564,-122.33584）。有关如何使用创建命名阴影的更多信息 AWS CLI，请参阅 “[update-thing-shadow](https://docs.aws.amazon.com//cli/latest/reference/iot-data/update-thing-shadow.html)参*AWS CLI**考*”。
```
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" \
```
此命令不会生成任何输出。要查看您创建的命名阴影，可以运行 [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
```
此命令的输出可能如下所示：
```
{
"results": [
"Bike1-shadow"
],
"timestamp": 1699574309
}
```
## 更新事物索引配置
要为位置数据编制索引，您必须更新您的事物索引配置，使其包含位置数据。由于您的位置数据存储在本教程中的命名影子中，请将 `thingIndexingMode` 设置为 `REGISTRY`（最低要求），将 `namedShadowIndexingMode` 设置为 `ON`，然后将您的位置数据添加到配置中。在此示例中，您必须将命名影子的名称和影子的位置数据路径添加到 `filter` 中。
1. 运行以下命令来更新位置索引的索引配置。
```
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"}] } }'
```
命令不会生成任何输出。您可能需要稍等片刻，直到更新完成。要检查状态，请运行 [describe-index](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-index.html) CLI 命令：如果您看到 `indexStatus` 显示 `ACTIVE`，则表示您的事物索引更新已完成。
1. 运行以下命令来验证您的索引配置。此为可选步骤。
```
aws iot get-indexing-configuration
```
输出类似于以下内容：
```
{
"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"
}
}
```
## 运行地理查询
现在，您已经更新了事物索引配置，使其包含位置数据。请尝试创建一些地理查询，并运行这些查询以查看您是否可以获得所需的搜索结果。地理查询必须遵循[查询语法](query-syntax.md)。您可以在 [地理查询示例](location-indexing-geoquery.md#location-indexing-geoqueries) 中找到一些有用的地理查询示例。
在以下示例命令中，使用地理查询 `shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km` 搜索距坐标为（47.6204,-122.3491）的中心点的径向距离在 15.5 千米以内的设备。
```
aws iot search-index --query-string "shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
由于您设备的坐标纬度是 47.6153，经度是 -122.3333，距中心点的距离在 15.5 千米之内，因此您应该能够在输出中看到此设备（Bike-1）。输出类似于以下内容：
```
{
"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}"
}
]
}
```
有关更多信息，请参阅 [为位置数据编制索引](location-indexing-geoquery.md)。