本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 入門教學課程
本教學課程示範如何使用[機群索引](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**參考*中的 [create-thing](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，請參閱《 *AWS CLI** 參考*》中的 [update-thing-shadow](https://docs.aws.amazon.com//cli/latest/reference/iot-data/update-thing-shadow.html)。
```
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)。
在下列範例命令中，您可以使用 geoquery `shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km`搜尋與座標中心點 (47.6204，-122.3491) 徑向距離 15.5 km 內的裝置。
```
aws iot search-index --query-string "shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
由於您有一個裝置位於座標「lat」：47.6153、「lon」：-122.3333，其距離中心點 15.5 km 的範圍內，因此您應該能夠在輸出中看到此裝置 (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)。