Panoramica di Utilizzo delle intestazioni HTTP in un batch Esempio di payload Limitazioni Azioni di errore relative al batching Raccolta in batch dei messaggi di azione HTTP con AWS CLI

Messaggi di azione HTTP in batch

È possibile utilizzare il batch per inviare più messaggi di azione HTTP in un'unica richiesta.

Panoramica di

Il batching consente di inviare messaggi da AWS IoT Core Rules Engine agli endpoint HTTP in batch. Questa funzionalità può contribuire a ridurre i costi riducendo il numero di esecuzioni di azioni HTTP e a migliorare l'efficienza riducendo il sovraccarico associato alla creazione di nuove connessioni.

Nota

L'azione HTTP in batch viene misurata come azione singola. La misurazione viene effettuata in incrementi di 5 KiB, in base alla dimensione del payload in batch in uscita emesso dal Rules Engine al servizio downstream. AWS IoT Core Per ulteriori informazioni, consultare la pagina dei prezzi di AWS IoT Core.

Quando abiliti il batching nella definizione di IoT Rule Action, i seguenti parametri saranno disponibili per la configurazione:

maxBatchOpenMs

Il tempo massimo (in millisecondi) in cui un messaggio in uscita attende che altri messaggi creino il batch. Maggiore è l'impostazione, maggiore è la latenza dell'azione HTTP in batch.

Valore minimo: 5 ms. Valore massimo: 200 ms.

Valore predefinito: 20 ms

Supporta modelli di sostituzione: no

maxBatchSize

Il numero massimo di messaggi raggruppati in un'unica azione basata su una regola IoT.

Valore minimo: 2 messaggi. Valore massimo: 10 messaggi

Valore predefinito: 10 messaggi

Supporta modelli di sostituzione: no

maxBatchSizeBytes

Dimensione massima di un batch di messaggi, in byte.

Valore minimo: 100 byte. Valore massimo: 131.072 byte

Valore predefinito: 5120 byte

Supporta modelli di sostituzione: no

batchAcrossTopics

Se consentire il raggruppamento in batch di messaggi provenienti da diversi argomenti MQTT in un'unica richiesta HTTP. Per impostazione predefinita, solo i messaggi dello stesso argomento vengono raggruppati insieme. Abilita questo parametro per il routing dei casi d'uso in cui i messaggi provenienti da più argomenti del dispositivo sono destinati allo stesso endpoint HTTP.

Valore predefinito: false

Supporta modelli di sostituzione: no

Importante

Quando si specificano più parametri batch, il batch viene completato quando viene raggiunto il primo limite. Ad esempio, se si specificano 100 ms come tempo massimo di apertura del batch e 5 KiB come dimensione massima del batch e Rules Engine esegue batch di soli 2 KiB in 100 ms, verrà creato e inviato un batch da 2 KiB.

Nota

I messaggi vengono sempre raggruppati nell’ambito dello stesso account, nome della regola, URL dell’endpoint HTTP di destinazione e gruppo di fatturazione. I messaggi che differiscono in uno di questi attributi non vengono mai combinati nello stesso batch, indipendentemente dall'batchAcrossTopicsimpostazione.

Utilizzo delle intestazioni HTTP in un batch

Quando si utilizzano le intestazioni nell'azione HTTP, la richiesta in batch utilizza il valore dell'intestazione dell'ultimo messaggio aggiunto al batch (non necessariamente l'ultimo messaggio pubblicato). Ti consigliamo di utilizzare valori di intestazione che siano:

Identici in tutti i messaggi del batch
Applicabile a tutti i messaggi (ad esempio, le credenziali di autenticazione)

Le intestazioni vengono inviate con la richiesta HTTP e non fanno parte del corpo del messaggio.

Nota

Quando il batching è abilitato:

La richiesta in batch include automaticamente l'Content-Type: application/jsonintestazione, poiché il batch viene inviato come array JSON.
Non possiamo garantire che l'ultimo messaggio del batch sia l'ultimo messaggio pubblicato. È l'ultimo messaggio che è stato inserito nel batch.

Esempio di payload

L'esempio seguente mostra la struttura di un payload di messaggi in batch inviato all'endpoint HTTP:


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

Limitazioni

Di seguito sono riportate le limitazioni relative al batch:

AWS IoT Core non garantisce l'ordine complessivo dei messaggi. Il batch viene eseguito localmente su ciascun host, il che può comportare l'elaborazione dei messaggi all'interno di un batch in un ordine diverso da quello in cui sono stati ricevuti.
AWS IoT Core non fornisce supporto per l'elaborazione dei messaggi sul lato ricevente. L'utente è responsabile di garantire che il servizio downstream sia configurato per accettare ed elaborare i dati in batch.
Cross-account il batching non è supportato, anche se i messaggi sono destinati allo stesso identificatore di risorsa (URL HTTP o ARN di risorsa).
AWS IoT Core non garantisce che la dimensione del batch soddisfi la configurazione specificata. I batch possono essere inferiori ai limiti configurati in base alla tempistica e al flusso di messaggi.
Quando il batch è abilitato, i payload binari (non UTF-8 dati) non sono supportati. Sono accettati solo payload di UTF-8 testo (come JSON). Per inviare dati binari, è necessario codificarli in base64 prima di inviarli all'azione HTTP, quindi decodificarli all'endpoint ricevente. Ad esempio, puoi utilizzare la funzione di codifica nelle regole IoT per codificare il payload binario. In alternativa, puoi codificare il payload binario nel tuo dispositivo IoT e pubblicarlo su. AWS IoT Core

Azioni di errore relative al batching

Non sarà possibile definire una logica di batch separata nella definizione di Error Action. Tuttavia, l'azione di errore supporterà il batch se è stata definita una logica di batch nell'azione principale.

Quando una richiesta batch fallisce, il motore AWS IoT Core delle regole seguirà la logica di ripetizione dell'azione HTTP. Dopo l'ultimo tentativo di nuovo tentativo, verrà richiamata un'azione di errore per l'intero batch fallito.

Di seguito è riportato un esempio di messaggio di errore con il batching abilitato:


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

Quando batchAcrossTopics è abilitato, il formato del payload dell'azione di errore cambia. Il topic campo si sposta dal livello superiore all'interno di ogni payloadsWithMetadata voce:


{
    "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."
        }
    ]
}

Nota

Gli errori dovuti alle azioni in batch generano inoltre payload di maggiori dimensioni, che possono aumentare la probabilità di errori dovuti alle dimensioni. È possibile monitorare le azioni di errore non riuscite utilizzando la metrica. ErrorActionFailure Per ulteriori informazioni, consulta Parametri delle operazioni sulle regole.

Raccolta in batch dei messaggi di azione HTTP con AWS CLI

Creazione o aggiornamento di un'azione della regola con batch

Usa il AWS CLI comando appropriato per creare o aggiornare una regola:
- Per creare una nuova regola, usa il comando https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html create-topic-rule:
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
- Per aggiornare una regola esistente, usa il comando replace-topic-rule: 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
```

Abilita le funzionalità di batch impostando il parametro enableBatching su true nel payload della regola tematica:


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

Configura i parametri di batch. Non è necessario specificare tutti i parametri del batch. È possibile scegliere di specificare 1, 2, 3 o tutti e 4 i parametri del batch. Se non si specifica un parametro batch, Rules Engine aggiornerà tale parametro con i valori predefiniti. Per ulteriori informazioni sui parametri di batch e sui relativi valori predefiniti, consulta Parametri Parameters HTTP.

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

HTTP

Destinazioni dell’azione HTTP