集計データのクエリ - AWS IoT Core
GetStatisticsGetCardinalityGetPercentilesGetBucketsAggregation認証

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

集計データのクエリ

AWS IoT にはGetStatisticsGetCardinalityGetPercentiles、デバイス群から集計データを検索できる 4 つの API (、、およびGetBucketsAggregation) が用意されています。

注記

集約 API の値が不足しているか、予期しない値になっているという問題については、フリートインデックス作成トラブルシューティングガイドを参照してください。

GetStatistics

GetStatisticsget-statisticsAPIと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 ブール値を使用

Boolean 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 は次の値を返します。

数

クエリ文字列条件に一致し、有効な集計フィールドの値を含むモモノの数。

平均

クエリに一致する数値の平均。

sum

クエリに一致する数値の合計。

minimum

クエリに一致する数値のうち最小の値。

maximum

クエリに一致する数値のうち最大値。

sumOfSquares

クエリに一致する数値の二乗の合計。

分散

クエリに一致する数値の分散。値の集合の分散は、集合の平均値からの各値の差の二乗の平均です。

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

GetCardinalityAPI と get-cardinality CLI コマンドは、クエリに一致する一意の値のおおよその数を返します。たとえば、バッテリー残量が 50% 未満のデバイスの数を調べるとします。

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

このコマンドは、バッテリー残量が 50% を超えるものの数を返します。

{
    "cardinality": 100
}

cardinality は、一致するフィールドがない場合でも、常に get-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

GetPercentilesAPI と 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

(オプション) このパラメータを使用して、カスタムのパーセンタイルグループを指定できます。

GetBucketsAggregation

GetBucketsAggregationAPI と 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 コマンドは以下のパラメータを取ります。

index-name

検索を実行するインデックスの名前。デフォルト値は AWS_Things です。

query-string

インデックスを検索するために使用されるクエリ。"*"内のインデックスに登録されているすべてのものの数を取得するように指定できます。 AWS アカウント

aggregation-field

集計するフィールド。

buckets-aggregation-type

レスポンスの形の基本的な制御と実行するバケット集計タイプ。

認証

以下のように、 AWS IoT モノグループインデックスをポリシーアクションのリソース ARN として指定できます。

アクション リソース

iot:GetStatistics

インデックス ARN (例: arn:aws:iot:your-aws-region:index/AWS_Things または arn:aws:iot:your-aws-region:index/AWS_ThingGroups)。