附录 – HTTP 终端节点传输请求和响应规范 - Amazon Kinesis Data Firehose
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

附录 – HTTP 终端节点传输请求和响应规范

要使 Kinesis Data Firehose 成功将数据传输到自定义 HTTP 终端节点,这些终端节点必须接受请求并使用特定 Kinesis Data Firehose 请求和响应格式发送响应。本节介绍 Kinesis Data Firehose 服务发送到自定义 HTTP 终端节点的 HTTP 请求的格式规范,以及 Kinesis Data Firehose 服务预期的 HTTP 响应的格式规范。HTTP 终端节点在 Kinesis Data Firehose 超时请求之前,需要 3 分钟来响应请求。Kinesis Data Firehose 将不符合正确格式的响应视为传输失败。

请求格式

路径和 URL 参数

这些由您直接配置为单个 URL 字段的一部分。Kinesis 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 标头的值始终为 application/json

HTTP 标头 - 内容编码

可将 Kinesis Data Firehose 传输流配置为使用 GZIP 在发送请求时压缩正文。启用此压缩后,根据标准做法,Content-Encoding 标头的值将设置为 gzip。如果未启用压缩,则 Content-Encoding 标头完全不存在。

HTTP 标头 - 内容长度

这是按标准方式使用的。

HTTP 标头 - X-Amz-Firehose-Source-Arn:

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

HTTP 标头 - X-Amz-Firehose-Access-Key

此标头具有 API 密钥或其他凭证。您可以在创建或更新传输流时创建或更新 API 密钥(也称为授权令牌)。Kinesis Data Firehose 将访问密钥的大小限制为 4096 字节。Kinesis Data Firehose 不会尝试以任何方式解释此键。配置的键逐字复制到此标头的值中。

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

HTTP 标头 - X-Amz-Firehose-Common-Attributes

此标头包含与整个请求和/或请求中的所有记录相关的常见属性(元数据)。这些将由您在创建传输流时直接配置。此属性的值将编码为具有以下架构的 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 编写):

"$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 Delivery 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=" } ] }

响应格式

错误时的默认行为

如果响应未能满足以下要求,Kinesis Firehose 服务器将认为它具有 500 状态代码并且没有正文。

状态代码

HTTP 状态代码必须在 2XX、4XX 或 5XX 范围内。

Kinesis Data Firehose 服务器不遵循重定向 (3XX 状态代码)。仅响应代码 200 被视为将记录成功传送到 HTTP/EP。响应代码 413(超过大小)被视为永久失败,并且如果配置了记录批次,则不会将其发送到错误存储桶。所有其他响应代码都被视为可重试错误,并受稍后解释的退避重试算法的影响。

标头 - 内容类型

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

HTTP 标头 - 内容编码

不得使用内容编码。正文必须未压缩。

HTTP 标头 - 内容长度

如果响应具有正文,则必须存在 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 }
错误响应处理

在所有错误情况下,Kinesis Data Firehose 服务器重新尝试使用指数退避算法来传输同一批记录。重试使用初始退避时间(1 秒)并带有抖动系数 (5%) 来备份,后续的每次重试使用具有增加抖动的公式(初始退避 * (倍数 (2) ^ 重试计数))进行备份。退避时间的上限为 2 分钟。例如,对于 "n"-th 重试退避时间 = MAX(120sec, (1 * 2^n)) * random(0.85, 1,15)。

前面公式中指定的参数可能会发生变化。请参阅 AWS Firehose 文档,以了解指数退避算法中使用的确切初始退避时间、最大退避时间、乘数和抖动百分比。

在每个后续重试尝试中,将记录传输到的访问密钥和/或目标可能会因传输流的更新配置而发生变化。Kinesis Data Firehose 服务以最佳努力方式跨重试使用相同的请求 ID。HTTP 终端节点服务器可以将最后一个功能用于重复数据删除目的。如果请求在允许的最大时间 (基于传输流配置) 后仍然无法传输,则可以选择根据流配置将一批记录传输到错误存储桶。

Examples

源请求的示例: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" } ] } } ] }