管理物件索引 - AWS IoT Core
啟用物件索引描述物件索引查詢物件索引法規與限制授權

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

管理物件索引

為所有物件建立的索引為 AWS_Things。您可以控制要從下列資料來源編製索引的內容：AWS IoT 登錄檔資料、AWS IoT Device Shadow 資料，AWS IoT 連線資料，以及 AWS IoT Device Defender 違規資料。

啟用物件索引

您可以使用 update-indexing-configurationCLI命令或 UpdateIndexingConfigurationAPI操作來建立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，再在 filter 中指定已命名影子名稱。

下表顯示每個索引模式的有效值，以及為每個值編製索引的資料來源。

屬性 有效值 登錄檔 影子 連線能力 DD 違規 已命名影子
thingIndexingMode OFF
REGISTRY ✓
REGISTRY_AND_SHADOW ✓ ✓
thingConnectivityIndexingMode 未指定。
OFF
STATUS ✓
deviceDefenderIndexingMode 未指定。
OFF
VIOLATIONS ✓
namedShadowIndexingMode 未指定。
OFF
ON ✓

受管欄位和自訂欄位

受管欄位

受管欄位包含與物件、物件群組、裝置影子、裝置連線能力和 Device Defender 違規相關的資料。 定義受管欄位中 AWS IoT 的資料類型。請在建立 AWS IoT 物件時指定每個受管欄位的值。例如，物件名稱、物件群組和物件描述都是受管欄位。機群索引會根據您指定的索引模式編製受管欄位的索引。無法在 customFields 中變更或顯示受管欄位。

自訂欄位

您可以建立自訂欄位來彙總屬性、Device Shadow 資料和 Device Defender 違規資料，以便為這些資料編製索引。customFields 屬性是欄位名稱和資料類型配對的清單。您可以執行基於資料類型的彙總查詢。您選擇的索引模式會影響可以在 customFields 中指定的欄位。例如，如果您指定 REGISTRY 索引模式，則無法從物件影子中指定自訂欄位。您可以使用 update-indexing-configurationCLI命令來建立或更新自訂欄位 （請參閱更新索引組態範例中的範例命令）。如需詳細資訊，請參閱自訂欄位。

索引篩選條件

索引篩選條件為具名陰影和地理位置資料提供額外的選擇。

namedShadowNames

若要將具名影子新增至機群索引組態，namedShadowIndexingMode請將 設定為 ，ON並在namedShadowNames篩選條件中指定具名影子名稱。

範例

"filter": {
     "namedShadowNames": [ "namedShadow1", "namedShadow2" ]
}

geoLocations

若要將地理位置資料新增至機群索引組態：

  • 如果您的地理位置資料存放在傳統 （未命名） 陰影中，請將 thingIndexingMode 設定為 REGISTRY_AND_SHADOW，並在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"
        }
     ]
  }

如需詳細資訊，請參閱 IndexingFilter AWS IoTAPI參考中的 。

更新索引組態範例

若要更新您的索引組態，請使用 AWS IoT update-indexing-configurationCLI命令 。下列範例示範如何使用 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-indexCLI命令：

aws iot describe-index --index-name "AWS_Things"

describe-index 命令的輸出如下所示：

{
    "indexName": "AWS_Things",
    "indexStatus": "ACTIVE",
    "schema": "MULTI_INDEXING_MODE"
}
注意

機群索引可能需要一些時間才能更新機群索引。建議您等到 indexStatus 顯示ACTIVE後再使用。結構描述欄位可以擁有不同的值，視已設定的資料來源而定。如需詳細資訊，請參閱描述物件索引。

若要取得物件索引組態詳細資訊，請執行 get-indexing-configurationCLI命令：

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-indexCLI命令來擷取物件索引的目前狀態。

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，重建索引時，您可以查詢登錄檔資料 (包括最新的更新)。不過，您無法查詢影子資料，除非重建完成。建立或重建索引所需時間，取決於資料量。

結構描述欄位可以顯示不同的值，視已設定的資料來源而定。下表顯示了不同的結構描述值和相應描述：

結構描述 描述
OFF 未設定任何資料來源或為其編制索引。
REGISTRY 登錄檔資料會編製索引。
REGISTRY_AND_SHADOW 登錄檔資料和未命名 (傳統) 的影子資料都會編製索引。
REGISTRY_AND_CONNECTIVITY 登錄檔資料和連線資料都會編製索引。
REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS 登錄檔資料、未命名 (傳統) 影子資料和連線資料都會編製索引。
MULTI_INDEXING_MODE

除了登錄檔、未命名 (傳統) 影子或連線資料之外，還會編製已命名影子或 Device Defender 違規資料的索引。

查詢物件索引

使用 search-indexCLI命令查詢索引中的資料。

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。裝置因為 1556649874716 而POSIX同時"mything1"中斷連線 (false)CONNECTION_LOST。如需中斷連線原因的詳細資訊，請參閱生命週期事件。

"connectivity": { 
    "connected":false,
    "timestamp":1556649874716, 
    "disconnectReason": "CONNECTION_LOST"
}

裝置在 POSIX 時"mything2"連線 (true)1556649855046：

"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 與登錄中已註冊物件的 thingName 相同。

未登錄檔的影子

如果您使用 來使用尚未在 AWS IoT 帳戶中註冊的物件名稱UpdateThingShadow建立影子，則不會為此影子中的欄位編製索引。這適用於傳統的未命名影子和已命名影子。

數值

如果服務將任何登錄檔或影子資料辨識為數值，則會因其為數值而建立索引。您可以對數值運用包含範圍與比較運算子的查詢 (例如 "attribute.foo<5" 或 "shadow.reported.foo:[75 TO 80]")。若要識別為數值，資料的值必須是有效的常值類型JSON號碼。數值可為介於範圍 -2^53...2^53-1 之間的整數、使用選擇性指數表示法的雙精度浮點，或必須屬於僅包含這些值的陣列。

Null 值

Null 值不編製索引。

最大值

彙總查詢的自訂欄位數量上限是 5。

彙總查詢所要求的百分位數上限是 100。

授權

您可以在 AWS IoT 政策動作中將物件索引指定為 Amazon Resource Name (ARN)，如下所示。

動作 資源

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)。
注意

如果您有查詢機群索引的許可，您就可以存取整個機群的物件資料。