GetStatistics GetCardinality GetPercentiles GetBucketsAggregation Autorizzazione

Interrogazione di dati aggregati

AWS IoT fornisce quattro API (GetStatistics, GetCardinalityGetPercentiles, eGetBucketsAggregation) che consentono di cercare dati aggregati nel parco dispositivi.

Nota

Per problemi con valori mancanti o imprevisti per le API di aggregazione, leggere Fleet indexing troubleshooting guide (Guida alla risoluzione dei problemi di indicizzazione del parco istanze).

GetStatistics

L'GetStatisticsAPI e il comando get-statistics CLI restituiscono il conteggio, la media, la somma, il minimo, il massimo, la somma dei quadrati, la varianza e la deviazione standard per il campo aggregato specificato.

Il comando CLI get-statistics accetta i parametri seguenti:

index-name: Nome dell'indice su cui eseguire una ricerca. Il valore predefinito è AWS_Things.
query-string: La query usata per eseguire la ricerca nell'indice. Puoi specificare di ottenere il conteggio "*" di tutte le cose indicizzate nel tuo. Account AWS
aggregationField: (Facoltativo) Il campo da aggregare. Questo campo deve essere un campo gestito o personalizzato definito quando si chiama update-indexing-configuration. Se non specifichi un campo di aggregazione, viene utilizzato registry.version come campo di aggregazione.
query-version: La versione della query da usare. Il valore predefinito è 2017-09-30.

Il tipo di campo di aggregazione può influenzare le statistiche restituite.

GetStatistics con valori di stringa

Se si aggrega in un campo stringa, la chiamata GetStatistics restituisce un conteggio di dispositivi con attributi che corrispondono alla query. Ad esempio:


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

Questo comando restituisce il numero di dispositivi che contengono un attributo denominato stringAttribute:


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

GetStatistics con valori booleani

Quando chiami GetStatistics con un campo di aggregazione booleano:

AVERAGE è la percentuale di dispositivi che corrispondono alla query.
MINIMUM è 0 o 1 secondo le seguenti regole:
- Se tutti i valori per il campo di aggregazione sono false, MINIMUM è 0.
- Se tutti i valori per il campo di aggregazione sono true, MINIMUM è 1.
- Se i valori per il campo di aggregazione sono una miscela di false e true, MINIMUM è 0.
MAXIMUM è 0 o 1 secondo le seguenti regole:
- Se tutti i valori per il campo di aggregazione sono false, MAXIMUM è 0.
- Se tutti i valori per il campo di aggregazione sono true, MAXIMUM è 1.
- Se i valori per il campo di aggregazione sono una miscela di false e true, MAXIMUM è 1.
SUM è la somma dell'equivalente intero dei valori booleani.
COUNT è il numero di oggetti che corrispondono ai criteri della stringa di query e contengono un valore di campo di aggregazione valido.

GetStatistics con valori numerici

Quando si chiama GetStatistics e si specifica un campo di aggregazione di tipo Number, GetStatistics restituisce i seguenti valori:

count: Numero di oggetti che corrispondono ai criteri della stringa di query e contengono un valore di campo di aggregazione valido.
average: La media dei valori numerici che corrispondono alla query.
sum: La somma dei valori numerici che corrispondono alla query.
minimum: Il più piccolo dei valori numerici che corrisponde alla query.
maximum: Il più grande dei valori numerici che corrisponde alla query.
sumOfSquares: La somma dei quadrati dei valori numerici che corrispondono alla query.
variance: La varianza dei valori numerici che corrispondono alla query. La varianza di un insieme di valori è la media dei quadrati delle differenze di ciascun valore rispetto al valore medio del set.
stdDeviation: La deviazione standard dei valori numerici che corrispondono alla query. La deviazione standard di un insieme di valori è una misura di quanto sono distribuiti i valori.

Nell'esempio seguente viene illustrato come chiamare get-statistics con un campo personalizzato numerico.


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

Per i campi di aggregazione numerica, se i valori dei campi superano il valore doppio massimo, i valori delle statistiche sono vuoti.

GetCardinality

L'GetCardinalityAPI e il comando get-cardinality CLI restituiscono il conteggio approssimativo di valori univoci che corrispondono alla query. Ad esempio, potresti cercare il numero di dispositivi con livelli di batteria inferiori al 50%:


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

Questo comando restituisce il numero di elementi con livelli di batteria oltre il 50%:


{
    "cardinality": 100
}

cardinality viene sempre restituito da get-cardinality anche se non ci sono campi corrispondenti. Ad esempio:


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


{
    "cardinality": 0
}

Il comando CLI get-cardinality accetta i parametri seguenti:

index-name: Nome dell'indice su cui eseguire una ricerca. Il valore predefinito è AWS_Things.
query-string: La query usata per eseguire la ricerca nell'indice. Puoi specificare di "*" ottenere il conteggio di tutte le cose indicizzate nel tuo. Account AWS
aggregationField: Il campo da aggregare.
query-version: La versione della query da usare. Il valore predefinito è 2017-09-30.

GetPercentiles

L'GetPercentilesAPI e il comando get-percentiles CLI raggruppano i valori aggregati che corrispondono alla query in raggruppamenti percentili. I raggruppamenti percentili predefiniti sono: 1, 5, 25, 50, 75, 95, 99, anche se è possibile specificare il proprio quando si chiama GetPercentiles. Questa funzione restituisce un valore per ogni gruppo percentile specificato (o i raggruppamenti percentili predefiniti). Il gruppo percentile "1" contiene il valore del campo aggregato che si verifica in circa l'1% dei valori corrispondenti alla query. Il gruppo percentile "5" contiene il valore del campo aggregato che si verifica in circa il cinque percento dei valori corrispondenti alla query e così via. Il risultato è un'approssimazione, più valori corrispondono alla query, più precisi sono i valori percentili.

Nell'esempio seguente viene illustrato come chiamare il comando CLI get-percentiles.


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

Il comando seguente mostra l'output restituito da get-percentiles quando non ci sono documenti corrispondenti.


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


{
    "percentiles": []
}

Il comando CLI get-percentile accetta i parametri seguenti:

index-name: Nome dell'indice su cui eseguire una ricerca. Il valore predefinito è AWS_Things.
query-string: La query usata per eseguire la ricerca nell'indice. Puoi specificare di "*" ottenere il conteggio di tutte le cose indicizzate nel tuo. Account AWS
aggregationField: Il campo da aggregare, che deve essere di tipo Number.
query-version: La versione della query da usare. Il valore predefinito è 2017-09-30.
percents: (Facoltativo) È possibile utilizzare questo parametro per specificare raggruppamenti percentili personalizzati.

GetBucketsAggregation

L'GetBucketsAggregationAPI e il comando get-buckets-aggregation CLI restituiscono un elenco di bucket e il numero totale di elementi che soddisfano i criteri della stringa di query.

L'esempio seguente mostra come chiamare il comando 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}'

Questo comando restituisce quanto segue:


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

Il comando get-buckets-aggregation CLI accetta i seguenti parametri:

index-name: Nome dell'indice su cui eseguire una ricerca. Il valore predefinito è AWS_Things.
query-string: La query usata per eseguire la ricerca nell'indice. Puoi specificare di "*" ottenere il conteggio di tutte le cose indicizzate nel tuo. Account AWS
aggregation-field: Il campo da aggregare.
buckets-aggregation-type: Il controllo di base della forma di risposta e il tipo di aggregazione del bucket da eseguire.

Autorizzazione

È possibile specificare l'indice dei gruppi di oggetti come ARN di risorse in un'azione AWS IoT politica, come segue.

Azione	Risorsa
`iot:GetStatistics`	Un indice ARN (ad esempio `arn:aws:iot:your-aws-region:index/AWS_Things` o `arn:aws:iot:your-aws-region:index/AWS_ThingGroups`).

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Gestione dell'indicizzazione di gruppi di oggetti

Sintassi delle query