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

# 了解 HTTP 端點交付請求和回應規格
<a name="httpdeliveryrequestresponse"></a>

若要讓 Amazon Data Firehose 成功將資料交付至自訂 HTTP 端點，這些端點必須接受請求，並使用特定 Amazon Data Firehose 請求和回應格式傳送回應。本節說明 Amazon Data Firehose 服務傳送至自訂 HTTP 端點的 HTTP 請求格式規格，以及 Amazon Data Firehose 服務預期的 HTTP 回應格式規格。HTTP 端點有 3 分鐘的時間在 Amazon Data Firehose 逾時該請求之前回應請求。Amazon Data Firehose 會將不符合適當格式的回應視為交付失敗。

## 要求格式
<a name="requestformat"></a>

**路徑和 URL 參數**  
這些是由您作為單一 URL 欄位的一部分直接進行設定。Amazon Data Firehose 會依設定傳送它們，無需修改。僅 https 目的地受支援。系統會在交付串流組態期間套用 URL 限制。  
目前，HTTP 端點資料交付僅支援連接埠 443。

**HTTP 標頭 – X-Amz-Firehose-Protocol-Version**  
此標頭用於指示請求/回應格式的版本。目前僅支援 1.0 版本。

**HTTP 標頭 – X-Amz-Firehose-Request-Id**  
此標頭的值是不透明的 GUID，可用於偵錯和重複資料刪除目的。如果可能，端點實作應該記錄此標頭的值，以滿足成功和不成功的請求。在相同請求的多次嘗試之間，請求 ID 保持不變。

**HTTP 標頭 – Content-Type**  
Content-Type 標頭的值永遠是 `application/json`。

**HTTP 標頭 – Content-Encoding**  
Firehose 串流可設定為在傳送請求時使用 GZIP 壓縮內文。啟用此壓縮時，根據標準實務，Content-Encoding 標頭的值會設定為 gzip。如果未啟用壓縮，則 Content-Encoding 標頭完全不存在。

**HTTP 標頭 – Content-Length**  
以標準方式對其進行使用。

**HTTP 標頭 – X-Amz-Firehose-Source-Arn：**  
以 ASCII 字串格式表示的 Firehose 串流 ARN。ARN 會編碼區域、 AWS 帳戶 ID 和串流名稱。例如 `arn:aws:firehose:us-east-1:123456789:deliverystream/testStream`。

**HTTP 標頭 – X-Amz-Firehose-Access-Key**  
此標頭帶有 API 金鑰或其他憑證。您可以在建立或更新交付串流時建立或更新 API 金鑰 (也稱為授權記號)。Amazon Data Firehose 會將存取金鑰的大小限制為 4096 個位元組。Amazon Data Firehose 不會嘗試以任何方式解譯此金鑰。設定的金鑰會逐字複製到此標頭的值中。不過，如果您使用 Secrets Manager 來設定金鑰，則秘密必須遵循特定的 JSON 物件格式：`{"api_key": "..."}`。  
內容可以是任意的，並且可能代表 JWT 記號或 ACCESS\$1KEY。如果端點需要多欄位憑證 (例如，使用者名稱和密碼)，則所有欄位的值都應以端點理解的格式 (JSON 或 CSV) 儲存在單一存取金鑰中。如果原始內容是二進位，則此欄位可以是 base-64 編碼。Amazon Data Firehose 不會修改和/或編碼設定的值，並照原樣使用內容。

**HTTP 標頭 – X-Amz-Firehose-Common-Attributes**  
該標頭包含與整個請求和/或請求中的所有記錄有關的共同屬性 (中繼資料)。這些是由您在建立 Firehose 串流時直接設定。系統會將此屬性的值編碼為具有下列結構描述的 JSON 物件：  

```
"$schema": http://json-schema.org/draft-07/schema#

properties:
  commonAttributes:
    type: object
    minProperties: 0
    maxProperties: 50
    patternProperties:
      "^.{1,256}$":
        type: string
        minLength: 0
        maxLength: 1024
```
範例如下：  

```
"commonAttributes": {
    "deployment -context": "pre-prod-gamma",
    "device-types": ""
  }
```

**主體 – 大小上限**  
壓縮之前，主體大小上限由您設定，最大可達 64 MiB。

**主體 – 結構描述**  
主體包含具有下列 JSON 結構描述 (以 YAML 寫入) 的單一 JSON 文件：  

```
"$schema": http://json-schema.org/draft-07/schema#

title: FirehoseCustomHttpsEndpointRequest
description: >
  The request body that the Firehose service sends to
  custom HTTPS endpoints.
type: object
properties:
  requestId:
    description: >
      Same as the value in the X-Amz-Firehose-Request-Id header,
      duplicated here for convenience.
    type: string
  timestamp:
    description: >
      The timestamp (milliseconds since epoch) at which the Firehose
      server generated this request.
    type: integer
  records:
    description: >
      The actual records of the Firehose stream, carrying 
      the customer data.
    type: array
    minItems: 1
    maxItems: 10000
    items:
      type: object
      properties:
        data:
          description: >
            The data of this record, in Base64. Note that empty
            records are permitted in Firehose. The maximum allowed
            size of the data, before Base64 encoding, is 1024000
            bytes; the maximum length of this field is therefore
            1365336 chars.
          type: string
          minLength: 0
          maxLength: 1365336

required:
  - requestId
  - records
```
範例如下：  

```
{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": 1578090901599
  "records": [
    {
      "data": "aGVsbG8="
    },
    {
      "data": "aGVsbG8gd29ybGQ="
    }
  ]
}
```

## 回應格式
<a name="responseformat"></a>

**出現錯誤時的預設行為**  
如果回應不符合下列要求，Firehose 伺服器會將其視為具有 500 狀態碼且沒有內文。

**狀態碼**  
HTTP 狀態碼必須在 2XX、4XX 或 5XX 的範圍內。  
Amazon Data Firehose 伺服器不遵循重新導向 (3XX 狀態碼）。只將回應碼 200 視為成功將記錄交付至 HTTP/EP。會將回應碼 413 (大小已超出) 視為永久失效，如果已設定，則不會將記錄批次傳送至錯誤儲存貯體。會將所有其他回應碼視為可重試的錯誤，並受限於稍後解釋的輪詢重試演算法。

**標頭 – 內容類型**  
唯一可接受的內容類型是應用程式/json。

**HTTP 標頭 – Content-Encoding**  
不能使用 Content-Encoding。必須對主體進行解壓縮。

**HTTP 標頭 – Content-Length**  
如果回應有主體，則 Content-Length 標頭必須存在。

**主體 – 大小上限**  
回應主體的大小必須為小於或等於 1 MiB。  

```
"$schema": http://json-schema.org/draft-07/schema#

title: FirehoseCustomHttpsEndpointResponse

description: >
  The response body that the Firehose service sends to
  custom HTTPS endpoints.
type: object
properties:
  requestId:
    description: >
      Must match the requestId in the request.
    type: string
  
  timestamp:
    description: >
      The timestamp (milliseconds since epoch) at which the
      server processed this request.
    type: integer
   
  errorMessage:
    description: >
      For failed requests, a message explaining the failure.
      If a request fails after exhausting all retries, the last 
      Instance of the error message is copied to error output
      S3 bucket if configured.
    type: string
    minLength: 0
    maxLength: 8192
required:
  - requestId
  - timestamp
```
範例如下：  

```
Failure Case (HTTP Response Code 4xx or 5xx)
{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": "1578090903599",
  "errorMessage": "Unable to deliver records due to unknown error."
}
Success case (HTTP Response Code 200)
{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": 1578090903599
}
```

**錯誤回應處理**  
在所有錯誤情況下，Amazon Data Firehose 伺服器會使用指數退避演算法重新嘗試交付相同批次的記錄。重試會使用初始退避時間 (1 秒) 和抖動係數 (15%) 進行退避，並且每次後續重試都會使用新增抖動的公式 (initial-backoff-time \$1 (multiplier(2) ^ retry\$1count)) 來退避。退避時間受限於 2 分鐘的間隔上限。例如，在第 n 次重試時，退避時間為 = MAX(120， 2^n) \$1 random(0.85， 1.15)。  
在上一個方程式中所指定的參數可能會發生變更。如需確切的初始退避時間、最大退避時間、倍數和指數退避演算法中使用的抖動百分比，請參閱 AWS Firehose 文件。  
每次後續重試嘗試時，交付記錄的存取金鑰和/或目的地可能會根據 Firehose 串流的更新組態而變更。Amazon Data Firehose 服務會盡最大努力跨重試使用相同的 request-id。可將這最後一個功能用於 HTTP 端點伺服器的重複資料刪除目的。如果請求在允許的最長時間 （根據 Firehose 串流組態） 之後仍未交付，批次記錄可以根據串流組態選擇性地交付到錯誤儲存貯體。

## 範例
<a name="examples"></a>

 CWLog 來源請求的範例。

```
{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": 1578090901599,
  "records": [
   {
    "data": {
      "messageType": "DATA_MESSAGE",
      "owner": "123456789012",
      "logGroup": "log_group_name",
      "logStream": "log_stream_name",
      "subscriptionFilters": [
        "subscription_filter_name"
      ],
      "logEvents": [
        {
          "id": "0123456789012345678901234567890123456789012345",
          "timestamp": 1510109208016,
          "message": "log message 1"
        },
        {
          "id": "0123456789012345678901234567890123456789012345",
          "timestamp": 1510109208017,
          "message": "log message 2"
        }
      ]
    }
   }
  ]
}
```