附录 - HTTP 端点传输请求和响应规范

由您直接配置为单个 URL 字段的一部分。Amazon Data Firehose 按配置发送它们，无需修改。仅支持 https 目标。URL 限制在传输流配置期间应用。

此标头用于指示请求/响应格式的版本。目前唯一的版本是 1.0。

此标头的值是一个不透明的 GUID，可用于调试和重复数据删除。如果可能的话，端点实现应记录这个标头的值，包括成功和失败的请求。在多次尝试同一请求时，请求 ID 保持不变。

Content-Type 标头的值始终为 application/json。

可以将 Firehose 流配置为在发送请求时使用 GZIP 压缩正文。启用此压缩后，按照标准做法，Content-Encoding 标头的值将设置为 gzip。如果未启用压缩，则 Content-Encoding 标头就完全不存在。

按照标准方式使用。

以 ASCII 字符串格式表示的 Firehose 直播的 ARN。ARN 对区域、Amazon 账户 ID 和流名称进行编码。例如，arn:aws:firehose:us-east-1:123456789:deliverystream/testStream。

此标头包含 API 密钥或其他凭证。在创建或更新传输流时，您可以创建或更新 API 密钥（又称授权令牌）。Amazon Data Firehose 将访问密钥的大小限制在 4096 字节以内。Amazon Data Firehose 不会尝试以任何方式解释此密钥。配置的密钥将逐字复制到此标头的值中。

内容可以是任意的，可能表示 JWT 令牌或 ACCESS_KEY。如果端点需要多字段凭证（如用户名和密码），则应将所有字段的值以端点可理解的格式（JSON 或 CSV）一起存储在单个访问密钥中。如果原始内容是二进制的，则可以对此字段进行 base-64 编码。Amazon Data Firehose 不会修改和/或编码配置的值，而是按原样使用内容。

此标头包含与整个请求和/或请求中所有记录相关的公共属性（元数据）。这些都是您在创建 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": ""
  }
                    

最大正文大小由您配置，压缩前最大可达 64MiB。

正文包含一个 JSON 文档，该文档具有以下 JSON 架构（用 YAML 编写）：

"$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（超出大小）被视为永久失败，并且记录批次不会发送到错误存储桶（如果已配置）。所有其他响应代码均被视为可重试的错误，并受到稍后介绍的回退重试算法的约束。

唯一可接受的内容类型是 application/json。

不得使用 Content-Encoding。正文必须是未压缩状态。

如果响应有正文，则必须有 Content-Length 标头。

响应正文的大小必须小于等于 1MiB。

"$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 服务器都会使用指数退避算法重新尝试传送相同批次的记录。重试使用抖动系数为 (15%) 的初始退缩时间（1 秒）进行恢复，随后的每次重试都使用带有抖动的公式（initial-backoff-time *（乘数 (2) ^ retry_count））进行恢复。回退时间的最大间隔限制为 2 分钟。例如，在第 n 次重试时，回退时间为 = MAX(120sec, (1 * (2^n)) * random(0.85, 1.15)。

上式中指定的参数可能会发生变化。有关指数回退算法中使用的具体初始回退时间、最大回退时间、乘数和抖动百分比，请参阅 Amazon Firehose 文档。

在随后的每次重试中，传送记录的访问密钥和/或目标可能会根据更新后的 Firehose 流配置而发生变化。Amazon Data Firehose 服务以尽力而为的方式在重试中使用相同的请求编号。最后一项功能可用于 HTTP 端点服务器进行重复数据删除。如果在允许的最长时间（基于 Firehose 流配置）之后仍未传送请求，则可以根据流配置选择将批次记录传送到错误存储桶。