附录-发送请求和响应规范(PatientendpointdeliveryRequestandResponseSpecifications) - Amazon Kinesis Data Firehose
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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

附录-发送请求和响应规范(PatientendpointdeliveryRequestandResponseSpecifications)

要使Kinesis数据Firehose能够成功地将数据传送到自定义的HTTPS端点,这些端点必须接受请求并使用特定的Kinesis数据Firehose请求和响应格式发送响应。本节描述了KinesisDataFirehose服务向自定义HTTPS端点发送请求的格式规范,以及KinesisDataFirehose服务预期的HTTPS响应的格式规范。在Kinesis数据Firehose超时之前,对请求进行3分钟的响应。KinesisDataFirehose将不符合正确格式的回答视为交付失败。

请求格式

路径和URL参数

它们由您直接配置,作为单个URL字段的一部分。KinesisDataFirehose按配置发送,无需修改。仅支持https目的地。在交付流配置期间应用URL限制。

HTTPS接头-X-Amz-Firehose研究方案版本

此页眉用于表示请求/响应格式的版本。目前唯一的版本为1.0。

HTTPS标题-X-Amz-Firehose-Request-Id

此标题的值是一个不透明的GUID,可用于调试和重删目的。如果可能,对于成功和不成功的请求,端点实现应记录此标题的值。在同一请求多次尝试之间,请求ID保持不变。

HTTPS标题-内容类型

内容类型标题的价值始终 application/json.

HTTPS标题-内容编码

KinesisDataFirehose输送流可以配置为在发送请求时使用GZIP压缩身体。启用此压缩后,根据标准实践,“内容编码”标题的值设置为gzip。如果未启用压缩,则完全不存在内容编码标题。

HTTPS标题-内容长度

以标准方式使用。

HTTPS接头-X-Amz-Firehose-来源-Arn:

KinesisDataFirehose交付流的ARN以ASCII串格式表示。ARN编码地区、AW账号ID和流名称。例如:arn:aws:firehose:us-east-1:123456789:deliverystream/testStream

HTTPS标题-X-Amz-Firehose-访问密钥

此标题携带API密钥或其他凭证。您可以在创建或更新交付流时创建或更新API密钥(也称为授权标记)。KinesisDataFirehose将访问密钥的大小限制在4096位数。KinesisDataFirehose不会以任何方式解释此密钥。配置的密钥将逐字复制到此标题的值中。

内容可以是任意的,并且可能代表JWT标记或ACCESS_KY。如果某个终点需要多字段凭据(例如,用户名和密码),所有字段的值应以该终点理解的格式(Json或CSV)一起存储在一个访问密钥中。如果原始内容为二元,则该字段可采用base-64编码。KinesisDataFirehose不会修改和/或编码配置的值,而是按原样使用内容。

HTTPS标题-X-Amz-Firehose-通用属性

此标题承载与整个请求和/或请求中的所有记录相关的通用属性(元数据)。创建交付流时,这些是由您直接配置的。此属性的值编码为具有以下框架的JSM对象:

"$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。

正文-示意图

正文携带一个含以下JNS架构的JNS文档(用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=" } ] }

响应格式

默认错误行为

如果回答不符合以下要求,KinesisFirehose服务器将其视为500状态代码,无正文。

状态代码

必须在2XX、4XX或5XX范围内。

KinesisDataFirehose服务器不遵循重定向(3XX状态代码)。只有响应代码200才被视为将记录成功发送至HTTPS/EP。响应代码413(超出大小)被视为永久失败,如果已配置,记录批次不会发送到错误存储桶。所有其他响应代码均被视为可检索错误,并接受稍后解释的后退重试算法。

标题-内容类型

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

HTTPS标题-内容编码

不得使用内容编码。身体必须解压。

HTTPS标题-内容长度

如果回答具有正文,则必须显示内容长度标题。

正文-最大尺寸

反应体的大小必须为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 }
错误回答处理

在所有错误情况下,KinesisDataFirehose服务器使用指数回溯算法重新尝试交付同一批次的记录。使用初始后退时间(1秒)和不稳定因子(15%)来回退重试,并使用包含添加的不稳定因素的公式(初始后退时间*(乘数(2)^rest_count))来回退重试。最多以2分钟为间隔时间。例如,在‘n’-第次重试时,返回时间=最大值(120秒,(1*(2^n))*随机(0.85,1,15)。

前述公式中指定的参数可能会发生变化。有关指数回溯算法中使用的确切初始回溯时间、最大回溯时间、乘数和振动百分比,请参阅AWIDFirehose文档。

在每个后续重试尝试中,根据交付流的更新配置,交付记录的访问密钥和/或目的地可能会发生变化。KinesisDataFirehose服务以最有效的方式使用相同的请求ID。此最后一个功能可用于由HTTPS端点服务器进行重删。如果请求在允许的最长时间(基于交付流配置)后仍未交付,则可根据流配置将批处理记录可选地发送至错误存储区。

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