AWS IoT
开发人员指南
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

机群索引服务

机群索引是一项托管服务,让您可以对云中的注册表和影子数据进行索引编制和搜索。设置机群索引之后,这项服务将管理对您的所有注册表和影子更新的索引编制。您可以使用基于流行的开源搜索引擎 Apache Lucene 的简单查询语言,在这些数据中搜索。

要开始使用,请启用索引,此时 AWS IoT 将为您的事物创建索引。在索引处于活动状态之后,您可以对索引运行查询。AWS IoT 使用您最新的数据保持索引的持续更新。

您可以使用 AWS IoT 控制台管理您的索引配置和运行您的搜索查询。如果您更喜欢以编程方式访问,则可以使用 AWS 开发工具包或 AWS CLI。

请注意,除了 AWS IoT 服务的标准费用之外,使用此服务需要额外支付费用,这些费用在 AWS IoT 设备管理定价中进行了简要介绍。

管理索引

AWS_Things 是为您的所有事物创建的索引。您可以控制仅为注册表数据编制索引还是同时为注册表和影子数据编制索引。

启用索引

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

以下命令说明了如何使用 get-indexing-configuration CLI 命令来检索当前事物索引配置:

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

您可以使用 AWS IoT update-indexing-configuration CLI 命令更新事物索引配置:

aws iot update-indexing-configuration --thing-indexing-configuration thingIndexingMode=REGISTRY_AND_SHADOW

thing-indexing-configuration 的有效值为:

OFF

无索引/删除索引。

REGISTRY

创建或配置 AWS_Things 索引以仅为注册表数据编制索引。

REGISTRY_AND_SHADOW

创建或配置 AWS_Things 索引以仅为注册表和影子数据编制索引。

注意

影子通常是加密的。但是,如果您决定在 AWS_Things 索引中包含影子,数据将被解密以便为影子编制索引。

描述索引

以下命令说明了如何使用 describe-index CLI 命令来检索索引的当前状态:

aws iot describe-index --index-name "AWS_Things" { "indexName": "AWS_Things", "indexStatus": "BUILDING", "schema": "REGISTRY_AND_SHADOW" }

首次启用索引时,AWS IoT 将构建您的索引。如果 indexStatus 为 BUILDING,您无法查询索引。架构指示要索引的数据类型是 REGISTRY 还是 REGISTRY_AND_SHADOW

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

什么是编制索引

请注意以下限制:

具有复杂类型的影子字段:

只有字段的值是简单类型或完全由简单类型组成的数组时,才会对影子字段编制索引。(“简单类型”是指一个字符串、数字或文本 truefalsenull 之一。) 如果一个字段的值本身就是一个 JSON 对象或一个包含对象的数组,则不会在该字段上进行索引编制。例如,给定的影子状态:

{ "state": { "reported": { "switched": "ON", "colors": [ "RED", "GREEN", "BLUE" ], "palette": [ { "name": "RED", "intensity": 124 }, { "name": "GREEN", "intensity": 68 }, { "name": "BLUE", "intensity": 201 } ] } } }

字段 "palette" 的值将不会编制索引,因为它是一个其项目为“对象”的数组。字段“颜色”的值将会编制索引,因为数组中的每个值都是一个字符串。

影子元数据:

影子的元数据部分中的字段编制了索引,但仅当影子的 "state" 部分中的相应字段编制了索引时才这样。(在上面的示例中,影子的元数据部分中的“调色板”字段不会也编制索引。)

已注销的影子:

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

数字值:

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

查询索引

以下命令说明了如何使用 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" } }, { "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 } }], "nextToken":"AQFCuvk7zZ3D9pOYMbFCeHbdZ+h=G" }

查询语法

可使用类似 Lucene 的查询语法来指定查询。有关更多信息,请参阅 Apache 网站上的 Lucene 查询语法概览

Lucene 查询语法支持以下功能:

  • 术语和短语

  • 搜索字段

  • 前缀搜索

  • 范围搜索

  • 布尔运算符 AND、OR、NOT 和 –

  • 分组

  • 字段分组

  • 对特殊字符转义

Lucene 查询语法不支持以下功能:

  • 前导通配符搜索 (例如“*xyz”),搜索“*”将匹配所有事物

  • 正则表达式

  • 提升

  • 排名

  • 模糊搜索

  • 近似搜索

  • 排序

  • 聚合

关于查询语言需要注意的几点:

  • 默认运算符为 AND。查询“thingName:abc thingType:xyz”等同于“thingName:abc AND thingType:xyz”。

  • 如果未指定字段,AWS IoT 将在所有字段中搜索术语。

  • 所有字段名称均区分大小写。

  • 搜索不区分大小写。单词使用空格字符分隔,如 Java 的 Character.isWhitespace(int) 中所定义。

  • 影子数据的索引编制包括“reported”、“desired”、“delta”和“metadata”部分。

  • 影子和注册表版本不可搜索,但在响应中提供。

  • 查询中术语数量上限为 5 个。

示例查询

查询在查询字符串中使用类似于 Lucene 的查询语法指定,并传递到 API。SearchIndex下表列出了一些示例查询字符串:

查询字符串 结果

"abc"

在任意注册表或影子字段中查询“abc”。

"thingName:myThingName"

查询名为“myThingName”的事物。

"thingName:my*"

查询名称以“my”开头的事物。

"thingName:ab?"

查询名称为“ab”以及另外一个字符的事物,例如:“aba”、“abb”、“abc”等。

"attributes.myAttribute:75"

查询属性名为“MyAttribute”且属性值为 75 的事物。

"attributes.myAttribute:[75 TO 80]"

查询属性名为“MyAttribute”,且属性值在数字范围 (75 – 80,含) 之内的事物。

"attributes.myAttribute:{75 TO 80]"

查询属性名为“MyAttribute”,且属性值在数字范围 (大于 75 且小于等于 <80) 之内的事物。

'attributes.serialNumber["abcd" TO "abcf"]'

查询属性名为“serialNumber”,且属性值在字母数字字符串范围之内的事物。此查询将返回属性名为“serialNumber”,且其值为“abcd”、“abce”或“abcf”的事物。

"attributes.myAttribute:i*t"

查询属性名为“MyAttribute”,且其值为以“i”开头、以“t”结尾、中间有任意数量字符的事物。

"attributes.attr1:abc AND attributes.attr2<5 NOT attributes.attr3>10

使用布尔表达式组合术语来查询事物。此查询将返回具有下列特征的事物:属性名为“attr1”且值为“abc”;属性名为“attr2”且值小于 5;以及属性名为“attr3”且值不大于 10。

"shadow.hasDelta:true"

查询其影子具有增量元素的事物。

"-attributes.model:legacy"

查询属性模型不是“legacy”的事物。

"shadow.reported.stats.battery:(>70 AND <100) (v2 | v3) -attributes.model:legacy"

查询具有以下特征的事物:

  • 事物的影子 stats.battery 属性具有介于 70 到 100 之间的值。

  • 文本“v2”或“v3”出现在事物的名称、类型名称或属性值中。

  • 事物的 model 属性未设置为“legacy”。

"shadow.reported.myvalues:2"

查询具有以下特征的事物:影子的“reported”部分中的 myvalues 数组包含值 2。

"shadow.reported.location:* NOT shadow.desired.stats.battery:*"

查询具有以下特征的事物:

  • 影子的 reported 部分中存在 location 属性。

  • 影子的 desired 部分中不存在 stats.battery 属性。

授权

您可以指定事物索引作为 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)。

本页内容: