Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

查询聚合数据

Amazon IoT 提供了四个 API（GetStatistics、GetCardinality、GetPercentiles 和 GetBucketsAggregation），允许您搜索设备机群以获取聚合数据。

GetStatistics

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

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

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

具有字符串值的 GetStatistics

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

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

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

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

具有布尔值的 GetStatistics

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

具有数值的 GetStatistics

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

以下示例演示了如何使用数值自定义字段调用 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 命令使用以下参数：

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 命令使用以下参数：

GetBucketsAggregation

GetBucketsAggregation API 和get-buckets-aggregation CLI 命令返回存储桶列表以及符合查询字符串条件的内容总数。

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

aws iot get-buckets-aggregation --query-string '*' --index-name AWS_Things --aggregation-field 'shadow.reported.batterylevelpercent' --buckets-aggregation-type 'termsAggregation={maxBuckets=5}'

此命令将返回以下：

{
    "totalCount": 20,
    "buckets": [
        {
            "keyValue": "100",
            "count": 12
        },
        {
            "keyValue": "90",
            "count": 5
        },
        {
            "keyValue": "75",
            "count": 3
        }
    ]
}

get-buckets-aggregation CLI 命令使用以下参数：

Authorization

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