管理事物索引 - AWS IoT
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

管理事物索引

AWS_Things 是为您的所有事物创建的索引。您可以控制对什么建立索引:注册表数据、影子数据和设备连接状态数据(由设备生命周期事件驱动)。

启用事物索引

您可以使用 update-indexing-configuration CLI 命令或 UpdateIndexingConfiguration API 创建 AWS_Things 索引并控制其配置。--thing-indexing-configuration (thingIndexingConfiguration) 参数允许您控制建立索引的数据类型(例如,注册表、阴影和设备连接数据)。

--thing-indexing-configuration 参数采用具有以下结构的字符串:

{ "thingIndexingMode": "OFF"|"REGISTRY"|"REGISTRY_AND_SHADOW", "thingConnectivityIndexingMode": "OFF"|"STATUS", "customFields": [ { name: <field-name>, type: String | Number | Boolean }, ... ] }

thingIndexingMode 属性控制建立索引的数据类型。有效值为:

OFF

无索引。

REGISTRY

为注册表数据建立索引。

REGISTRY_AND_SHADOW

为注册表和事物影子数据建立索引。

thingConnectivityIndexingMode 属性指定是否为事物连接数据建立索引。有效值为:

OFF

不为事物连接数据建立索引。

STATUS

为事物连接数据建立索引。

customFields 属性是字段和数据类型对的列表。可以根据数据类型对这些字段执行聚合查询。您选择的索引模式(REGISTRY 或 REGISTRY_AND_SHADOW)会影响可以在 customFields 中指定的字段。例如,如果指定 REGISTRY 索引模式,则无法从事物影子中指定字段。必须在 customFields 中指定要为其建立索引的自定义字段。

如果配置中的自定义字段与要为其建立索引的值类型不一致,则队列索引服务将忽略聚合查询的不一致值。CloudWatch 日志对于排除聚合查询问题很有帮助。有关更多信息,请参阅队列索引服务的聚合查询疑难解答

托管字段包含与 IoT 事物、事物组和设备影子关联的数据。托管字段的数据类型由 AWS IoT 定义。您可以在创建 IoT 事物时指定每个托管字段的值。例如,事物名称、事物组和事物描述都是托管字段。队列索引服务根据您指定的索引模式为托管字段建立索引:

  • 注册表的托管字段

    "managedFields" : [ {name:thingId, type:String}, {name:thingName, type:String}, {name:registry.version, type:Number}, {name:registry.thingType, type:String}, {name:registry.thingGroupNames, type:String}, ]
  • 事物影子的托管字段

    "managedFields" : [ {name:shadow.version, type:Number}, {name:shadow.delta, type:Boolean} ]
  • 事物连接的托管字段

    "managedFields" : [ {name:connectivity.timestamp, type:Number}, {name:connectivity.version, type:Number}, {name:connectivity.connected, type:Boolean} ]
  • 事物组的托管字段

    "managedFields" : [ {name:description, type:String}, {name:parentGroupNames, type:String}, {name:thingGroupId, type:String}, {name:thingGroupName, type:String}, {name:version, type:Number}, ]

托管字段无法更改或显示在 customFields 中。

下面的示例介绍了如何使用 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}}]

此命令可以为注册表和影子数据建立索引。聚合查询根据数据类型使用托管字段和提供的 customFields

您可以使用 get-indexing-configuration CLI 命令或 GetIndexingConfiguration API 来检索当前的索引配置。

以下命令演示了如何使用 get-indexing-configuration CLI 命令检索定义了五个自定义字段(三个注册表自定义字段和两个影子自定义字段)的当前事物索引配置。

aws iot get-indexing-configuration

{ "thingGroupIndexingConfiguration": { "thingGroupIndexingMode": "OFF" }, "thingIndexingConfiguration": { "thingConnectivityIndexingMode": "STATUS", "customFields": [ { "name": "attributes.customField_NUM", "type": "Number" }, { "name": "shadow.desired.customField_STR", "type": "String" }, { "name": "shadow.desired.customField_NUM", "type": "Number" }, { "name": "attributes.customField_STR", "type": "String" }, { "name": "attributes.customField_BOOL", "type": "Boolean" } ], "thingIndexingMode": "REGISTRY_AND_SHADOW", "managedFields": [ { "name": "shadow.hasDelta", "type": "Boolean" }, { "name": "registry.thingGroupNames", "type": "String" }, { "name": "connectivity.version", "type": "Number" }, { "name": "registry.thingTypeName", "type": "String" }, { "name": "connectivity.connected", "type": "Boolean" }, { "name": "registry.version", "type": "Number" }, { "name": "thingId", "type": "String" }, { "name": "connectivity.timestamp", "type": "Number" }, { "name": "thingName", "type": "String" }, { "name": "shadow.version", "type": "Number" } ] } }

下表提供了允许的 thingIndexingModethingConnectivityIndexingMode 及其关联效果的组合。必需的 thingIndexingMode 参数指定 AWS_Things 索引是只包含注册表数据还是同时包含注册表和影子数据。可选的 thingConnectivityIndexingMode 参数指定索引是否还包含连接状态数据(在设备上次连接 AWS IoT 和与它断开连接时)。

thingIndexingMode thingConnectivityIndexingMode 结果
OFF 未指定。 无索引或删除索引。
OFF OFF 相当于以前的条目。
REGISTRY 未指定。 创建或配置 AWS_Things 索引以仅为注册表数据编制索引。
REGISTRY OFF 相当于以前的条目。(只对注册表数据建立索引。)
REGISTRY_AND_SHADOW 未指定。 创建或配置 AWS_Things 索引,以对注册表数据和影子数据建立索引。
REGISTRY_AND_SHADOW OFF 相当于以前的条目。(对注册数据和影子数据建立索引。)
REGISTRY STATUS 创建或配置 AWS_Things 索引,以对注册表数据和事物连接状态数据建立索引 (REGISTRY_AND_CONNECTIVITY_STATUS)。
REGISTRY_AND_SHADOW STATUS 创建或配置 AWS_Things 索引,以对注册表数据、影子数据和事物连接状态数据建立索引 (REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS)。

您可以使用 AWS IoT update-indexing-configuration CLI 命令更新索引配置。以下示例演示了如何使用 update-indexing-configuration CLI 命令。

简短语法:

aws iot update-indexing-configuration --thing-indexing-configuration "thingIndexingMode=REGISTRY_AND_SHADOW,thingConnectivityIndexingMode=STATUS,customFields=[{name=attributes.version,type=Number},{name=attributes.color,type=String},{name=shadow.desired.power,type=Boolean}]"

JSON 语法:

aws iot update-indexing-configuration --cli-input-json \ '{ "thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY_AND_SHADOW", "thingConnectivityIndexingMode": "STATUS", "customFields": [ { "name": "shadow.desired.power", "type": "Boolean" }, { "name": "attributes.color", "type": "String" }, { "name": "attributes.version", "type": "Number" } ] } }'

这些命令的输出是:

{ "thingIndexingConfiguration": { "thingConnectivityIndexingMode": "STATUS", "customFields": [ { "type": "String", "name": "attributes.color" }, { "type": "Number", "name": "attributes.version" }, { "type": "Boolean", "name": "shadow.desired.power" } ], "thingIndexingMode": "REGISTRY_AND_SHADOW", "managedFields": [ { "type": "Boolean", "name": "connectivity.connected" }, { "type": "String", "name": "registry.thingTypeName" }, { "type": "String", "name": "thingName" }, { "type": "Number", "name": "shadow.version" }, { "type": "String", "name": "thingId" }, { "type": "Boolean", "name": "shadow.hasDelta" }, { "type": "Number", "name": "connectivity.timestamp" }, { "type": "String", "name": "registry.thingGroupNames" }, { "type": "Number", "name": "connectivity.version" }, { "type": "Number", "name": "registry.version" } ] }, "thingGroupIndexingConfiguration": { "thingGroupIndexingMode": "OFF" } }

在以下示例中,新的自定义字段将添加到配置中:

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 时指定所有自定义字段。

重建索引后,您可以对新添加的字段、搜索注册表数据、影子数据和事物连接状态数据使用聚合查询。

更改索引模式时,请使用新的索引模式以确保所有自定义字段均有效。例如,如果从 REGISTRY_AND_SHADOW 模式开始使用名为 shadow.desired.temperature 的自定义字段,则必须先删除 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) 建立索引。

更改索引的配置会导致重新生成索引。此过程中的 indexStatusREBUILDING。在重新生成期间,您可以对事物索引中的数据执行查询。例如,如果您将索引配置从 REGISTRY 更改为 REGISTRY_AND_SHADOW,同时正在重新生成索引,则您可以查询注册表数据,包括最新的更新。但是,在重新生成操作完成之前,无法查询影子数据。生成或重新生成索引所需的时间量取决于数据量。

查询事物索引

使用 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 } }, { "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 设置启用)提供了一个布尔值和时间戳来指示设备是否连接到 AWS IoT Core。设备 "mything1" 在 POSIX 时间 1556649874716 断开连接 (false):

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

设备 "mything2" 在 POSIX 时间 1556649855046 连接 (true):

"connectivity": { "connected":true, "timestamp":1556649855046 }

时间戳以自纪元以来的毫秒数给出,因此 1556649855046 表示 2019 年 4 月 30 日星期二上午 6:44:15.046 (GMT)。

重要

如果设备已断开连接大约一小时,则连接状态的 "timestamp" 值可能会缺失。

限制和局限性

AWS_Things 具有这些限制。

具有复杂类型的影子字段

只有字段的值是简单类型、不包含数组的 JSON 对象或完全由简单类型组成的数组时,才会对影子字段编制索引。“简单类型”是指字符串、数字或文本 truefalse 之一。例如,如果是以下影子状态,则系统将不会编制索引字段 "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" 字段也不会编制索引。)

未注册的影子

如果您使用 UpdateThingShadow 创建一个使用未在您的 AWS IoT 账户中注册的事物名称的影子,则不会为该影子中的字段编制索引。

数字值

如果任何注册表或影子数据被服务识别为数值,则会对其照此编制索引。您可以针对数字值创建涉及范围和比较运算符的查询(例如 "attribute.foo<5""shadow.reported.foo:[75 TO 80]")。要识别为数字,数据的值必须是有效的 JSON 数字类型文本(范围 -2^53...2^53-1 中的整数,或具有可选指数表示法的双精度浮点数)或仅包含此类值的数组的一部分。

Null 值

未对 Null 值编制索引。

聚合查询的最大自定义字段数

5

聚合查询请求的最大百分位数。

100

授权

您可以指定事物索引作为 AWS IoT 策略操作中的资源 ARN,如下所示:

操作 资源

iot:SearchIndex

索引 ARN(例如,arn:aws:iot:<your-aws-region><your-aws-account>:index/AWS_Things)。

iot:DescribeIndex

索引 ARN(例如,arn:aws:iot:<your-aws-region>:index/AWS_Things)。

注意

如果您有权查询队列索引,则可以访问整个队列的事物数据。