Consulta de datos agregados

AWS IoT proporciona cuatro API (GetStatistics, GetCardinality, GetPercentiles y GetBucketsAggregation) que le permiten buscar datos agregados en su flota de dispositivos.

GetStatistics

La API GetStatistics y el comando get-statistics de la CLI devuelven el recuento, la media, la suma, el mínimo, el máximo, la suma de los cuadrados, la varianza y la desviación estándar del campo agregado especificado.

El comando get-statistics de la CLI usa los siguientes parámetros:

El tipo de campo de agregación puede afectar a las estadísticas devueltas.

GetStatistics con valores de cadena

Si realiza la agregación en un campo de cadena, la llamada a GetStatistics devuelve el número de dispositivos que tienen atributos que coinciden con la consulta. Por ejemplo:

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

Este comando devuelve el número de dispositivos que contienen un atributo llamado stringAttribute:

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

GetStatistics con valores booleanos

Cuando llama a GetStatistics con un campo de agregación booleano:

GetStatistics con valores numéricos

Cuando se llama a GetStatistics y se especifica un campo de agregación de tipo Number, GetStatistics devuelve los siguientes valores:

El siguiente ejemplo muestra cómo llamar a get-statistics con un campo numérico personalizado.

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 los campos de agregación numérica, si los valores del campo superan el valor «double» máximo, los valores de las estadísticas están vacíos.

GetCardinality

La API GetCardinality y el comando get-cardinality de la CLI devuelven el recuento aproximado de valores únicos que coinciden con la consulta. Por ejemplo, es posible que desee encontrar el número de dispositivos con niveles de batería inferiores al 50 por ciento:

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

Este comando devuelve el número de objetos con niveles de batería de más del 50 por ciento:

{
    "cardinality": 100
}

cardinality siempre devuelve get-cardinality, aunque no haya campos coincidentes. Por ejemplo:

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

{
    "cardinality": 0
}

El comando get-cardinality de la CLI usa los siguientes parámetros:

GetPercentiles

La API GetPercentiles y el comando get-percentiles de la CLI agrupa los valores agregados que coinciden con la consulta en grupos de percentiles. Los grupos de percentiles predeterminados son: 1,5,25,50,75,95,99, aunque puede especificar los suyos propios cuando llame a GetPercentiles. Esta función devuelve un valor para cada grupo de percentiles especificado (o para los grupos de percentiles predeterminados). El grupo de percentiles "1" contiene el valor agregado del campo que se obtiene aproximadamente en el uno por ciento de los valores que coinciden con la consulta. El grupo de percentiles "5" contiene el valor agregado del campo que se obtiene en aproximadamente el cinco por ciento de los valores que coinciden con la consulta, y así sucesivamente. El resultado es una aproximación: cuantos más valores coincidan con la consulta, más precisos serán los valores de percentil.

El siguiente ejemplo muestra cómo llamar al comando get-percentiles de la 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
        }
    ]
}

El siguiente comando muestra la salida devuelta get-percentiles cuando no hay documentos coincidentes.

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

{
    "percentiles": []
}

El comando get-percentile de la CLI usa los siguientes parámetros:

GetBucketsAggregation

La API GetBucketsAggregation y el comando dela CLI get-buckets-aggregation devuelven una lista de buckets y el número total de objetos que se ajustan a los criterios de la cadena de consulta.

El siguiente ejemplo muestra cómo llamar al comando de la CLI get-buckets-aggregation.

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

Este comando devuelve la siguiente salida:

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

El comando get-buckets-aggregation de la CLI usa los siguientes parámetros:

Autorización

Puede especificar el índice de grupos de objetos como un ARN del recurso en una acción de política de AWS IoT, como en el siguiente ejemplo.