本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 索引位置資料
您可以使用[AWS IoT 機群索引](https://docs.aws.amazon.com//iot/latest/developerguide/iot-indexing.html)來為裝置上次傳送的位置資料編製索引，並使用地理位置搜尋裝置。此功能可解決裝置監控和管理使用案例，例如位置追蹤和鄰近搜尋。位置索引的運作方式類似於其他機群索引功能，以及要在[物件索引](managing-fleet-index.md)中指定的其他組態。
常見的使用案例包括： 搜尋和彙總位於所需地理邊界內的裝置， 使用與裝置中繼資料和狀態相關的查詢詞彙，從索引資料來源取得位置特定洞見， 提供精細檢視，例如將結果篩選到特定地理區域，以減少機群監控地圖中的轉譯延遲，並追蹤上次報告的裝置位置。 和 識別超出所需界限限制的裝置，並使用[機群指標](iot-fleet-metrics.md)產生警示。若要開始使用位置索引和地理查詢，請參閱 [入門教學課程](location-indexing-tutorial.md)。
## 支援的資料格式
AWS IoT 機群索引支援下列位置資料格式：
1.
**眾所周知的座標參考系統文字表示**
遵循[地理資訊 - 座標參考系統格式的已知文字表示法的](https://docs.ogc.org/is/12-063r5/12-063r5.html)字串。範例可以是 `"POINT(long lat)"`。
1.
**代表座標的字串**
格式為 `"latitude, longitude"`或 `"longitude, latitude"` 的字串。如果您使用 `"longitude, latitude"`，您還必須在 `order`中指定 `geoLocations`。範例可以是 `"41.12,-71.34"`。
1.
**lat（緯度）、lon（經度） 鍵的物件**
此格式適用於傳統陰影和具名陰影。支援的金鑰：`lat`、`latitude`、`lon`、`long`、`longitude`。範例可以是 `{"lat": 41.12, "lon": -71.34}`。
1.
**代表座標的陣列**
格式為 `[lat,lon]`或 的陣列`[lon,lat]`。如果您使用與 [GeoJSON](https://geojson.org/) 中的座標相同的格式 （適用於傳統陰影和具名陰影）`[lon,lat]`，您還必須在 `order`中指定 `geoLocations`。
範例可以是：
```
{
"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.aws.amazon.com//iot/latest/developerguide/query-syntax.html)。您可以在 [範例地理查詢](#location-indexing-geoqueries) 中找到一些範例。
## 更新物件索引組態
若要為位置資料編製索引，您必須更新索引組態並包含位置資料。根據您的位置資料存放位置，依照步驟更新您的索引組態：
### 儲存在傳統陰影中的位置資料
如果您的位置資料存放在傳統影子中，您必須`thingIndexingMode`將 設定為 ，`REGISTRY_AND_SHADOW`並在 中的`geoLocations`欄位 (`name` 和 `order`) 中指定位置資料[https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html)。
在下列物件索引組態範例中，您將位置資料路徑指定`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`。若要提高限制，請參閱[AWS IoT Device Management 配額](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#fleet-indexing-limits)。
+ `name`
地理位置目標欄位的名稱。的範例值`name`可以是影子的位置資料路徑：`shadow.reported.coordinates`。
+ `order`
地理位置目標欄位的順序。有效值： `LatLon`和 `LonLat`。 `LatLon`表示經緯度。 `LonLat`表示經度和經度。此欄位為選用欄位。預設值為 `LatLon`。
### 存放在具名影子中的位置資料
如果您的位置資料存放在具名影子 (`namedShadowIndexingMode`設定為 )`ON`，請將具名影子名稱新增至 中的 `namedShadowNames` 欄位[https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html)，並在 的 `geoLocations` 欄位中指定位置資料路徑[https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html)。
在下列物件索引組態範例中，您將位置資料路徑指定`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`。若要提高限制，請參閱[AWS IoT Device Management 配額](https://docs.aws.amazon.com//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 km 內的裝置清單。
```
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 km 內的裝置清單。
```
aws iot search-index --query-string \
"shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
**範例查詢 3**
此範例假設位置資料存放在傳統影子中。此命令的輸出是未連線且距離中心點與座標 (47.6204，-122.3491) 徑向距離 15.5 km 外的裝置清單。
```
aws iot search-index --query-string \
"connectivity.connected:false AND (NOT shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km)"
```