查询聚合数据 - AWS IoT
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

查询聚合数据

AWS IoT 提供了三个 API(GetStatisticsGetCardinalityGetPercentiles),允许您搜索设备队列以获取聚合数据。

GetStatistics

GetStatistics API 和 get-statistics CLI 命令返回指定聚合字段的计数、平均值、总和、最小值、最大值、平方和、方差和标准差。

get-statistics CLI 命令使用以下参数:

index-name

要搜索的索引的名称。默认值为 AWS_Things

query-string

用于搜索索引的查询。您可以为查询指定 "*" 来获取您的 AWS 账户中所有已编制索引的事物的计数。

aggregationField

可选。要聚合的字段。此字段必须是在调用 update-indexing-configuration 时定义的托管字段或自定义字段。如果不指定聚合字段,则 registry.version 用作聚合字段。

query-version

要使用的查询的版本。默认值为 2017-09-30

聚合字段的类型可能会影响返回的统计信息。

具有字符串值的 GetStatistics

如果在字符串字段上进行聚合,则调用 GetStatistics 会返回具有与查询匹配的属性的设备计数。例如:

aws iot get-statistics --aggregation-field 'attributes.stringAttribute' --query-string '*'

此命令会返回包含 stringAttribute 属性的设备数量:

{ "statistics": { "count": 3 } }

具有布尔值的 GetStatistics

当您使用布尔聚合字段调用 GetStatistics 时:

  • AVERAGE 是匹配查询的设备的百分比。

  • 根据以下规则,MINIMUM 为 0 或 1:

    • 如果聚合字段的所有值均为 false,则 MINIMUM 为 0。

    • 如果聚合字段的所有值均为 true,则 MINIMUM 为 1。

    • 如果聚合字段的值既有 false 又有 true,则 MINIMUM 为 0。

  • 根据以下规则,MAXIMUM 为 0 或 1:

    • 如果聚合字段的所有值均为 false,则 MAXIMUM 为 0。

    • 如果聚合字段的所有值均为 true,则 MAXIMUM 为 1。

    • 如果聚合字段的值既有 false 又有 true,则 MAXIMUM 为 1。

  • SUM 是等效于布尔值的整数的总和。

  • COUNT 是与查询匹配的事物的数量。

具有数值的 GetStatistics

调用 GetStatistics 并指定 Number 类型的聚合字段时,GetStatistics 返回以下值:

count

具有与查询匹配的字段的设备数量。

average

与查询匹配的数值的平均值。

sum

与查询匹配的数值的总和。

minimum

与查询匹配的数值中的最小值。

maximum

与查询匹配的数值中的最大值。

sumOfSquares

与查询匹配的数值的平方和。

variance

与查询匹配的数值的方差。一组值的方差是每个值与该组值平均值之间差值的平方的平均值。

stdDeviation

与查询匹配的数值的标准差。一组值的标准差用于衡量值的分布程度。

以下示例演示了如何使用数值自定义字段调用 get-statistics

aws iot get-statistics --aggregation-field 'attributes.numericAttribute2' --query-string '*'

{ "statistics": { "count": 3, "average": 33.333333333333336, "sum": 100.0, "minimum": -125.0, "maximum": 150.0, "sumOfSquares": 43750.0, "variance": 13472.22222222222, "stdDeviation": 116.06990230986766 } }

对于数值聚合字段,如果字段值超过最大双精度值,则统计值为空

GetCardinality

GetCardinality API 和 get-cardinality CLI 命令返回与查询匹配的唯一值的近似计数。例如,您可能需要查找电池电量低于 50% 的设备数量:

aws iot get-cardinality --index-name AWS_Things --query-string "batterylevel > 50" --aggregation-field "shadow.reported.batterylevel"

此命令返回电池电量超过 50% 的事物数量:

{ "cardinality": 100 }

即使没有匹配字段,get-cardinality 也始终返回 cardinality。例如:

aws iot get-cardinality --query-string "thingName:Non-existent*" --aggregation-field "attributes.customField_STR"

{ "cardinality": 0 }

get-cardinality CLI 命令使用以下参数:

index-name

要搜索的索引的名称。默认值为 AWS_Things

query-string

用于搜索索引的查询。您可以为查询指定 "*" 来获取您的 AWS 账户中所有已编制索引的事物的计数。

aggregationField

要聚合的字段。

query-version

要使用的查询的版本。默认值为 2017-09-30

GetPercentiles

GetPercentiles API 和 get-percentiles CLI 命令将与查询匹配的聚合值分组为百分位数分组。默认百分位数分组为:1,5,25,50,75,95,99,不过您可以在调用 GetPercentiles 时指定自己的百分位数分组。此函数为指定的每个百分位数组(或默认百分位数分组)返回一个值。百分位数组“1”包含在与查询匹配的值的大约 1% 中出现的聚合字段值。百分位数组“5”包含在与查询匹配的值的大约 5% 中出现的聚合字段值,以此类推。结果是近似值,与查询匹配的值越多,百分位数值就越准确。

以下示例演示了如何调用 get-percentiles CLI 命令。

aws iot get-percentiles --query-string "thingName:*" --aggregation-field "attributes.customField_NUM" --percents 10 20 30 40 50 60 70 80 90 99

{ "percentiles": [ { "value": 3.0, "percent": 80.0 }, { "value": 2.5999999999999996, "percent": 70.0 }, { "value": 3.0, "percent": 90.0 }, { "value": 2.0, "percent": 50.0 }, { "value": 2.0, "percent": 60.0 }, { "value": 1.0, "percent": 10.0 }, { "value": 2.0, "percent": 40.0 }, { "value": 1.0, "percent": 20.0 }, { "value": 1.4, "percent": 30.0 }, { "value": 3.0, "percent": 99.0 } ] }

以下命令显示没有匹配文档时从 get-percentiles 返回的输出。

aws iot get-percentiles --query-string "thingName:Non-existent*" --aggregation-field "attributes.customField_NUM"

{ "percentiles": [] }

get-percentile CLI 命令使用以下参数:

index-name

要搜索的索引的名称。默认值为 AWS_Things

query-string

用于搜索索引的查询。您可以为查询指定 "*" 来获取您的 AWS 账户中所有已编制索引的事物的计数。

aggregationField

要聚合的字段,必须为 Number 类型。

query-version

要使用的查询的版本。默认值为 2017-09-30

percents

可选。您可以使用此参数指定自定义百分位数分组。

授权

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

操作 资源

iot:GetStatistics

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