了解 HTTP 端點交付請求和回應規格 - Amazon Data Firehose
要求格式回應格式範例

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

了解 HTTP 端點交付請求和回應規格

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

要求格式

路徑和 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 不會嘗試以任何方式解譯此金鑰。設定的金鑰會逐字複製到此標頭的值中。

內容可以是任意的，並且可能代表 JWT 記號或 ACCESS_KEY。如果端點需要多欄位憑證 (例如，使用者名稱和密碼)，則所有欄位的值都應以端點理解的格式 (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="
    }
  ]
}

回應格式

出現錯誤時的預設行為

如果回應不符合下列要求，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 * (multiplier(2) ^ retry_count)) 來退避。退避時間受限於 2 分鐘的間隔上限。例如，在第 'n' 次重試後關閉時間為 = MAX(120， 2^n) * random(0.85， 1.15)。

在上一個方程式中所指定的參數可能會發生變更。如需確切的初始退避時間、最大退避時間、乘數和指數退避演算法中使用的抖動百分比，請參閱 AWS Firehose 文件。

在每次後續重試嘗試中，交付記錄的存取金鑰和/或目的地可能會根據 Firehose 串流的更新組態而變更。Amazon Data Firehose 服務在重試之間以最佳方式使用相同的 request-id。可將這最後一個功能用於 HTTP 端點伺服器的重複資料刪除目的。如果請求在允許的最長時間 （根據 Firehose 串流組態） 後仍未交付，則可根據串流組態選擇將批次記錄交付至錯誤儲存貯體。

範例

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