Abfragen von Aggregatdaten

AWS IoT bietet vier APIs (GetStatistics,GetCardinality, undGetBucketsAggregation)GetPercentiles, mit denen Sie Ihre Geräteflotte nach aggregierten Daten durchsuchen können.

Anmerkung

Bei Problemen mit fehlenden oder unerwarteten Werten für die Aggregation APIs lesen Sie den Leitfaden zur Fehlerbehebung bei der Fleet-Indexierung.

GetStatistics

Der Befehl GetStatisticsAPIund der get-statistics CLI Befehl geben die Anzahl, den Durchschnitt, die Summe, das Minimum, das Maximum, die Summe der Quadrate, die Varianz und die Standardabweichung für das angegebene aggregierte Feld zurück.

Der get-statistics-Befehl CLI verwendet die folgenden Parameter:

index-name

Der Name des zu durchsuchenden Indexes. Der Standardwert ist AWS_Things.

query-string

Die zur Abfrage des Indexes verwendete Abfrage. Sie können angeben"*", dass die Anzahl aller indizierten Objekte in Ihrem abgerufen werden soll. AWS-Konto

aggregationField

(Optional) Das zu aggregierende Feld. Dieses Feld muss ein verwaltetes oder benutzerdefiniertes Feld sein, das beim Aufruf von update-indexing-configuration definiert wird. Wenn Sie kein Aggregationsfeld angeben, wird registry.version als Aggregationsfeld verwendet.

query-version

Die Version der Abfrage, die verwendet werden soll. Der Standardwert ist 2017-09-30.

Der Typ des Aggregationsfelds kann sich auf die zurückgegebenen Statistiken auswirken.

GetStatistics mit Zeichenkettenwerten

Wenn Sie in einem Zeichenfolgenfeld aggregieren, gibt der Aufruf von GetStatistics eine Anzahl von Geräten zurück, die Attribute aufweisen, die der Abfrage entsprechen. Beispielsweise:

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

Dieser Befehl gibt die Anzahl der Geräte zurück, die ein Attribut mit dem Namen stringAttribute enthalten:

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

GetStatistics mit booleschen Werten

Wenn Sie GetStatistics mit einem booleschen Aggregationsfeld aufrufen:

• AVERAGEist der Prozentsatz der Geräte, die der Abfrage entsprechen.

• MINIMUMist gemäß den folgenden Regeln 0 oder 1:

  • Wenn alle Werte für das Aggregationsfeld gleich sindfalse, MINIMUM ist 0.

  • Wenn alle Werte für das Aggregationsfeld gleich sindtrue, MINIMUM ist 1.

  • Wenn die Werte für das Aggregationsfeld eine Mischung aus false und sindtrue, MINIMUM ist 0.

• MAXIMUMist 0 oder 1 gemäß den folgenden Regeln:

  • Wenn alle Werte für das Aggregationsfeld gleich sindfalse, MAXIMUM ist 0.

  • Wenn alle Werte für das Aggregationsfeld gleich sindtrue, MAXIMUM ist 1.

  • Wenn die Werte für das Aggregationsfeld eine Mischung aus false und sindtrue, MAXIMUM ist 1.

• SUMist die Summe der ganzzahligen Entsprechungen der booleschen Werte.

• COUNTist die Anzahl der Elemente, die den Kriterien der Abfragezeichenfolge entsprechen und einen gültigen Aggregationsfeldwert enthalten.

GetStatistics mit numerischen Werten

Wenn Sie GetStatistics aufrufen und ein Aggregationsfeld vom Typ Number angeben, gibt GetStatistics die folgenden Werte zurück:

count

Die Anzahl der Elemente, die den Kriterien der Abfragezeichenfolge entsprechen und einen gültigen Aggregationsfeldwert enthalten.

Durchschnitt

Der Durchschnitt der numerischen Werte, die der Abfrage entsprechen.

sum

Die Summe der numerischen Werte, die der Abfrage entsprechen.

Minimum

Der kleinste numerische Wert, der der Abfrage entspricht.

Maximum

Der größte numerische Wert, der der Abfrage entspricht.

sumOfSquares

Die Summe der Quadrate der numerischen Werte, die der Abfrage entsprechen.

Varianz

Die Varianz der numerischen Werte, die der Abfrage entsprechen. Die Varianz einer Wertemenge ist der Durchschnitt der Quadrate der Differenzen jedes einzelnen Werts vom Durchschnittswert der Menge.

stdDeviation

Die Standardabweichung der numerischen Werte, die der Abfrage entsprechen. Die Standardabweichung einer Wertemenge ist ein Maß für die Verteilung der Werte.

Das folgende Beispiel zeigt, wie get-statistics mit einem numerischen benutzerdefinierten Feld aufgerufen wird.

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

Wenn die Feldwerte den maximalen doppelten Wert überschreiten, sind bei numerischen Aggregationsfeldern die Statistikwerte leer.

GetCardinality

Der Befehl GetCardinalityAPIund der get-cardinality CLI Befehl geben die ungefähre Anzahl der eindeutigen Werte zurück, die der Abfrage entsprechen. Beispiel: Sie möchten die Anzahl der Geräte mit einem Akkustand von weniger als 50 Prozent ermitteln:

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

Dieser Befehl gibt die Anzahl der Elemente mit einem Akkustand von mehr als 50 Prozent zurück:

{
    "cardinality": 100
}

cardinality wird immer von get-cardinality zurückgegeben, auch wenn keine übereinstimmenden Felder vorhanden sind. Beispielsweise:

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

{
    "cardinality": 0
}

Der get-cardinality-Befehl CLI verwendet die folgenden Parameter:

index-name

Der Name des zu durchsuchenden Indexes. Der Standardwert ist AWS_Things.

query-string

Die zur Abfrage des Indexes verwendete Abfrage. Sie können angeben"*", dass die Anzahl aller indizierten Dinge in Ihrem AWS-Konto abgerufen werden soll.

aggregationField

Das zu aggregierende Feld.

query-version

Die Version der Abfrage, die verwendet werden soll. Der Standardwert ist 2017-09-30.

GetPercentiles

Der Befehl GetPercentilesAPIund der get-percentiles CLI Befehl gruppiert die aggregierten Werte, die der Abfrage entsprechen, in Perzentilgruppierungen. Die standardmäßigen Perzentilgruppierungen sind 1,5,25,50,75,95,99, auch wenn Sie beim Aufrufen von GetPercentiles Ihre eigenen angeben können. Diese Funktion gibt einen Wert für jede angegebene Perzentilgruppe (oder die standardmäßigen Perzentilgruppierungen) zurück. Die Perzentilgruppe „1“ enthält den aggregierten Feldwert, der in etwa in einem Prozent der Werte auftritt, die der Abfrage entsprechen. Die Perzentilgruppe „5“ enthält den aggregierten Feldwert, der in etwa in fünf Prozent der Werte auftritt, die der Abfrage entsprechen, usw. Das Ergebnis ist eine Annäherung, je mehr Werte der Abfrage entsprechen, desto genauer sind die Perzentilwerte.

Das folgende Beispiel zeigt, wie der Befehl aufgerufen wird. get-percentiles 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
        }
    ]
}

Der folgende Befehl zeigt die Ausgabe von get-percentiles, wenn keine entsprechenden Dokumente vorhanden sind.

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

{
    "percentiles": []
}

Der get-percentile-Befehl CLI verwendet die folgenden Parameter:

index-name

Der Name des zu durchsuchenden Indexes. Der Standardwert ist AWS_Things.

query-string

Die zur Abfrage des Indexes verwendete Abfrage. Sie können angeben"*", dass die Anzahl aller indizierten Dinge in Ihrem AWS-Konto abgerufen werden soll.

aggregationField

Das zu aggregierende Feld, das den Typ Number aufweisen muss.

query-version

Die Version der Abfrage, die verwendet werden soll. Der Standardwert ist 2017-09-30.

percents

Mit diesem Parameter können Sie benutzerdefinierte Perzentilgruppierungen angeben.

GetBucketsAggregation

Der Befehl GetBucketsAggregationAPIund der get-buckets-aggregation CLI Befehl geben eine Liste von Buckets und die Gesamtzahl der Dinge zurück, die den Kriterien der Abfragezeichenfolge entsprechen.

Das folgende Beispiel zeigt, wie der get-buckets-aggregation CLI Befehl aufgerufen wird.

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

Dieser Befehl gibt die folgende Ausgabe zurück: .

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

Der get-buckets-aggregation CLI Befehl verwendet die folgenden Parameter:

index-name

Der Name des zu durchsuchenden Indexes. Der Standardwert ist AWS_Things.

query-string

Die zur Abfrage des Indexes verwendete Abfrage. Sie können angeben"*", dass die Anzahl aller indizierten Dinge in Ihrem AWS-Konto abgerufen werden soll.

aggregation-field

Das zu aggregierende Feld.

buckets-aggregation-type

Die grundlegende Steuerung der Antwortform und des auszuführenden Bucket-Aggregationstyps.

Autorisierung

Sie können den Index der Dinggruppen wie folgt als Ressource ARN in einer AWS IoT Richtlinienaktion angeben.

Aktion	Ressource
iot:GetStatistics	Ein Index ARN (zum Beispiel arn:aws:iot:your-aws-region:index/AWS_Things oderarn:aws:iot:your-aws-region:index/AWS_ThingGroups).