入門教學課程 - AWS IoT Core
必要條件創建事物和陰影更新物件索引組態執行地理查詢

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

入門教學課程

本教學課程示範如何使用叢集索引編製位置資料的索引。為了簡化起見，您可以建立表示裝置的物件，並將位置資料儲存在具名陰影中，更新物件索引組態以進行位置索引，並執行範例地理查詢以搜尋徑向邊界內的裝置。

此教學課程約需 15 分鐘方能完成。

必要條件

創建事物和陰影

您可以創建一個代表您的設備的東西，並創建一個命名的陰影來存儲其位置數據（坐標 47.61564，-122.33584）。

  1. 運行以下命令來創建代表您名為 Bike-1 的自行車的東西。如需如何使用建立物件的詳細資訊 AWS CLI，請參閱從參考建立物件。AWS CLI

    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"
}

  2. 執行下列指令以建立具名陰影來儲存自行車 1 號的位置資料 (座標 47.61564, -122.33584)。如需如何使用建立具名陰影的詳細資訊 AWS CLI，請參閱AWS CLI參考update-thing-shadow中的〈〉。

    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 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"}] } }'

    命令不會產生任何輸出。您可能需要等待片刻，直到更新完成。若要檢查狀態，請執行描述索引 CLI 命令。如果您看到indexStatus顯示：ACTIVE，則表示您的物件索引更新已完成。

  2. 執行命令以驗證您的索引組態。此為選擇性步驟。

    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"
    }
}

執行地理查詢

現在，您已更新物件索引組態以包含位置資料。嘗試創建一些地理查詢並運行它們以查看是否可以獲得所需的搜索結果。地理查詢必須遵循查詢語法。您可以在地理查詢示例中找到一些有用的地理查詢示例。

在以下範例指令中，您可以使用地理查詢shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km來搜尋距中心點 15.5 公里之徑向距離內的裝置 (47.6204, -122.3491)。

aws iot search-index --query-string "shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"

因為您的設備位於坐標「緯度」：47.6153，「LON」：-122.3333，該設備落在距中心點 15.5 公里的距離內，因此您應該能夠在輸出中看到此設備（自行車 -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}"
        }
    ]
}

如需更多詳細資訊，請參閱 索引位置資料。