Consulta de dados agregados

O AWS IoT fornece quatro APIs (GetStatistics, GetCardinality, GetPercentiles, e GetBucketsAggregation) que permitem que você pesquise dados agregados em sua frota de dispositivos.

GetStatistics

A API GetStatistics e o comando get-statistics da CLI retornam a contagem, a média, a soma, o mínimo, o máximo, a soma de quadrados, a variância e o desvio padrão para o campo agregado especificado.

O comando da CLI get-statistics usa os seguintes parâmetros:

O tipo de campo de agregação pode afetar as estatísticas retornadas.

GetStatistics com valores de string

Se você agregar em um campo de string, chamar GetStatistics retornará uma contagem de dispositivos que têm atributos que correspondem à consulta. Por exemplo:

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

Esse comando retorna o número de dispositivos que contêm um atributo chamado stringAttribute:

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

GetStatistics com valores boolianos

Quando você chama GetStatistics com um campo de agregação booliano:

GetStatistics com valores numéricos

Quando você chama GetStatistics e especifica um campo de agregação do tipo Number, GetStatistics retorna os seguintes valores:

O exemplo a seguir mostra como chamar get-statistics com um campo personalizado numérico.

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
  }
}

Para campos de agregação numéricos, se os valores de campo excederem o valor duplo máximo, os valores estatísticos estarão vazios.

GetCardinality

A API GetCardinality e o comando get-cardinality da CLI retornam a contagem aproximada de valores exclusivos que correspondem à consulta. Por exemplo, você pode querer encontrar o número de dispositivos com níveis de bateria inferiores a 50%:

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

Este comando retorna o número de itens com níveis de bateria superiores a 50%:

{
    "cardinality": 100
}

cardinality é sempre retornado por get-cardinality mesmo se não houver campos correspondentes. Por exemplo:

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

{
    "cardinality": 0
}

O comando da CLI get-cardinality usa os seguintes parâmetros:

GetPercentiles

A API GetPercentiles e o comando get-percentiles da CLI agrupam os valores agregados que correspondem à consulta em agrupamentos de percentil. Os agrupamentos de percentil padrão são: 1, 5, 25, 50, 75, 95, 99, embora você possa especificar o seu próprio quando chamar GetPercentiles. Esta função retorna um valor para cada grupo de percentis especificado (ou os agrupamentos de percentil padrão). O grupo de percentis “1” contém o valor de campo agregado que ocorre em aproximadamente um por cento dos valores que correspondem à consulta. O grupo de percentil “5” contém o valor de campo agregado que ocorre em aproximadamente cinco por cento dos valores que correspondem à consulta, e assim por diante. O resultado é uma aproximação. Quanto mais valores correspondem à consulta, mais precisos os valores do percentil.

O exemplo a seguir mostra como chamar o comando get-percentiles da 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
        }
    ]
}

O comando a seguir mostra a saída retornada de get-percentiles quando não há documentos correspondentes.

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

{
    "percentiles": []
}

O comando da CLI get-percentile usa os seguintes parâmetros:

GetBucketsAggregation

A API GetBucketsAggregation e o comando get-buckets-aggregation da CLI retornam uma lista de buckets e o número total de objetos que se encaixam nos critérios da string de consulta.

O exemplo a seguir mostra como chamar o comando get-buckets-aggregation da CLI.

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

O comando retorna os seguintes:

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

O comando get-buckets-aggregation da CLI usa os seguintes parâmetros:

Autorização

Você pode especificar o índice de grupo de objetos como um ARN do recurso em uma ação de política da AWS IoT, da seguinte forma.