AWS IoT
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

管理事物索引

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

启用事物索引

您可以创建 AWS_Things 索引并使用 UpdateIndexingConfiguration API 中的 --thing-indexing-configuration 参数来控制其配置。您可以使用 GetIndexingConfiguration API 检索当前索引配置。

以下命令说明了如何使用 get-indexing-configuration CLI 命令来检索当前的事物索引配置。(在本示例中,事物索引当前已禁用。)

aws iot get-indexing-configuration { "thingIndexingConfiguration": { "thingConnectivityIndexingMode": "OFF" "thingIndexingMode": "OFF" } }

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

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

使用 update-indexing-configuration CLI 命令更新事物索引配置。在以下示例中,您可以使用 AWS_Things 索引(在生成之后,如下一节所述)搜索注册表数据、影子数据和事物连接状态数据。

aws iot update-indexing-configuration --thing-indexing-configuration thingIndexingMode=REGISTRY_AND_SHADOW,thingConnectivityIndexingMode=STATUS

描述事物索引

以下命令说明了如何使用 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 核心。设备 "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" 值可能会缺失。对于持久性会话,在客户端断开连接的时间超过为持久性会话配置的生存时间 (TTL) 后,该值可能会缺失。仅为客户端 ID 具有匹配事物名称的连接,对连接状态数据建立索引。(客户端 ID 是用于将设备到连接 AWS IoT 核心的值。)

限制

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" 字段也不会编制索引。)

未注册的影子

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

数字值

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

Null 值

未对 Null 值编制索引。

授权

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

操作 资源

iot:SearchIndex

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

iot:DescribeIndex

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

注意

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