Consulta de dados agregados

AWS IoT fornece quatro APIs (GetStatistics,GetCardinality,GetPercentiles, eGetBucketsAggregation) que permitem pesquisar dados agregados em sua frota de dispositivos.

nota

Para problemas com valores ausentes ou inesperados para a agregaçãoAPIs, leia o guia de solução de problemas de indexação de frotas.

GetStatistics

O get-statistics CLI comando GetStatisticsAPIand the retorna a contagem, a média, a soma, o mínimo, o máximo, a soma dos quadrados, a variância e o desvio padrão para o campo agregado especificado.

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

index-name

O nome do índice a ser pesquisado. O valor padrão é AWS_Things.

query-string

A consulta usada para pesquisar o índice. Você pode especificar "*" para obter a contagem de todas as coisas indexadas em seu Conta da AWS.

aggregationField

(Opcional) O campo a ser agregado. Esse campo deve ser um campo gerenciado ou personalizado definido ao chamar update-indexing-configuration. Se você não especificar um campo de agregação, registry.version será usado como o campo de agregação.

query-version

A versão da consulta a ser usada. O valor padrão é 2017-09-30.

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 booleanos

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

• AVERAGEé a porcentagem de dispositivos que correspondem à consulta.

• MINIMUMé 0 ou 1 de acordo com as seguintes regras:

  • Se todos os valores do campo de agregação foremfalse, MINIMUM será 0.

  • Se todos os valores do campo de agregação foremtrue, MINIMUM será 1.

  • Se os valores do campo de agregação forem uma mistura de false etrue, MINIMUM será 0.

• MAXIMUMé 0 ou 1 de acordo com as seguintes regras:

  • Se todos os valores do campo de agregação foremfalse, MAXIMUM será 0.

  • Se todos os valores do campo de agregação foremtrue, MAXIMUM será 1.

  • Se os valores do campo de agregação forem uma mistura de false etrue, MAXIMUM é 1.

• SUMé a soma do equivalente inteiro dos valores booleanos.

• COUNTé a contagem de itens que correspondem aos critérios da sequência de caracteres de consulta e contêm um valor de campo de agregação válido.

GetStatistics com valores numéricos

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

contagem

A contagem de objetos que correspondem aos critérios da string de consulta e contêm um valor de campo de agregação válido.

média

A média dos valores numéricos que correspondem à consulta.

soma

A soma dos valores numéricos que correspondem à consulta.

mínimo

O menor dos valores numéricos que correspondem à consulta.

máximo

O maior dos valores numéricos que correspondem à consulta.

sumOfSquares

A soma dos quadrados dos valores numéricos que correspondem à consulta.

variância

A variação dos valores numéricos que correspondem à consulta. A variância de um conjunto de valores é a média dos quadrados das diferenças de cada valor em relação ao valor médio do conjunto.

stdDeviation

O desvio padrão dos valores numéricos que correspondem à consulta. O desvio padrão de um conjunto de valores é uma medida de como os valores estão distribuídos.

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

O get-cardinality CLI comando GetCardinalityAPIand the retorna 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 CLI da get-cardinality usa os seguintes parâmetros:

index-name

O nome do índice a ser pesquisado. O valor padrão é AWS_Things.

query-string

A consulta usada para pesquisar o índice. Você pode especificar "*" para obter a contagem de todas as coisas indexadas em seu Conta da AWS.

aggregationField

O campo a ser agregado.

query-version

A versão da consulta a ser usada. O valor padrão é 2017-09-30.

GetPercentiles

O get-percentiles CLI comando GetPercentilesAPIe o agrupa os valores agregados que correspondem à consulta em agrupamentos de percentis. 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 get-percentiles CLI comando.

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 CLI da get-percentile usa os seguintes parâmetros:

index-name

O nome do índice a ser pesquisado. O valor padrão é AWS_Things.

query-string

A consulta usada para pesquisar o índice. Você pode especificar "*" para obter a contagem de todas as coisas indexadas em seu Conta da AWS.

aggregationField

O campo a ser agregado, que deve ser do tipo Number.

query-version

A versão da consulta a ser usada. O valor padrão é 2017-09-30.

percents

(Opcional) você pode usar esse parâmetro para especificar agrupamentos de percentil personalizados.

GetBucketsAggregation

O get-buckets-aggregation CLI comando GetBucketsAggregationAPIand the retorna uma lista de compartimentos e o número total de itens que se encaixam nos critérios da sequência de caracteres de consulta.

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

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 get-buckets-aggregation CLI comando usa os seguintes parâmetros:

index-name

O nome do índice a ser pesquisado. O valor padrão é AWS_Things.

query-string

A consulta usada para pesquisar o índice. Você pode especificar "*" para obter a contagem de todas as coisas indexadas em seu Conta da AWS.

aggregation-field

O campo a ser agregado.

buckets-aggregation-type

O controle básico da forma de resposta e do tipo de agregação do bucket a ser executado.

Autorização

Você pode especificar o índice de grupos de coisas como um recurso ARN em uma ação AWS IoT política, da seguinte maneira.

Ação	Recurso
iot:GetStatistics	Um índice ARN (por exemplo, arn:aws:iot:your-aws-region:index/AWS_Things ouarn:aws:iot:your-aws-region:index/AWS_ThingGroups).