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

管理事物索引

AWS_Things 是为您的所有事物创建的索引。您可以从以下数据源控制要索引的内容:Amazon IoT注册表数据,Amazon IoTDevice Shadow数据,Amazon IoT连接数据以及Amazon IoT Device Defender违规数据。

启用事物索引

您可以使用 update-indexing-configuration CLI 命令或 UpdateIndexingConfiguration 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" ] } }

事物索引模式

thingIndexingMode 属性控制建立索引的数据类型。

重要

要启用事物索引,thingIndexingMode 不能将属性设置为 OFF。

属性 有效值 描述
thingIndexingMode OFF 无索引。
REGISTRY 为注册表数据建立索引。
REGISTRY_AND_SHADOW 为注册表和事物影子数据建立索引。

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

属性 有效值 描述
thingConnectivityIndexingMode 未指定。 不为事物连接数据建立索引。
OFF 不为事物连接数据建立索引。
STATUS 为事物连接数据建立索引。

deviceDefenderIndexingMode 属性指定是否为 Device Defender 违规数据建立索引。

属性 有效值 描述
deviceDefenderIndexingMode 未指定。 没有对 Device Defender 违规数据建立索引。
OFF 没有对 Device Defender 违规数据建立索引。
违规 对 Device Defender 违规数据建立索引。

namedShadowIndexingMode 属性指定是否为命名影子数据建立索引。

属性 有效值 描述
namedShadowIndexingMode 未指定。 没有对命名影子数据建立索引。
OFF 没有对命名影子数据建立索引。
对命名影子数据建立了索引。
注意

要选择要添加到实例集索引配置的命名影子,请将 namedShadowIndexingMode 设置为 ON并在 filter 中指定命名的影子名称。

托管字段和自定义字段

托管字段

托管字段包含与事物、事物组、设备影子、设备连接和 Device Defender 违规关联的数据。Amazon IoT 定义了托管字段中的数据类型。您可以在创建 IoT 事物时指定每个托管字段的值。例如,事物名称、事物组和事物描述都是托管字段。机群索引服务根据您指定的索引模式为托管字段建立索引。托管字段无法更改或显示在 customFields 中。

自定义字段

您可以通过创建自定义字段来对属性、Device Shadow 数据和 Device Defender 违规数据进行汇总来进行索引。customFields 属性是字段名称和数据类型对的列表。您可以根据数据类型执行聚合查询。您选择的索引模式会影响可以在 customFields 中指定的字段。例如,如果您指定 REGISTRY 索引模式,则无法从事物影子中指定字段。您可以使用更新索引配置 CLI 命令创建或更新自定义字段的(请参阅更新索引配置示例中的示例命令)。有关更多信息,请参阅自定义字段

更新索引配置示例

您可以使用 Amazon 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" } }

要更新自定义字段,可以运行更新索引配置命令。示例如下:

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" }

首次启用机群索引时,Amazon IoT 将构建您的索引。如果 indexStatus 处于 BUILDING 状态,您无法查询索引。事物索引的 schema 指示将对什么类型的数据 (REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS) 建立索引。

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

根据配置的数据源,您可以在模式字段中看到不同的值。下表显示了不同的模式值和相应的说明:

Schema 描述
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 来指示设备是否连接到 Amazon 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 }

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

重要

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

限制和局限性

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 创建一个使用未在您的 Amazon IoT 账户中注册的事物名称的影子,则不会为该影子中的字段编制索引。这适用于经典的未命名影子和命名影子。

数字值

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

Null 值

未对 Null 值建立索引。

最大值

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

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

Authorization

您可以在 Amazon 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)。

注意

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