管理物件索引 - 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：指定是否要索引裝置防禦者違規資料。

  • 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為「開啟」，在篩選器中新增陰影名稱，並在namedShadowNames篩選器中指定地理位置資料。geoLocations

    下面的示例過濾器指定在一個命名的 shadow（nameShadow1）的地理位置對象：

    "filter": {
     "namedShadowNames": [ "namedShadow1" ],
     "geoLocations": [
        {
            "name": "shadow.name.namedShadow1.reported.location",
            "order": "LonLat"
        }
     ]
  }

有關更多信息，請參閱 IndexingFilter從 AWS IoTAPI 參考。

更新索引組態範例

若要更新索引組態，請使用 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 (啟用) 之後才使用。結構描述欄位可以擁有不同的值，視已設定的資料來源而定。如需詳細資訊，請參閱描述物件索引。

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

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

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

除了登錄檔、未命名 (傳統) 影子或連線資料之外，還會編製已命名影子或 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)。如需中斷連線原因的詳細資訊，請參閱生命週期事件。

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

未登錄檔的影子

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

數值

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

Null 值

Null 值不編製索引。

最大值

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

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

授權

您可以在 AWS IoT 政策動作中將物件索引指定為 Amazon 資源名稱 (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)。
注意

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