本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 索引位置資料 您可以使用[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)" ``` # 入門教學課程 本教學課程示範如何使用[機群索引](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)。