Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# Consulta de datos agregados
<a name="index-aggregate"></a>

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

**nota**  
 Si hay problemas relacionados con valores faltantes o inesperados en la agregación APIs, consulta la [guía de solución de problemas de indexación de flotas](fleet-indexing-troubleshooting.md). 

## GetStatistics
<a name="get-statistics"></a>

La [GetStatistics](https://docs.aws.amazon.com/iot/latest/apireference/API_GetStatistics.html)API y el comando **get-statistics** CLI devuelven el recuento, el promedio, 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:

`index-name`  
El nombre del índice que se buscará. El valor predeterminado es `AWS_Things`.

`query-string`  
La consulta utilizada para buscar el índice. Puede especificar si desea `"*"` obtener el recuento de todos los elementos indexados de su. Cuenta de AWS

`aggregationField`  
(Opcional) El campo que se va a agregar. Este campo debe ser un campo administrado o personalizado definido al llamar a **update-indexing-configuration**. Si no especifica un campo de agregación, se utiliza `registry.version` como el campo de agregación.

`query-version`  
La versión de la consulta que se va a utilizar. El valor predeterminado es `2017-09-30`.

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

### GetStatistics con valores de cadena
<a name="string-aggregation"></a>

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
<a name="boolean-aggregation"></a>

Cuando llama a `GetStatistics` con un campo de agregación booleano:
+ AVERAGE es el porcentaje de dispositivos que coinciden con la consulta.
+ MINIMUM es 0 o 1 de acuerdo con las siguientes reglas:
  + Si todos los valores del campo de agregación son `false`, MINIMUM es 0.
  + Si todos los valores del campo de agregación son `true`, MINIMUM es 1.
  + Si los valores del campo de agregación son una mezcla de `false` y `true`, MINIMUM es 0.
+ MAXIMUM es 0 o 1 de acuerdo con las siguientes reglas:
  + Si todos los valores del campo de agregación son `false`, MAXIMUM es 0.
  + Si todos los valores del campo de agregación son `true`, MAXIMUM es 1.
  + Si los valores del campo de agregación son una mezcla de `false` y `true`, MAXIMUM es 1.
+ SUM es la suma del entero equivalente de los valores booleanos.
+ COUNT es el recuento de objetos que coinciden con los criterios de la cadena de consulta y contienen un valor de campo de agregación válido.

### GetStatistics con valores numéricos
<a name="numerical-aggregation"></a>

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

count  
El número de objetos que coinciden con los criterios de la cadena de consulta y contienen un valor de campo de agregación válido.

average  
El promedio de los valores numéricos que coinciden con la consulta.

sum  
La suma de los valores numéricos que coinciden con la consulta.

minimum  
El menor de los valores numéricos que coinciden con la consulta.

maximum  
El mayor de los valores numéricos que coinciden con la consulta.

sumOfSquares  
La suma de los cuadrados de los valores numéricos que coinciden con la consulta.

variance  
La varianza de los valores numéricos que coinciden con la consulta. La varianza de un conjunto de valores es la media de los cuadrados de las diferencias de cada valor con respecto al valor medio del conjunto.

stdDeviation  
La desviación estándar de los valores numéricos que coinciden con la consulta. La desviación estándar de un conjunto de valores es una medida de la distribución de los 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
<a name="get-cardinality"></a>

La [GetCardinality](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCardinality.html)API y el comando **get-cardinality** 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
}
```

**get-cardinality** siempre devuelve `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:

`index-name`  
El nombre del índice que se buscará. El valor predeterminado es `AWS_Things`.

`query-string`  
La consulta utilizada para buscar el índice. Puede especificar si desea `"*"` obtener el recuento de todos los elementos indexados de su Cuenta de AWS.

`aggregationField`  
El campo que se va a agregar.

`query-version`  
La versión de la consulta que se va a utilizar. El valor predeterminado es `2017-09-30`.

## GetPercentiles
<a name="get-percentiles"></a>

La [GetPercentiles](https://docs.aws.amazon.com/iot/latest/apireference/API_GetPercentiles.html)API y el comando **get-percentiles** CLI agrupan 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:

`index-name`  
El nombre del índice que se buscará. El valor predeterminado es `AWS_Things`.

`query-string`  
La consulta utilizada para buscar el índice. Puede especificar si desea `"*"` obtener el recuento de todos los elementos indexados de su. Cuenta de AWS

`aggregationField`  
El campo que se va a agregar, que debe ser del tipo `Number`.

`query-version`  
La versión de la consulta que se va a utilizar. El valor predeterminado es `2017-09-30`.

`percents`  
(Opcional) Puede utilizar este parámetro para especificar grupos de percentiles personalizados.

## GetBucketsAggregation
<a name="get-buckets"></a>

La [GetBucketsAggregation](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html)API y el comando **get-buckets-aggregation** CLI devuelven una lista de depósitos y el número total de elementos que se ajustan a los criterios de la cadena de consulta.

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

```
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:

`index-name`  
El nombre del índice que se buscará. El valor predeterminado es `AWS_Things`.

`query-string`  
La consulta utilizada para buscar el índice. Puede especificar si desea `"*"` obtener el recuento de todos los elementos indexados de su. Cuenta de AWS

`aggregation-field`  
El campo que se va a agregar.

`buckets-aggregation-type`  
El control básico de la forma de la respuesta y el tipo de agregación de buckets que se va a realizar.

## Autorización
<a name="index-aggregate-authorization"></a>

Puede especificar el índice de grupos de cosas como un ARN de recurso en una acción de AWS IoT política, de la siguiente manera.


| Action | Recurso | 
| --- | --- | 
|  `iot:GetStatistics`  |  El ARN de un índice (por ejemplo, `arn:aws:iot:your-aws-region:index/AWS_Things` o `arn:aws:iot:your-aws-region:index/AWS_ThingGroups`).  |