瞭解HTTP端點交付要求和回應規格

為了讓 Amazon Data Firehose 能夠成功地將資料交付到自訂HTTP端點，這些端點必須接受請求並使用特定 Amazon Data Firehose 請求和回應格式傳送回應。本節說明 Amazon Data Firehose 服務傳送到自訂HTTP端點的HTTP請求的格式規格，以及 Amazon 資料 Firehose 服務預期HTTP回應的格式規格。HTTP在 Amazon Data Firehose 逾時該請求之前，端點有 3 分鐘的時間來回應請求。Amazon 資料 Firehose 會將不遵守正確格式的回應視為交付失敗。

要求格式

路徑和URL參數

這些由您直接配置為單個URL字段的一部分。Amazon 數據 Firehose 將它們按配置發送而無需修改。僅 https 目的地受支援。URL交付串流組態期間會套用限制。

注意

目前，HTTP端點資料傳遞僅支援連接埠 443。

HTTP標題-X-AMZ-防火管協議版本

此標頭用於指示請求/回應格式的版本。目前僅支援 1.0 版本。

HTTP標題-X-AMZ-防火軟件請求 ID

此標頭的值是不透明的，可GUID用於調試和重複數據刪除目的。如果可能，端點實作應該記錄此標頭的值，以滿足成功和不成功的請求。在相同請求的多次嘗試之間，請求 ID 保持不變。

HTTP標題-內容類型

Content-Type 標頭的值永遠是 application/json。

HTTP標題-內容編碼

Firehose 串流可設定為在傳送要求時用GZIP來壓縮主體。啟用此壓縮時，根據標準實務，Content-Encoding 標頭的值會設定為 gzip。如果未啟用壓縮，則 Content-Encoding 標頭完全不存在。

HTTP標題-內容長度

以標準方式對其進行使用。

HTTP標題-X-AMZ 防火軟管源-阿恩：

以ASCII字串格式表示ARN的 Firehose 資料流。ARN編碼區域、 AWS 帳戶 ID 和串流名稱。例如：arn:aws:firehose:us-east-1:123456789:deliverystream/testStream。

HTTP標題-X-AMZ 防火軟管訪問密鑰

此標頭包含API金鑰或其他認證。您可以在建立或更新交付串流時建立或更新 API-key (也稱為授權權杖)。Amazon 數據 Firehose 將訪問密鑰的大小限制為 4096 字節。Amazon 數據 Firehose 不會嘗試以任何方式解釋此密鑰。設定的金鑰會逐字複製到此標頭的值中。

內容可以是任意的，並且可能代表JWT令牌或 ACCESS _ KEY。如果端點需要多欄位認證（例如，使用者名稱和密碼），則所有欄位的值都應以端點理解的格式儲存在單一存取金鑰中。JSON CSV如果原始內容是二進位，則此欄位可以是 base-64 編碼。Amazon 資料 Firehose 不會修改和/或編碼已設定的值，也不會按原樣使用內容。

HTTP標題-X-AMZ 防火軟管-共同屬性

該標頭包含與整個請求和/或請求中的所有記錄有關的共同屬性 (中繼資料)。這些是您在建立 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態碼MUST是在 2XX，4XX 或 5XX 範圍內。

Amazon 數據 Firehose 服務器確實NOT遵循重定向（3XX 狀態碼）。只有回應碼 200 會被視為成功傳遞記錄至 HTTP /EP。會將回應碼 413 (大小已超出) 視為永久失效，如果已設定，則不會將記錄批次傳送至錯誤儲存貯體。會將所有其他回應碼視為可重試的錯誤，並受限於稍後解釋的輪詢重試演算法。

標頭 – 內容類型

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

HTTP標題-內容編碼

使用內容編碼MUSTNOT。主體MUST將被解壓縮。

HTTP標題-內容長度

內容長度頭MUST是存在的，如果響應有一個主體。

主體 – 大小上限

回應主體的大小必須為小於或等於 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 * (乘數 (2) ^ retry_count)) 來取消每次後續重試。退避時間受限於 2 分鐘的間隔上限。例如，在第 N 次重試時，退回時間是 =MAX（120，2 ^ n）* 隨機（0.85，1.15）。

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

在每次後續重試嘗試中，傳送記錄的存取金鑰和/或目的地可能會根據 Firehose 串流的更新組態而變更。Amazon 資料 Firehose 服務會以最佳方式在重試期間使用相同的請求識別碼。最後一個功能可用於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"
        }
      ]
    }
   }
  ]
}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

了解跨 AWS 帳戶和區域的交付

處理資料傳送失敗