-Übersicht Verwendung von HTTP-Headern in einem Batch Beispiel für eine Nutzlast Einschränkungen Fehleraktionen beim Stapeln Stapeln von HTTP-Aktionsmeldungen mit dem AWS CLI

Batch-Verarbeitung von HTTP-Aktionsnachrichten

Sie können Batching verwenden, um mehrere HTTP-Aktionsnachrichten in einer einzigen Anfrage zu senden.

-Übersicht

Mithilfe der Stapelverarbeitung können Sie Nachrichten stapelweise von der AWS IoT Core Rules Engine an Ihre HTTP-Endpunkte senden. Diese Funktion kann dazu beitragen, Ihre Kosten zu senken, indem sie die Anzahl der HTTP-Aktionsausführungen reduziert und die Effizienz verbessert, indem der Aufwand für den Aufbau neuer Verbindungen reduziert wird.

Anmerkung

Die gebündelte HTTP-Aktion wird als einzelne Aktion erfasst. Die Berechnung erfolgt in Schritten von 5 KiB, basierend auf der Größe der ausgehenden Batch-Payload, die von der Rules Engine an den AWS IoT Core Downstream-Service ausgegeben wird. Weitere Informationen finden Sie in der AWS IoT Core Preisliste.

Wenn Sie das Batching in der Definition Ihrer IoT-Regelaktion aktivieren, stehen die folgenden Parameter zur Konfiguration zur Verfügung:

maxBatchOpenMs

Die maximale Zeit (in Millisekunden), die eine ausgehende Nachricht darauf wartet, dass andere Nachrichten den Stapel erstellen. Je höher die Einstellung, desto länger ist die Latenz der Batch-HTTP-Aktion.

Mindestwert: 5 ms. Maximalwert: 200 ms.

Standardwert: 20 ms

Unterstützt Ersatzvorlagen: Nein

maxBatchSize

Die maximale Anzahl von Nachrichten, die bei der Ausführung einer einzelnen IoT-Regelaktion gebündelt werden.

Mindestwert: 2 Nachrichten. Maximalwert: 10 Nachrichten

Standardwert: 10 Nachrichten

Unterstützt Ersatzvorlagen: Nein

maxBatchSizeBytes

Maximale Größe eines Nachrichtenstapels in Byte.

Mindestwert: 100 Byte. Höchstwert: 131.072 Byte

Standardwert: 5120 Byte

Unterstützt Ersatzvorlagen: Nein

batchAcrossTopics

Ob das Stapeln von Nachrichten aus verschiedenen MQTT-Themen in einer einzigen HTTP-Anfrage zulässig ist. Standardmäßig werden nur Nachrichten zum gleichen Thema gebündelt. Aktivieren Sie diesen Parameter für Routing-Anwendungsfälle, in denen Nachrichten aus mehreren Gerätethemen für denselben HTTP-Endpunkt bestimmt sind.

Standardwert: false

Unterstützt Ersatzvorlagen: Nein

Wichtig

Wenn Sie mehrere Batch-Parameter angeben, wird die Stapelverarbeitung abgeschlossen, wenn das erste Limit erreicht ist. Wenn Sie beispielsweise 100 ms als maximale Batch-Öffnungszeit und 5 KiB als maximale Batchgröße angeben und Rules Engine innerhalb von 100 ms nur 2 KiB stapelt, wird ein 2-KiB-Batch erstellt und gesendet.

Anmerkung

Nachrichten werden immer im Rahmen desselben Kontos, desselben Regelnamens, derselben HTTP-Zielendpunkt-URL und derselben Abrechnungsgruppe gebündelt. Nachrichten, die sich in einem dieser Attribute unterscheiden, werden niemals zu demselben Stapel zusammengefasst, unabhängig von der batchAcrossTopics Einstellung.

Verwendung von HTTP-Headern in einem Batch

Wenn Sie Header in Ihrer HTTP-Aktion verwenden, verwendet die Batch-Anfrage den Header-Wert der letzten Nachricht, die dem Batch hinzugefügt wurde (nicht unbedingt die letzte Nachricht, die Sie veröffentlicht haben). Wir empfehlen, Header-Werte zu verwenden, die entweder:

Identisch für alle Nachrichten im Stapel
Gilt für alle Nachrichten (z. B. Authentifizierungsdaten)

Die Header werden mit der HTTP-Anfrage gesendet und sind nicht Teil des Nachrichtentexts.

Anmerkung

Wenn die Stapelverarbeitung aktiviert ist:

Die Batch-Anfrage enthält automatisch den Content-Type: application/json Header, da der Batch als JSON-Array gesendet wird.
Wir können nicht garantieren, dass die letzte Nachricht im Stapel die letzte Nachricht ist, die Sie veröffentlicht haben. Es ist die letzte Nachricht, die es in den Stapel geschafft hat.

Beispiel für eine Nutzlast

Das folgende Beispiel zeigt die Struktur einer Batch-Nutzlast, die an Ihren HTTP-Endpunkt gesendet wird:


[
  {
    "user_id": "user1",
    "steps_today": 1000
  },
  {
    "user_id": "user2",
    "steps_today": 21000
  },
  {
    "user_id": "user8",
    "steps_today": 1500
  },
  ...
]

Einschränkungen

Die folgenden Einschränkungen gelten für die Stapelverarbeitung:

AWS IoT Core garantiert nicht die allgemeine Reihenfolge der Nachrichten. Die Stapelverarbeitung erfolgt lokal auf jedem Host, was dazu führen kann, dass Nachrichten innerhalb eines Batches in einer anderen Reihenfolge verarbeitet werden, als sie empfangen wurden.
AWS IoT Core bietet keine Unterstützung für die Nachrichtenverarbeitung auf der Empfängerseite. Sie sind dafür verantwortlich, dass Ihr Downstream-Service so konfiguriert ist, dass er Daten stapelweise akzeptiert und verarbeitet.
Cross-account Batching wird nicht unterstützt, auch wenn Nachrichten für dieselbe Ressourcenkennung (HTTP-URL oder Ressourcen-ARN) bestimmt sind.
AWS IoT Core garantiert nicht, dass die Batchgröße der von Ihnen angegebenen Konfiguration entspricht. Stapel können je nach Zeitpunkt und Nachrichtenfluss kleiner als Ihre konfigurierten Grenzwerte sein.
Wenn die Stapelverarbeitung aktiviert ist, werden binäre Nutzdaten (keine UTF-8 Daten) nicht unterstützt. Nur UTF-8 Textnutzlasten (wie JSON) werden akzeptiert. Um Binärdaten zu senden, kodieren Sie sie mit Base64, bevor Sie sie an die HTTP-Aktion senden, und dekodieren Sie sie dann an Ihrem Empfangsendpunkt. Beispielsweise können Sie die Encode-Funktion in IoT-Regeln verwenden, um die binäre Nutzlast zu kodieren. Alternativ können Sie die binäre Nutzlast in Ihrem IoT-Gerät kodieren und dort veröffentlichen. AWS IoT Core

Fehleraktionen beim Stapeln

Sie werden in Ihrer Fehleraktionsdefinition keine separate Batching-Logik definieren können. Ihre Fehleraktion unterstützt jedoch die Stapelverarbeitung, wenn Sie in Ihrer primären Aktion eine Batching-Logik definiert haben.

Wenn eine Batch-Anfrage fehlschlägt, folgt die AWS IoT Core Rules Engine der HTTP-Aktionslogik für Wiederholungsversuche. Nach dem letzten Wiederholungsversuch wird eine Fehleraktion für den gesamten fehlgeschlagenen Batch aufgerufen.

Im Folgenden finden Sie ein Beispiel für eine Fehlermeldung mit aktivierter Stapelverarbeitung:


{
    "ruleName": "FailedTopicRule",
    "topic": "topic/rulesengine",
    "payloadsWithMetadata": [
        {
            "id": 1,
            "cloudwatchTraceId": "bebd6d93-6d4a-899e-9e40-56e82252d2be",
            "clientId": "Test",
            "sourceIp": "10.0.0.0",
            "base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
        },
        {
            "id": 2,
            "cloudwatchTraceId": "af94d3b8-0b18-1dbf-2c7d-513f5cb9e2e1",
            "clientId": "Test",
            "sourceIp": "10.0.0.0",
            "base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
        },
        {
            "id": 3,
            "cloudwatchTraceId": "ca441266-c2ce-c916-6aee-b9e5c7831675",
            "clientId": "Test",
            "sourceIp": "10.0.0.0",
            "base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
        }
    ],
    "failures": [
        {
            "affectedIds": [
                1,
                2,
                3
            ],
            "failedAction": "HttpAction",
            "failedResource": "https://example.foobar.com/HttpAction",
            "errorMessage": "HttpAction failed to make a request to the specified endpoint. StatusCode: 500. Reason: Internal Server Error."
        },
        {
            "affectedIds": [
                3
            ],
            "failedAction": "S3Action",
            "failedResource": "amzn-s3-demo-bucket",
            "errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist"
        },
        {
            "affectedIds": [
                3
            ],
            "failedAction": "LambdaAction",
            "failedResource": "arn:aws:lambda:us-west-2:123456789012:function:dummy",
            "errorMessage": "Failed to invoke lambda function. Received Server error from Lambda. The error code is 403"
        }
    ]
}

Wenn diese Option aktiviert batchAcrossTopics ist, ändert sich das Payload-Format für die Fehleraktion. Das topic Feld wird von der obersten Ebene in jeden payloadsWithMetadata Eintrag verschoben:


{
    "ruleName": "FailedTopicRule",
    "payloadsWithMetadata": [
        {
            "id": 1,
            "topic": "topic/sensor1",
            "cloudwatchTraceId": "bebd6d93-6d4a-899e-9e40-56e82252d2be",
            "clientId": "Test",
            "sourceIp": "10.0.0.0",
            "base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
        },
        {
            "id": 2,
            "topic": "topic/sensor2",
            "cloudwatchTraceId": "af94d3b8-0b18-1dbf-2c7d-513f5cb9e2e1",
            "clientId": "Test",
            "sourceIp": "10.0.0.0",
            "base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
        }
    ],
    "failures": [
        {
            "affectedIds": [1, 2],
            "failedAction": "HttpAction",
            "failedResource": "https://example.foobar.com/HttpAction",
            "errorMessage": "HttpAction failed to make a request to the specified endpoint. StatusCode: 500. Reason: Internal Server Error."
        }
    ]
}

Anmerkung

Fehlgeschlagene Aktionen generieren außerdem größere Nutzlasten für Fehleraktionen, was aufgrund der Größe die Wahrscheinlichkeit erhöhen kann, dass Fehleraktionen fehlschlagen. Mithilfe der Metrik können Sie Fehlschläge bei Fehlaktionen überwachen. ErrorActionFailure Weitere Informationen finden Sie unter Regelaktionsmetriken.

Stapeln von HTTP-Aktionsmeldungen mit dem AWS CLI

Erstellen oder Aktualisieren einer Regelaktion mit Batching

Verwenden Sie den entsprechenden AWS CLI Befehl, um eine Regel zu erstellen oder zu aktualisieren:
- Verwenden Sie den Befehl create-topic-rule, um eine neue Regel zu erstellen:
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
- Verwenden Sie den Befehl replace-topic-rule, um eine vorhandene Regel zu aktualisieren: https://docs.aws.amazon.com/cli/latest/reference/iot/replace-topic-rule.html
```
aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```

Aktivieren Sie die Batching-Funktionen, indem Sie den Parameter enableBatching in Ihrer Nutzlast für Themenregeln auf true setzen:


{
        "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false,
        "awsIotSqlVersion": "2016-03-23", 
        "actions": [
            { 
                "http": { 
                    "url": "https://www.example.com/subpath",
                    "confirmationUrl": "https://www.example.com", 
                    "headers": [
                        { 
                            "key": "static_header_key", 
                            "value": "static_header_value" 
                        },
                        { 
                            "key": "substitutable_header_key", 
                            "value": "${value_from_payload}" 
                         }
                    ],
                    "enableBatching": true,
                    "batchConfig": {
                       "maxBatchOpenMs": 100,
                       "maxBatchSize": 5,
                       "maxBatchSizeBytes": 1024,
                       "batchAcrossTopics": true
                    }
                }
            }
      ]
}

Konfigurieren Sie die Batching-Parameter. Sie müssen nicht alle Batch-Parameter angeben. Sie können wählen, ob Sie 1, 2, 3 oder alle 4 Batch-Parameter angeben möchten. Wenn Sie keinen Batch-Parameter angeben, aktualisiert Rules Engine diesen Parameter mit den Standardwerten. Weitere Informationen zu Batching-Parametern und ihren Standardwerten finden Sie unter HTTP-Parameter.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

HTTP

HTTP-Aktionsziele