批次 HTTP 動作訊息 - AWS IoT Core
概觀在批次中使用 HTTP 標頭承載範例限制批次處理的錯誤動作使用 批次處理 HTTP 動作訊息AWS CLI

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

批次 HTTP 動作訊息

您可以使用批次處理，在單一請求中傳送多個 HTTP 動作訊息。

概觀

批次處理可讓您分批從AWS IoT Core規則引擎傳送訊息至 HTTP 端點。此功能可以透過減少 HTTP 動作執行的數量，以及透過減少與建立新連線相關聯的額外負荷來提高效率，從而協助降低成本。

注意

批次 HTTP 動作會計量為單一動作。根據AWS IoT Core規則引擎向下游服務發出的傳出批次承載大小，以 5 kiB 的增量計量。如需詳細資訊，請參閱 AWS IoT Core 定價頁面。

當您在 IoT 規則動作的定義中啟用批次處理時，下列參數將可用於組態：

maxBatchOpenMs

傳出訊息等待其他訊息建立批次的時間上限 （以毫秒為單位）。設定越高，批次 HTTP 動作的延遲就越長。

最小值：5 毫秒。最大值：200 毫秒。

預設值：20 ms

支援替代範本：否

maxBatchSize

在單一 IoT 規則動作執行中批次處理的訊息數量上限。

最小值：2 則訊息。最大值：10 則訊息

預設值：10 則訊息

支援替代範本：否

maxBatchSizeBytes

訊息批次的大小上限，以位元組為單位。

最小值：100 位元組。最大值：131，072 個位元組

預設值：5120 位元組

支援替代範本：否

重要

當您指定多個批次參數時，批次會在達到第一個限制時完成。例如，如果您將 100 毫秒指定為最大批次開啟時間，將 5 kiB 指定為最大批次大小，且規則引擎只會在 100 毫秒內批次處理 2 kiB，則會建立並傳送 2 kiB 批次。

在批次中使用 HTTP 標頭

當您在 HTTP 動作中使用標頭時，批次請求會使用上次新增至批次的訊息中的標頭值 （不一定是您發佈的最後一個訊息）。我們建議使用下列其中一個標頭值：

  • 批次中所有訊息的相同

  • 適用於所有訊息 （例如，身分驗證憑證）

標頭會與 HTTP 請求一起傳送，且不屬於訊息內文。

注意

啟用批次處理時：

  • 批次請求會自動包含 Content-Type: application/json標頭，因為批次會以 JSON 陣列傳送。

  • 我們無法保證批次中的最後一個訊息是您發佈的最後一個訊息。這是最後一個訊息，讓它進入批次。

承載範例

下列範例顯示傳送至 HTTP 端點的批次訊息承載結構：

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

限制

以下是批次處理的限制：

  • AWS IoT Core不保證整體訊息排序。批次會在每個主機本機執行，這可能會導致批次中的訊息處理順序與收到的順序不同。

  • AWS IoT Core不提供接收者端的訊息處理支援。您有責任確保您的下游服務設定為接受並批次處理資料。

  • 即使訊息目的地為相同的資源識別符 (HTTP URL 或資源 ARN)，也不支援跨帳戶批次處理。

  • AWS IoT Core不保證批次大小符合您指定的組態。根據時間和訊息流程，批次可能小於您設定的限制。

  • 啟用批次處理時，不支援二進位承載 （非 UTF-8 資料）。只接受 UTF-8 文字承載 （例如 JSON)。若要傳送二進位資料，Base64 會在傳送至 HTTP 動作之前對其進行編碼，然後在接收端點對其進行解碼。例如，您可以使用 IoT 規則中的編碼函數來編碼二進位承載。或者，您可以在 IoT 裝置中編碼二進位承載並將其發佈到 AWS IoT Core。

批次處理的錯誤動作

您將無法在錯誤動作定義中定義個別的批次邏輯。不過，如果您已在主要動作中定義批次邏輯，您的錯誤動作將支援批次處理。

當批次請求失敗時，AWS IoT CoreRules 引擎將遵循 HTTP 動作重試邏輯。在最後一次重試嘗試之後，每個個別訊息都會叫用錯誤動作。

以下是啟用批次處理的錯誤動作訊息範例：

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

批次動作失敗也會產生較大的錯誤動作承載，進而增加因大小而導致錯誤動作失敗的機率。您可以使用 ErrorActionFailure 指標監控錯誤動作失敗。如需詳細資訊，請參閱規則動作指標。

使用 批次處理 HTTP 動作訊息AWS CLI

使用批次處理建立或更新規則動作

  1. 使用適當的AWS CLI命令來建立或更新規則：

    • 若要建立新的規則，請使用 create-topic-rule 命令：

      aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json

    • 若要更新現有規則，請使用 replace-topic-rule 命令：

      aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json

  2. 在主題規則承載中將 enableBatching 參數設定為 true，以啟用批次功能：

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

  3. 設定批次處理參數。您不需要指定所有批次參數。您可以選擇指定 1、2 或所有 3 個批次參數。如果您未指定批次參數，規則引擎會使用預設值更新該參數。如需批次處理參數及其預設值的詳細資訊，請參閱 HTTP 參數。