本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 管理物件索引
為所有物件建立的索引為 `AWS_Things`。您可以控制要從下列資料來源編製索引的內容：[AWS IoT 登錄檔](thing-registry.md)資料、[AWS IoT Device Shadow](iot-device-shadows.md) 資料，[AWS IoT 連線](life-cycle-events.md)資料，以及 [AWS IoT Device Defender](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/what-is-device-defender.html) 違規資料。
**Topics**
+ [啟用物件索引](#enable-index)
+ [描述物件索引](#describe-index)
+ [查詢物件索引](#search-index)
+ [法規與限制](#index-limitations)
+ [Authorization](#query-auth)
## 啟用物件索引
您可以使用 [update-indexing-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html) CLI 命令或 [UpdateIndexingConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateIndexingConfiguration.html) API 操作來建立 `AWS_Things` 索引，並控制其組態。您可以透過使用 `--thing-indexing-configuration` (`thingIndexingConfiguration`) 參數，來控制要編製索引的資料類型 (例如，登錄檔資料、影子整理、裝置連線資料以及 Device Defender 違規資料)。
`--thing-indexing-configuration` 參數採用具有以下結構的字符：
```
{
"thingIndexingMode": "OFF"|"REGISTRY"|"REGISTRY_AND_SHADOW",
"thingConnectivityIndexingMode": "OFF"|"STATUS",
"deviceDefenderIndexingMode": "OFF"|"VIOLATIONS",
"namedShadowIndexingMode": "OFF"|"ON",
"managedFields": [
{
"name": "string",
"type": "Number"|"String"|"Boolean"
},
...
],
"customFields": [
{
"name": "string",
"type": "Number"|"String"|"Boolean"
},
...
],
"filter": {
"namedShadowNames": [ "string" ],
"geoLocations": [
{
"name": "String",
"order": "LonLat|LatLon"
}
]
}
}
```
### 物件索引模式
您可以在索引組態中指定不同的物件索引模式，視您要從中編製索引和搜尋裝置的資料來源而定：
+ `thingIndexingMode`：控制登錄檔或影子是否編製索引。當 `thingIndexingMode` 設定為 時`OFF`，物件索引會停用。
+ `thingConnectivityIndexingMode`：指定物件連線資料是否已編製索引。
+ `deviceDefenderIndexingMode`：指定 Device Defender 違規資料是否編製索引。
+ `namedShadowIndexingMode`：指定命名陰影資料是否已編製索引。若要選取要新增至機群索引組態的已命名影子，請將 `namedShadowIndexingMode` 設為 `ON`，再在 [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html) 中指定已命名影子名稱。
下表顯示每個索引模式的有效值，以及針對每個值編製索引的資料來源。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/managing-index.html)
### 受管欄位和自訂欄位
**受管欄位**
受管欄位包含與物件、物件群組、裝置陰影、裝置連線能力和 Device Defender 違規相關的資料。 定義受 AWS IoT 管欄位中的資料類型。請在建立 AWS IoT 物件時指定每個受管欄位的值。例如，物件名稱、物件群組和物件描述都是受管欄位。機群索引會根據您指定的索引模式編製受管欄位的索引。無法在 `customFields` 中變更或顯示受管欄位。
**自訂欄位**
您可以建立自訂欄位來彙總屬性、Device Shadow 資料和 Device Defender 違規資料，以便為這些資料編製索引。`customFields` 屬性是欄位名稱和資料類型配對的清單。您可以執行基於資料類型的彙總查詢。您選擇的索引模式會影響可以在 `customFields` 中指定的欄位。例如，如果您指定 `REGISTRY` 索引模式，則無法從物件影子中指定自訂欄位。您可以使用 [update-indexing-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html) CLI 命令來建立或更新自訂欄位 (請參閱[更新索引組態範例](#update-index-examples)的範例命令)。如需詳細資訊，請參閱[自訂欄位](managing-fleet-index.md#custom-field)。
### 索引篩選條件
索引篩選條件為具名影子和地理位置資料提供額外的選擇。
**`namedShadowNames`**
若要將具名影子新增至機群索引組態，`namedShadowIndexingMode`請將 設定為 ，`ON`並在`namedShadowNames`篩選條件中指定具名影子名稱。
**範例**
```
"filter": {
"namedShadowNames": [ "namedShadow1", "namedShadow2" ]
}
```
`geoLocations`
若要將地理位置資料新增至機群索引組態：
+ 如果您的地理位置資料存放在傳統 （未命名） 陰影中，請將 `thingIndexingMode`設定為 REGISTRY\$1AND\$1SHADOW，並在`geoLocations`篩選條件中指定您的地理位置資料。
以下範例篩選條件指定傳統 （未命名） 陰影中的 geoLocation 物件：
```
"filter": {
"geoLocations": [
{
"name": "shadow.reported.location",
"order": "LonLat"
}
]
}
```
+ 如果您的地理位置資料存放在具名影子中，請將 `namedShadowIndexingMode`設定為 ON、在`namedShadowNames`篩選條件中新增影子名稱，並在`geoLocations`篩選條件中指定您的地理位置資料。
以下範例篩選條件指定具名影子中的 geoLocation 物件 (`nameShadow1`)：
```
"filter": {
"namedShadowNames": [ "namedShadow1" ],
"geoLocations": [
{
"name": "shadow.name.namedShadow1.reported.location",
"order": "LonLat"
}
]
}
```
如需詳細資訊，請參閱來自 *AWS IoT* *API 參考*的 [ IndexingFilter](https://docs.aws.amazon.com/iot/latest/apireference/API_IndexingFilter.html)。
### 更新索引組態範例
若要更新您的索引組態，請使用 AWS IoT **update-indexing-configuration** CLI 命令 。下列範例示範如何使用 **update-indexing-configuration**。
簡短語法：
```
aws iot update-indexing-configuration --thing-indexing-configuration \
'thingIndexingMode=REGISTRY_AND_SHADOW, deviceDefenderIndexingMode=VIOLATIONS,
namedShadowIndexingMode=ON,filter={namedShadowNames=[thing1shadow]}, thingConnectivityIndexingMode=STATUS,
customFields=[{name=attributes.version,type=Number},
{name=shadow.name.thing1shadow.desired.DefaultDesired, type=String}, {name=shadow.desired.power, type=Boolean},
{name=deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number, type=Number}]'
```
JSON 語法：
```
aws iot update-indexing-configuration --cli-input-json \ '{
"thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY_AND_SHADOW",
"thingConnectivityIndexingMode": "STATUS",
"deviceDefenderIndexingMode": "VIOLATIONS",
"namedShadowIndexingMode": "ON",
"filter": { "namedShadowNames": ["thing1shadow"]},
"customFields": [ { "name": "shadow.desired.power", "type": "Boolean" },
{"name": "attributes.version", "type": "Number"},
{"name": "shadow.name.thing1shadow.desired.DefaultDesired", "type": "String"},
{"name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number", "type": Number} ] } }'
```
此命令不會產生任何輸出。
若要檢查物件索引狀態，請執行 `describe-index` CLI 命令：
```
aws iot describe-index --index-name "AWS_Things"
```
`describe-index` 命令的輸出如下所示：
```
{
"indexName": "AWS_Things",
"indexStatus": "ACTIVE",
"schema": "MULTI_INDEXING_MODE"
}
```
**注意**
機群索引可能需要一些時間才能更新機群索引。建議等到 `indexStatus` 顯示 ACTIVE (啟用) 之後才使用。結構描述欄位可以擁有不同的值，視已設定的資料來源而定。如需詳細資訊，請參閱[描述物件索引](#describe-index)。
若要獲取索引組態的詳細資訊，請執行 `get-indexing-configuration` CLI 命令：
```
aws iot get-indexing-configuration
```
`get-indexing-configuration` 命令的輸出如下所示：
```
{
"thingIndexingConfiguration": {
"thingIndexingMode": "REGISTRY_AND_SHADOW",
"thingConnectivityIndexingMode": "STATUS",
"deviceDefenderIndexingMode": "VIOLATIONS",
"namedShadowIndexingMode": "ON",
"managedFields": [
{
"name": "connectivity.disconnectReason",
"type": "String"
},
{
"name": "registry.version",
"type": "Number"
},
{
"name": "thingName",
"type": "String"
},
{
"name": "deviceDefender.violationCount",
"type": "Number"
},
{
"name": "shadow.hasDelta",
"type": "Boolean"
},
{
"name": "shadow.name.*.version",
"type": "Number"
},
{
"name": "shadow.version",
"type": "Number"
},
{
"name": "connectivity.version",
"type": "Number"
},
{
"name": "connectivity.timestamp",
"type": "Number"
},
{
"name": "shadow.name.*.hasDelta",
"type": "Boolean"
},
{
"name": "registry.thingTypeName",
"type": "String"
},
{
"name": "thingId",
"type": "String"
},
{
"name": "connectivity.connected",
"type": "Boolean"
},
{
"name": "registry.thingGroupNames",
"type": "String"
}
],
"customFields": [
{
"name": "shadow.name.thing1shadow.desired.DefaultDesired",
"type": "String"
},
{
"name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number",
"type": "Number"
},
{
"name": "shadow.desired.power",
"type": "Boolean"
},
{
"name": "attributes.version",
"type": "Number"
}
],
"filter": {
"namedShadowNames": [
"thing1shadow"
]
}
},
"thingGroupIndexingConfiguration": {
"thingGroupIndexingMode": "OFF"
}
}
```
若要更新自訂欄位，您可以執行 `update-indexing-configuration` 命令。範例如下：
```
aws iot update-indexing-configuration --thing-indexing-configuration
'thingIndexingMode=REGISTRY_AND_SHADOW,customFields=[{name=attributes.version,type=Number},{name=attributes.color,type=String},{name=shadow.desired.power,type=Boolean},{name=shadow.desired.intensity,type=Number}]'
```
此命令已將 `shadow.desired.intensity` 新增至索引組態。
**注意**
更新索引組態中的自訂欄位會覆寫所有現有的自訂欄位。請務必在呼叫 **update-indexing-configuration** 時指定所有自訂欄位。
在重建索引之後，您可以在剛新增的欄位上使用彙總查詢，然後搜尋登錄檔資料、影子資料和物件連線狀態資料。
變更索引模式時，請使用新的索引模式確定所有自訂欄位都有效。例如，如果以自訂欄位名為 `shadow.desired.temperature` 的 `REGISTRY_AND_SHADOW` 模式開始，則必須先刪除 `shadow.desired.temperature` 自訂欄位，再將索引模式變更為 `REGISTRY`。如果索引組態包含未被索引模式編製索引的自訂欄位，更新就會失敗。
## 描述物件索引
以下命令說明如何使用 **describe-index** CLI 命令，擷取物件索引的目前狀態。
```
aws iot describe-index --index-name "AWS_Things"
```
命令的回應可能如下所示：
```
{
"indexName": "AWS_Things",
"indexStatus": "BUILDING",
"schema": "REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS"
}
```
第一次建立機群索引時， 會 AWS IoT 建置您的索引。`indexStatus` 為 `BUILDING` 狀態時，便法在索引內進行查詢。物件索引的 `schema` 會指出系統會為何種類型的資料 (`REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS`) 建立索引。
若您變更索引的組態，將導致索引重新建立。在此程序期間的 `indexStatus` 為 `REBUILDING`。您可以在重建物件索引時，對物件索引內的資料執行查詢。例如，若您將索引組態從 `REGISTRY` 變更為 `REGISTRY_AND_SHADOW`，重建索引時，您可以查詢登錄檔資料 (包括最新的更新)。不過，您無法查詢影子資料，除非重建完成。建立或重建索引所需時間，取決於資料量。
結構描述欄位可以顯示不同的值，視已設定的資料來源而定。下表顯示了不同的結構描述值和相應描述：
| 結構描述 | Description |
| --- | --- |
| OFF | 未設定任何資料來源或為其編制索引。 |
| REGISTRY | 登錄檔資料會編製索引。 |
| REGISTRY\$1AND\$1SHADOW | 登錄檔資料和未命名 (傳統) 的影子資料都會編製索引。 |
| REGISTRY\$1AND\$1CONNECTIVITY | 登錄檔資料和連線資料都會編製索引。 |
| REGISTRY\$1AND\$1SHADOW\$1AND\$1CONNECTIVITY\$1STATUS | 登錄檔資料、未命名 (傳統) 影子資料和連線資料都會編製索引。 |
| MULTI\$1INDEXING\$1MODE | 除了登錄檔、未命名 (傳統) 影子或連線資料之外，還會編製已命名影子或 Device Defender 違規資料的索引。 |
## 查詢物件索引
使用 **search-index** CLI 命令來查詢索引中的資料。
```
aws iot search-index --index-name "AWS_Things" --query-string
"thingName:mything*"
```
```
{
"things":[{
"thingName":"mything1",
"thingGroupNames":[
"mygroup1"
],
"thingId":"a4b9f759-b0f2-4857-8a4b-967745ed9f4e",
"attributes":{
"attribute1":"abc"
},
"connectivity": {
"connected":false,
"timestamp":1556649874716,
"disconnectReason": "CONNECTION_LOST"
}
},
{
"thingName":"mything2",
"thingTypeName":"MyThingType",
"thingGroupNames":[
"mygroup1",
"mygroup2"
],
"thingId":"01014ef9-e97e-44c6-985a-d0b06924f2af",
"attributes":{
"model":"1.2",
"country":"usa"
},
"shadow":{
"desired":{
"location":"new york",
"myvalues":[3, 4, 5]
},
"reported":{
"location":"new york",
"myvalues":[1, 2, 3],
"stats":{
"battery":78
}
},
"metadata":{
"desired":{
"location":{
"timestamp":123456789
},
"myvalues":{
"timestamp":123456789
}
},
"reported":{
"location":{
"timestamp":34535454
},
"myvalues":{
"timestamp":34535454
},
"stats":{
"battery":{
"timestamp":34535454
}
}
}
},
"version":10,
"timestamp":34535454
},
"connectivity": {
"connected":true,
"timestamp":1556649855046
}
}],
"nextToken":"AQFCuvk7zZ3D9pOYMbFCeHbdZ+h=G"
}
```
在 JSON 回應中，`"connectivity"` (透過 `thingConnectivityIndexingMode=STATUS` 設定啟用) 會提供布林值、時間戳記以及 disconnectReason，以指出裝置是否已連接到 AWS IoT Core。因為 `CONNECTION_LOST`，裝置 `"mything1"` 在 POSIX 時間 `1556649874716` 中斷連線 (`false`)。如需中斷連線原因的詳細資訊，請參閱[生命週期事件](life-cycle-events.md)。
```
"connectivity": {
"connected":false,
"timestamp":1556649874716,
"disconnectReason": "CONNECTION_LOST"
}
```
裝置 `"mything2"` 在 POSIX 時間 `1556649855046` 連線 (`true`)：
```
"connectivity": {
"connected":true,
"timestamp":1556649855046
}
```
時間戳記是以從 epoch 算起的毫秒提供，因此 `1556649855046` 代表 2019 年 4 月 30 日星期二下午 6:44:15.046 (UTC)。
**重要**
如果裝置已中斷連線大約一小時，則可能會缺少連線狀態的 `"timestamp"` 值和 `"disconnectReason"` 值。
## 法規與限制
這些是 `AWS_Things` 的限制。
**類型複雜的影子欄位**
只有當欄位的值為簡單類型，像是不包含陣列的 JSON 物件，或完全由簡單類型組成的陣列時，才會建立該影子欄位的索引。簡單類型是指字串、數值或下列其中一個常值：`true` 或 `false`。以下列影子狀態為例，欄位 `"palette"` 的值不會編製索引，因為它是包含複雜類型項目的陣列。而因為該陣列中的每個值皆為字串，所以 `"colors"` 欄位的值會建立索引。
```
{
"state": {
"reported": {
"switched": "ON",
"colors": [ "RED", "GREEN", "BLUE" ],
"palette": [
{
"name": "RED",
"intensity": 124
},
{
"name": "GREEN",
"intensity": 68
},
{
"name": "BLUE",
"intensity": 201
}
]
}
}
}
```
**巢狀影子欄位名稱**
巢狀影子欄位的名稱會儲存為以句號 (.) 分隔的字串。例如，假設影子文件為：
```
{
"state": {
"desired": {
"one": {
"two": {
"three": "v2"
}
}
}
}
}
```
`three` 欄位的名稱會儲存為 `desired.one.two.three`。如果您也有影子文件，會如此儲存：
```
{
"state": {
"desired": {
"one.two.three": "v2"
}
}
}
```
同時符合 `shadow.desired.one.two.three:v2` 的查詢。最佳實務是不要在影子欄位名稱中使用句點。
**影子中繼資料**
只有當建立影子的 `"state"` 區段中之對應欄位的索引時，才會建立影子中繼資料區段中之欄位的索引。(在前面的範例中，也不會建立影子中繼資料區段中 `"palette"` 欄位的索引。)
**未註冊的裝置**
機群索引會為裝置的連線狀態建立索引，其連線 `clientId` 與[登錄](https://docs.aws.amazon.com//iot/latest/developerguide/thing-registry.html)中已註冊物件的 `thingName` 相同。
**未登錄檔的影子**
如果您使用 [UpdateThingShadow](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html)，使用尚未在 AWS IoT 帳戶中註冊的物件名稱建立影子，則此影子中的欄位不會編製索引。這適用於傳統的未命名影子和已命名影子。
**數值**
如果服務將任何登錄檔或影子資料辨識為數值，則會因其為數值而建立索引。您可以對數值運用包含範圍與比較運算子的查詢 (例如 `"attribute.foo<5"` 或 `"shadow.reported.foo:[75 TO 80]"`)。若要識別為數字，資料的值必須是有效的文字類型 JSON 數字。數值可為介於範圍 -2^53...2^53-1 之間的整數、使用選擇性指數表示法的雙精度浮點，或必須屬於僅包含這些值的陣列。
**Null 值**
Null 值不編製索引。
**最大值**
彙總查詢的自訂欄位數量上限是 5。
彙總查詢所要求的百分位數上限是 100。
## Authorization
您可以在 AWS IoT 政策動作中將物件索引指定為 Amazon Resource Name (ARN)，如下所示。
****
| Action | 資源 |
| --- | --- |
| `iot:SearchIndex` | 索引 ARN (例如，`arn:aws:iot:your-aws-regionyour-aws-account:index/AWS_Things`)。 |
| `iot:DescribeIndex` | 索引 ARN (例如，`arn:aws:iot:your-aws-region:index/AWS_Things`)。 |
**注意**
如果您有查詢機群索引的許可，您就可以存取整個機群的物件資料。