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

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

管理事物索引

AWS_Things 是为您的所有事物创建的索引。您可以从以下数据源控制要索引的内容:Amazon IoT 注册表数据,Amazon IoT Device Shadow数据,Amazon IoT 连接数据以及Amazon 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:控制是否为注册表或影子编制索引。如果设置thingIndexingModeOFF,则禁用事物索引。

  • thingConnectivityIndexingMode:指定是否对事物连接数据进行索引。

  • deviceDefenderIndexingMode:指定是否为设备防御者违规数据编制索引。

  • namedShadowIndexingMode:指定是否对命名的影子数据进行索引。要选择要添加到实例集索引配置的命名影子,请将 namedShadowIndexingMode 设置为 ON并在 filter 中指定命名的影子名称。

下表显示了每种索引模式的有效值以及为每个值编制索引的数据源。

属性 有效值 注册表 影子 连接 DD 违规行为 命名的影子
thingIndexingMode 关闭
REGISTRY
REGISTRY_AND_SHADOW
thingConnectivityIndexingMode 未指定。
关闭
STATUS
deviceDefenderIndexingMode 未指定。
关闭
违规
namedShadowIndexingMode 未指定。
关闭

托管字段和自定义字段

托管字段

托管字段包含与事物、事物组、设备影子、设备连接和 Device Defender 违规相关的数据。 Amazon IoT 定义托管字段中的数据类型。您可以在创建 Amazon 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) 中指定了 GeoLocation 对象:

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

有关更多信息,请参阅《Amazon IoTAPI IndexingFilter参考》。

更新索引配置示例

要更新您的索引配置,请使用 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" } }

要更新自定义字段,可以运行 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 时指定所有自定义字段。

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

更改索引模式时,请使用新的索引模式以确保所有自定义字段均有效。例如,如果从 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,同时正在重新生成索引,则您可以查询注册表数据,包括最新的更新。但是,在重新生成操作完成之前,无法查询影子数据。生成或重新生成索引所需的时间量取决于数据量。

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

架构 描述
关闭 没有配置或索引数据源。
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" 字段也不会编制索引。)

未注册的设备

实例集索引对设备的连接状态编制索引,该设备的连接 clientId注册表中已注册事物的 thingName 相同。

未注册的影子

如果您使用UpdateThingShadow尚未在 Amazon IoT 账户中注册的事物名称创建影子,则不会为该影子中的字段编制索引。这适用于经典的未命名影子和命名影子。

数字值

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

Null 值

未对 Null 值建立索引。

最大值

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

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

授权

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

注意

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