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

# 批次處理 HTTP 動作訊息
<a name="http_batching"></a>

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

## 概觀
<a name="batching_overview"></a>

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

**注意**  
批次 HTTP 動作會計量為單一動作。根據 AWS IoT Core 規則引擎對下游服務發出的傳出批次承載大小，以 5 kiB 的增量計量。如需詳細資訊，請參閱 [AWS IoT Core 定價頁面](https://aws.amazon.com/iot-core/pricing/)。

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

`maxBatchOpenMs`  
傳出訊息等待其他訊息建立批次的時間上限 （以毫秒為單位）。設定越高，批次 HTTP 動作的延遲就越長。  
最小值：5 毫秒。最大值：200 毫秒。  
預設值：20 ms  
支援[替代範本](iot-substitution-templates.md)：否

`maxBatchSize`  
在單一 IoT 規則動作執行中批次處理的訊息數量上限。  
最小值：2 則訊息。最大值：10 則訊息  
預設值：10 則訊息  
支援[替代範本](iot-substitution-templates.md)：否

`maxBatchSizeBytes`  
訊息批次的大小上限，以位元組為單位。  
最小值：100 位元組。最大值：131，072 個位元組  
預設值：5120 位元組  
支援[替代範本](iot-substitution-templates.md)：否

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

## 在批次中使用 HTTP 標頭
<a name="batching_http_headers"></a>

當您在 HTTP 動作中使用標頭時，批次請求會使用上次新增至批次的訊息中的標頭值 （不一定是您發佈的最後一個訊息）。我們建議使用下列其中一個標頭值：
+ 批次中所有訊息的相同
+ 適用於所有訊息 （例如，身分驗證憑證）

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

**注意**  
啟用批次處理時：  
批次請求會自動包含 `Content-Type: application/json`標頭，因為批次會以 JSON 陣列傳送。
我們無法保證批次中的最後一個訊息是您發佈的最後一個訊息。這是最後一個訊息，讓它進入批次。

## 承載範例
<a name="batching_payload"></a>

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

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

## 限制
<a name="batching_limitations"></a>

以下是批次處理的限制：
+ AWS IoT Core 不保證整體訊息排序。批次處理會在每個主機本機執行，這可能會導致批次內的訊息處理順序與收到的順序不同。
+ AWS IoT Core 不提供接收者端的訊息處理支援。您有責任確保您的下游服務設定為接受並批次處理資料。
+ 即使訊息目的地為相同的資源識別符 (HTTP URL 或資源 ARN)，也不支援跨帳戶批次處理。
+ AWS IoT Core 不保證批次大小符合您指定的組態。根據時間和訊息流程，批次可能小於您設定的限制。
+ 啟用批次處理時，不支援二進位承載 （非 UTF-8 資料）。只接受 UTF-8 文字承載 （例如 JSON)。若要傳送二進位資料，Base64 會在傳送至 HTTP 動作之前對其進行編碼，然後在接收端點對其進行解碼。例如，您可以使用 IoT 規則中的[編碼函數](iot-sql-functions.html#iot-function-encode)來編碼二進位承載。或者，您可以在 IoT 裝置中編碼二進位承載並將其發佈到 AWS IoT Core。

## 批次處理的錯誤動作
<a name="batching_errors"></a>

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

當批次請求失敗時， AWS IoT Core Rules 引擎將遵循 [HTTP 動作重試邏輯](https-rule-action.md#https-rule-action-retry-logic)。在最後一次重試嘗試之後，將會針對整個失敗的批次叫用錯誤動作。

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

```
{
    "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` 指標監控錯誤動作失敗。如需詳細資訊，請參閱[規則動作指標](metrics_dimensions.md#rule-action-metrics)。

## 使用 批次處理 HTTP 動作訊息 AWS CLI
<a name="batching_procedure"></a>

### 使用批次處理建立或更新規則動作
<a name="batching_create_update_rule"></a>

1. 使用適當的 AWS CLI 命令來建立或更新規則：
   + 若要建立新的規則，請使用 [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) 命令：

     ```
     aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
     ```
   + 若要更新現有規則，請使用 [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
     ```

1. 在主題規則承載中將 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
                       }
                   }
               }
         ]
   }
   ```

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