本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 了解 Amazon Data Firehose 中的数据传输
当你向 Firehose 直播发送数据时，数据会自动传送到你选择的目的地。下表说明了到不同目的地的传输数据。
| 目标位置 | Details |
| --- | --- |
| Amazon S3 | 对于到 Amazon S3 的数据传输，Firehose 根据 Firehose 流的缓冲配置连接多个传入记录。然后，将记录作为 Amazon S3 对象传输到 Amazon S3。默认情况下，Firehose 连接数据时不使用任何分隔符。如果您想在记录之间使用新行分隔符，则可以通过在 [Firehose 控制台配置](https://docs.aws.amazon.com/firehose/latest/dev/create-destination.html#create-destination-s3)或 [API 参数](https://docs.aws.amazon.com/firehose/latest/APIReference/API_Processor.html)中启用此功能来添加新行分隔符。Firehose 和 Amazon S3 目的地之间的数据传输使用 TLS（HTTPS）加密。 |
| Amazon Redshift | 为向 Amazon Redshift 进行数据传输，Firehose 首先会将传入数据按上述格式传输到 S3 存储桶。然后，Firehose 会发出 Amazon Redshift **COPY** 命令，将数据从 S3 存储桶加载到 Amazon Redshift 预置集群或 Amazon Redshift Serverless 工作组。确保在 Amazon Data Firehose 将多个传入记录连接到 Amazon S3 对象后，可以将 Amazon S3 对象复制到您的 Amazon Redshift 预置集群或 Amazon Redshift Serverless 工作组。有关更多信息，请参阅 [Amazon Redshift COPY 命令数据格式参数](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-format.html)。 |
| OpenSearch 服务和 OpenSearch 无服务器 | 为了向 OpenSearch 服务和 OpenSearch 无服务器传输数据，Amazon Data Firehose 会根据您的 Firehose 流的缓冲配置来缓冲传入的记录。然后，它会生成一个 OpenSearch 服务或 OpenSearch无服务器批量请求，将多条记录索引到您的 OpenSearch 服务集群或 OpenSearch 无服务器集合。在将记录发送到 Amazon Data Firehose 之前，确保记录采用 UTF-8 编码并展平为单行 JSON 对象。此外，必须将 OpenSearch 服务集群的rest.action.multi.allow\$1explicit\$1index选项设置为 true（默认），才能使用为每条记录设置的显式索引来接受批量请求。有关更多信息，请参阅《Amazon OpenSearch 服务开发者指南》中的 OpenSearch 服务[配置高级选项](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/es-createupdatedomains.html#es-createdomain-configure-advanced-options)。 |
| Splunk | 为向 Splunk 进行数据传输，Amazon Data Firehose 会连接您发送的字节。如果要在您的数据中使用分隔符（如换行符），您必须自行插入这些分隔符。确保将 Splunk 配置为解析任何此类分隔符。要将传输到 S3 错误存储桶（S3 备份）的数据重新驱动回 Splunk，请按照 [Splunk 文档](https://www.splunk.com/en_us/blog/tips-and-tricks/aws-technical-add-on-simplifying-error-data-re-ingestion.html)中提到的步骤进行操作。 |
| HTTP 端点 | 在向受支持的第三方服务提供商拥有的 HTTP 端点进行数据传输时，您可以使用集成的 Amazon Lambda 服务创建一个函数，将传入记录转换为与服务提供商集成预期的格式匹配的格式。请联系您选择其 HTTP 端点作为目标的第三方服务提供商，了解有关他们接受的记录格式的更多信息。 |
| Snowflake | 为了将数据传输到 Snowflake，Amazon Data Firehose 会在内部缓冲数据一秒钟，并使用 Snowflake 流式传输 API 操作将数据插入到 Snowflake。默认情况下，每秒都会刷新您插入的记录并将其提交到 Snowflake 表中。在您进行插入调用后，Firehose 会发出一个 CloudWatch 指标，用于衡量将数据提交到 Snowflake 所花费的时间。Firehose 目前仅支持将单个 JSON 项目作为记录有效负载，并且不支持 JSON 数组。请确保您的输入有效负载是有效的 JSON 对象，并且格式正确，没有任何额外的双引号、引号或转义字符。 |
每个 Firehose 目的地都有自己的数据传输频率。有关更多信息，请参阅 [配置缓冲提示](create-configure-backup.md#buffering-hints)。
**重复记录**
Amazon Data Firehose 使用 at-least-once语义进行数据传输。在某些情况下（比如数据传输超时），如果原始数据传输请求最终通过，Amazon Data Firehose 的传输重试可能会导致重复。这适用于 Amazon Data Firehose 支持的所有目的地类型，但 Amazon S3 目的地、Apache Iceberg 表和 Snowflake 目的地除外。
**Topics**
+ [了解跨 AWS 账户和地区的配送情况](across.md)
+ [了解 HTTP 端点传输请求和响应规范](httpdeliveryrequestresponse.md)
+ [处理数据传输失败](retry.md)
+ [配置 Amazon S3 对象名称格式](s3-object-name.md)
+ [为 OpenSearch 服务配置索引轮换](es-index-rotation.md)
+ [暂停和恢复数据传输](pause-restart-stream.md)
# 了解跨 AWS 账户和地区的配送情况
Amazon Data Firehose 支持跨 AWS 账户向 HTTP 终端节点目标传输数据。您选择作为目标的 Firehose 流和 HTTP 端点可以属于不同的 AWS 账户。
Amazon Data Firehose 还支持跨 AWS 区域向 HTTP 终端节点目标传输数据。您可以将数据从一个区域的 Firehose 流传输到另一个 AWS AWS 区域的 HTTP 终端节点。您还可以将数据从 Firehose 流传输到 AWS 区域以外的 HTTP 终端节点目标，例如通过将 HTTP 端点网址设置为所需目的地，将数据传输到您自己的本地服务器。在这些情况下，您的传输成本将增加额外的传输费用。有关更多信息，请参阅“按需定价”页面中的[数据传输](https://aws.amazon.com/ec2/pricing/on-demand/#Data_Transfer)部分。
# 了解 HTTP 端点传输请求和响应规范
要使 Amazon Data Firehose 成功将数据传输到自定义 HTTP 端点，这些端点必须接受请求，并使用某些 Amazon Data Firehose 请求和响应格式发送响应。本节介绍 Amazon Data Firehose 服务发送到自定义 HTTP 端点的 HTTP 请求的格式规范，以及 Amazon Data Firehose 服务预期的 HTTP 响应的格式规范。在 Amazon Data Firehose 使请求超时之前，HTTP 端点有 3 分钟的时间响应请求。Amazon Data Firehose 将不符合正确格式的响应视为传输失败。
## 请求格式
**路径和 URL 参数**
由您直接配置为单个 URL 字段的一部分。Amazon Data Firehose 会按配置发送，无需修改。仅支持 https 目标。URL 限制在传输流配置期间应用。
目前，HTTP 端点数据传输仅支持端口 443。
**HTTP 标头 X-Amz-Firehose-Protocol-版本**
此标头用于指示请求/响应格式的版本。目前唯一的版本是 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 不会尝试以任何方式解释此密钥。配置的密钥将逐字复制到此标头的值中。但是，如果您使用 Secrets Manager 来配置密钥，则密钥必须遵循特定的 JSON 对象格式：`{"api_key": "..."}`。
内容可以是任意的，可能表示 JWT 令牌或 ACCESS\$1KEY。如果端点需要多字段凭证（如用户名和密码），则应将所有字段的值以端点可理解的格式（JSON 或 CSV）一起存储在单个访问密钥中。如果原始内容是二进制的，则可以对此字段进行 base-64 编码。Amazon Data Firehose 不会修改对配置值的 and/or 编码，而是按原样使用内容。
**HTTP 标头- X-Amz-Firehose-Common-属性**
此标头将与整个请求相关的公共属性（元数据）带 and/or 到请求中的所有记录。在创建 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。
**HTTP 标头 - Content-Encoding**
不得使用 Content-Encoding。正文必须是未压缩状态。
**HTTP 标头 - Content-Length**
如果响应有正文，则必须有 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 \$1（乘数 (2) ^ retry\$1count））进行恢复。回退时间的最大间隔限制为 2 分钟。例如，在第 n 次重试时，回退时间为 = M MAX(120, 2^n) \$1 random(0.85, 1.15)。
上式中指定的参数可能会发生变化。有关指数退避算法中使用的确切初始退缩时间、最大退避时间、乘数和抖动百分比，请参阅 Fi AWS rehose 文档。
在随后的每次重试中，传送记录的访问密钥 and/or 目标可能会根据更新后的 Firehose 流配置而发生变化。Amazon Data Firehose 服务尽力在重试中使用相同的请求 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"
}
]
}
}
]
}
```
# 处理数据传输失败
每个 Amazon Data Firehose 目的地都有自己的数据传输失败处理流程。
在设置 Firehose 流时，对于许多目的地（例如 OpenSearch Splunk 和 HTTP 终端节点），您还会设置一个 S3 存储桶，用于备份未能交付的数据。有关 Firehose 在传输失败时如何备份数据的更多信息，请参阅此页的相关目的地部分。有关如何授予对 S3 存储桶的访问权限以备份无法传输的数据的更多信息，请参阅[授予 Firehose 访问 Amazon S3 目的地的权限](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-s3)。当 Firehose（a）无法将数据传输到流目的地，并且（b）无法将数据写入传输失败的备份 S3 存储桶时，实际上会暂停流传输，直到数据可以传输到目的地或写入备份 S3 位置。
## Amazon S3
到 S3 存储桶的数据传输可能会由于某些原因而失败。例如，存储桶可能已不存在、Amazon Data Firehose 承担的 IAM 角色可能无权访问存储桶、网络故障或类似事件。在此类情况下，Amazon Data Firehose 会在 24 小时内持续重试，直到传输成功。Amazon Data Firehose 的最长数据存储时间为 24 小时。如果数据传输失败超过 24 小时，数据将丢失。
传输数据到 S3 存储桶可能会由于各种原因而失败，例如：
+ 存储桶不再存在。
+ Amazon Data Firehose 担任的 IAM 角色无法访问存储桶。
+ 网络问题。
+ S3 错误，例如 HTTP 500s 或其他 API 故障。
在这些情况下，Amazon Data Firehose 将重新尝试传输：
+ **DirectPut 来源：**重试最长可持续 24 小时。
+ **Kinesis Data Streams 或 Amazon MSK 来源**：重试会无限期持续下去，具体取决于流中定义的保留策略。
只有在 Lambda 处理或 parquet 转换失败时，Amazon Data Firehose 才会将失败的记录传输到 S3 错误存储桶。其他失败情况将导致持续重新尝试传输到 S3，直到达到保留期为止。当 Firehose 成功将记录传输到 S3 时，它会创建一个 S3 对象文件；在部分记录失败的情况下，它会自动重新尝试传输，并使用成功处理的记录更新同一 S3 对象文件。
## Amazon Redshift
对于 Amazon Redshift 目的地，您可以在创建 Firehose 流时指定重试持续时间（0–7200 秒）。
将数据传输到 Amazon Redshift 预置集群或 Amazon Redshift Serverless 工作组时，可能会因为以下几个原因而失败。例如，Firehose 流的集群配置不正确、集群或工作组正在维护或网络故障。在此类情况下，Amazon Data Firehose 会在指定的持续时间内重试，并跳过特定批次的 Amazon S3 对象。跳过的对象的信息会以清单文件的形式传输到您的 S3 存储桶中的 `errors/` 文件夹内，您可以利用该清单文件进行手动回填。有关如何使用清单文件手动 COPY 数据的信息，请参阅[使用清单指定数据文件](https://docs.aws.amazon.com/redshift/latest/dg/loading-data-files-using-manifest.html)。
## Amazon OpenSearch 服务和 OpenSearch 无服务器
对于 OpenSearch 服务和 OpenSearch 无服务器目标，您可以在 Firehose 直播创建期间指定重试持续时间（0—7200 秒）。
由于多种原因，向您的 OpenSearch 服务集群或 OpenSearch 无服务器集合传输数据可能会失败。例如，您的 Firehose 流可能存在错误的 OpenSearch 服务集群或 OpenSearch 无服务器集合配置、 OpenSearch 正在维护的服务集群 OpenSearch 或无服务器集合、网络故障或类似事件。在此类情况下，Amazon Data Firehose 会在指定的持续时间内重试，并跳过特定的索引请求。跳过的文档会传输到您的 S3 存储桶中的 `AmazonOpenSearchService_failed/` 文件夹内，您可以利用它进行手动回填。
对于 OpenSearch 服务，每个文档都具有以下 JSON 格式：
```
{
"attemptsMade": "(number of index requests attempted)",
"arrivalTimestamp": "(the time when the document was received by Firehose)",
"errorCode": "(http error code returned by OpenSearch Service)",
"errorMessage": "(error message returned by OpenSearch Service)",
"attemptEndingTimestamp": "(the time when Firehose stopped attempting index request)",
"esDocumentId": "(intended OpenSearch Service document ID)",
"esIndexName": "(intended OpenSearch Service index name)",
"esTypeName": "(intended OpenSearch Service type name)",
"rawData": "(base64-encoded document data)"
}
```
对于 OpenSearch 无服务器，每个文档都采用以下 JSON 格式：
```
{
"attemptsMade": "(number of index requests attempted)",
"arrivalTimestamp": "(the time when the document was received by Firehose)",
"errorCode": "(http error code returned by OpenSearch Serverless)",
"errorMessage": "(error message returned by OpenSearch Serverless)",
"attemptEndingTimestamp": "(the time when Firehose stopped attempting index request)",
"osDocumentId": "(intended OpenSearch Serverless document ID)",
"osIndexName": "(intended OpenSearch Serverless index name)",
"rawData": "(base64-encoded document data)"
}
```
## Splunk
当 Amazon Data Firehose 向 Splunk 发送数据时，会等待 Splunk 的确认。如果出现错误或未在确认超时期限内收到确认，Amazon Data Firehose 将启动重试持续时间计数器。它将不断重试，直到重试持续时间到期为止。重试持续时间到期后，Amazon Data Firehose 将这种情况视为数据传输失败，并将数据备份到 Amazon S3 存储桶。
每次 Amazon Data Firehose 向 Splunk 发送数据时，无论是首次尝试还是重试，都会重新启动确认超时计数器。然后，等待 Splunk 的确认。即使重试持续时间已过，Amazon Data Firehose 仍会等待确认，直到收到确认或确认超时。如果确认超时，Amazon Data Firehose 会检查重试计数器是否还有剩余时间。如果有剩余时间，它将再次重试并重复该逻辑，直到收到确认或确定重试时间已到期。
未收到确认并不是可能出现的唯一一类数据传输错误。有关其他类型的数据传输错误的信息，请参阅 [Splunk 数据传输错误](https://docs.aws.amazon.com/firehose/latest/dev/monitoring-with-cloudwatch-logs.html#monitoring-splunk-errors)。如果重试持续时间大于 0，任何数据传输错误都会触发重试逻辑。
下面是一个错误记录示例。
```
{
"attemptsMade": 0,
"arrivalTimestamp": 1506035354675,
"errorCode": "Splunk.AckTimeout",
"errorMessage": "Did not receive an acknowledgement from HEC before the HEC acknowledgement timeout expired. Despite the acknowledgement timeout, it's possible the data was indexed successfully in Splunk. Amazon Data Firehose backs up in Amazon S3 data for which the acknowledgement timeout expired.",
"attemptEndingTimestamp": 13626284715507,
"rawData": "MiAyNTE2MjAyNzIyMDkgZW5pLTA1ZjMyMmQ1IDIxOC45Mi4xODguMjE0IDE3Mi4xNi4xLjE2NyAyNTIzMyAxNDMzIDYgMSA0MCAxNTA2MDM0NzM0IDE1MDYwMzQ3OTQgUkVKRUNUIE9LCg==",
"EventId": "49577193928114147339600778471082492393164139877200035842.0"
}
```
## HTTP 端点目标
当 Amazon Data Firehose 向 HTTP 端点目的地发送数据时，会等待来自该目的地的响应。如果出现错误或未在响应超时期限内收到响应，Amazon Data Firehose 将启动重试持续时间计数器。它将不断重试，直到重试持续时间到期为止。重试持续时间到期后，Amazon Data Firehose 将这种情况视为数据传输失败，并将数据备份到 Amazon S3 存储桶。
每次 Amazon Data Firehose 向 HTTP 端点目的地发送数据时，无论是首次尝试还是重试，都会重新启动响应超时计数器。然后，等待来自 HTTP 端点目标的响应。即使重试持续时间已过，Amazon Data Firehose 仍会等待响应，直到收到响应或响应超时。如果响应超时，Amazon Data Firehose 会检查重试计数器是否还有剩余时间。如果还有时间，会再次重试并重复逻辑，直到收到响应或确定重试时间已过期。
未收到响应并不是唯一可能发生的数据传输错误类型。有关其他类型的数据传输错误的信息，请参阅 [HTTP 端点数据传输错误](https://docs.aws.amazon.com/firehose/latest/dev/monitoring-with-cloudwatch-logs.html#monitoring-http-errors)。
下面是一个错误记录示例。
```
{
"attemptsMade":5,
"arrivalTimestamp":1594265943615,
"errorCode":"HttpEndpoint.DestinationException",
"errorMessage":"Received the following response from the endpoint destination. {"requestId": "109777ac-8f9b-4082-8e8d-b4f12b5fc17b", "timestamp": 1594266081268, "errorMessage": "Unauthorized"}",
"attemptEndingTimestamp":1594266081318,
"rawData":"c2FtcGxlIHJhdyBkYXRh",
"subsequenceNumber":0,
"dataId":"49607357361271740811418664280693044274821622880012337186.0"
}
```
## Snowflake
对于 Snowflake 目的地，在创建 Firehose 流时，您可以指定可选的重试持续时间（0–7200 秒）。重试持续时间的默认值是 60 秒。
向 Snowflake 表传输数据可能会失败，原因有很多，例如 Snowflake 目的地配置不正确、Snowflake 中断、网络故障等。重试策略不适用于不可重试的错误。例如，如果 Snowflake 因为表中缺少额外的一列而拒绝了您的 JSON 有效负载，则 Firehose 不会尝试再次进行传输。相反，它会为所有因您的 S3 错误存储桶的 JSON 有效负载问题而导致的插入失败创建备份。
同样，如果由于角色、表或数据库错误而导致传输失败，则 Firehose 不会重试并将数据写入您的 S3 存储桶。重试持续时间仅适用于因 Snowflake 服务问题、临时网络故障等导致的失败。在此类情况下，Firehose 会在指定的持续时间内重试，然后再将它们传输到 S3。失败的记录将传输在 snowflake-failed/ 文件夹中，您可以使用该文件夹进行手动回填。
以下是您传输到 S3 的每条记录的 JSON 示例。
```
{
"attemptsMade": 3,
"arrivalTimestamp": 1594265943615,
"errorCode": "Snowflake.InvalidColumns",
"errorMessage": "Snowpipe Streaming does not support columns of type AUTOINCREMENT, IDENTITY, GEO, or columns with a default value or collation",
"attemptEndingTimestamp": 1712937865543,
"rawData": "c2FtcGxlIHJhdyBkYXRh"
}
```
# 配置 Amazon S3 对象名称格式
当 Firehose 向 Amazon S3 传输数据时，S3 对象键名称遵循以下格式 **，其中后缀的格式为 *-------- *，以 1 开头，每进行一次 Firehose 流的配置更改就增加 1。您可以更改 Firehose 流配置（例如，S3 存储桶名称、缓冲提示、压缩以及加密）。您可以使用 Firehose 控制台或 [UpdateDestination](https://docs.aws.amazon.com/firehose/latest/APIReference/API_UpdateDestination.html)API 操作来实现此目的。
对于 **，Firehose 在格式 `YYYY/MM/dd/HH` 中添加了默认的时间前缀。此前缀在存储桶中创建一个逻辑层级结构，其中，每个正斜杠（/）均在该层级结构中创建一个层级。您可以通过指定包含在运行时估算的表达式的自定义前缀来修改此结构。有关如何指定自定义前缀的信息，请参阅 [Custom Prefixes for Amazon Simple Storage Service Objects](https://docs.aws.amazon.com/firehose/latest/dev/s3-prefixes.html)。
默认情况下，时间前缀和后缀的时区为 UTC，但您可以将其更改为偏好的时区。例如，要使用日本标准时间代替 UTC，您可以在 [API 参数设置 CustomTimeZone () AWS 管理控制台](https://docs.aws.amazon.com/firehose/latest/APIReference/API_ExtendedS3DestinationConfiguration.html) 中 Asia/Tokyo 将时区配置为。以下列表包含 Firehose 为 S3 前缀配置支持的时区。
## 支持的时区
以下是 Firehose 为 S3 前缀配置支持的时区列表。
------
#### [ Africa ]
```
Africa/Abidjan
Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
Africa/Asmera
Africa/Bangui
Africa/Banjul
Africa/Bissau
Africa/Blantyre
Africa/Bujumbura
Africa/Cairo
Africa/Casablanca
Africa/Conakry
Africa/Dakar
Africa/Dar_es_Salaam
Africa/Djibouti
Africa/Douala
Africa/Freetown
Africa/Gaborone
Africa/Harare
Africa/Johannesburg
Africa/Kampala
Africa/Khartoum
Africa/Kigali
Africa/Kinshasa
Africa/Lagos
Africa/Libreville
Africa/Lome
Africa/Luanda
Africa/Lubumbashi
Africa/Lusaka
Africa/Malabo
Africa/Maputo
Africa/Maseru
Africa/Mbabane
Africa/Mogadishu
Africa/Monrovia
Africa/Nairobi
Africa/Ndjamena
Africa/Niamey
Africa/Nouakchott
Africa/Ouagadougou
Africa/Porto-Novo
Africa/Sao_Tome
Africa/Timbuktu
Africa/Tripoli
Africa/Tunis
Africa/Windhoek
```
------
#### [ America ]
```
America/Adak
America/Anchorage
America/Anguilla
America/Antigua
America/Aruba
America/Asuncion
America/Barbados
America/Belize
America/Bogota
America/Buenos_Aires
America/Caracas
America/Cayenne
America/Cayman
America/Chicago
America/Costa_Rica
America/Cuiaba
America/Curacao
America/Dawson_Creek
America/Denver
America/Dominica
America/Edmonton
America/El_Salvador
America/Fortaleza
America/Godthab
America/Grand_Turk
America/Grenada
America/Guadeloupe
America/Guatemala
America/Guayaquil
America/Guyana
America/Halifax
America/Havana
America/Indianapolis
America/Jamaica
America/La_Paz
America/Lima
America/Los_Angeles
America/Managua
America/Manaus
America/Martinique
America/Mazatlan
America/Mexico_City
America/Miquelon
America/Montevideo
America/Montreal
America/Montserrat
America/Nassau
America/New_York
America/Noronha
America/Panama
America/Paramaribo
America/Phoenix
America/Port_of_Spain
America/Port-au-Prince
America/Porto_Acre
America/Puerto_Rico
America/Regina
America/Rio_Branco
America/Santiago
America/Santo_Domingo
America/Sao_Paulo
America/Scoresbysund
America/St_Johns
America/St_Kitts
America/St_Lucia
America/St_Thomas
America/St_Vincent
America/Tegucigalpa
America/Thule
America/Tijuana
America/Tortola
America/Vancouver
America/Winnipeg
```
------
#### [ Antarctica ]
```
Antarctica/Casey
Antarctica/DumontDUrville
Antarctica/Mawson
Antarctica/McMurdo
Antarctica/Palmer
```
------
#### [ Asia ]
```
Asia/Aden
Asia/Almaty
Asia/Amman
Asia/Anadyr
Asia/Aqtau
Asia/Aqtobe
Asia/Ashgabat
Asia/Ashkhabad
Asia/Baghdad
Asia/Bahrain
Asia/Baku
Asia/Bangkok
Asia/Beirut
Asia/Bishkek
Asia/Brunei
Asia/Calcutta
Asia/Colombo
Asia/Dacca
Asia/Damascus
Asia/Dhaka
Asia/Dubai
Asia/Dushanbe
Asia/Hong_Kong
Asia/Irkutsk
Asia/Jakarta
Asia/Jayapura
Asia/Jerusalem
Asia/Kabul
Asia/Kamchatka
Asia/Karachi
Asia/Katmandu
Asia/Krasnoyarsk
Asia/Kuala_Lumpur
Asia/Kuwait
Asia/Macao
Asia/Magadan
Asia/Manila
Asia/Muscat
Asia/Nicosia
Asia/Novosibirsk
Asia/Phnom_Penh
Asia/Pyongyang
Asia/Qatar
Asia/Rangoon
Asia/Riyadh
Asia/Saigon
Asia/Seoul
Asia/Shanghai
Asia/Singapore
Asia/Taipei
Asia/Tashkent
Asia/Tbilisi
Asia/Tehran
Asia/Thimbu
Asia/Thimphu
Asia/Tokyo
Asia/Ujung_Pandang
Asia/Ulaanbaatar
Asia/Ulan_Bator
Asia/Vientiane
Asia/Vladivostok
Asia/Yakutsk
Asia/Yekaterinburg
Asia/Yerevan
```
------
#### [ Atlantic ]
```
Atlantic/Azores
Atlantic/Bermuda
Atlantic/Canary
Atlantic/Cape_Verde
Atlantic/Faeroe
Atlantic/Jan_Mayen
Atlantic/Reykjavik
Atlantic/South_Georgia
Atlantic/St_Helena
Atlantic/Stanley
```
------
#### [ Australia ]
```
Australia/Adelaide
Australia/Brisbane
Australia/Broken_Hill
Australia/Darwin
Australia/Hobart
Australia/Lord_Howe
Australia/Perth
Australia/Sydney
```
------
#### [ Europe ]
```
Europe/Amsterdam
Europe/Andorra
Europe/Athens
Europe/Belgrade
Europe/Berlin
Europe/Brussels
Europe/Bucharest
Europe/Budapest
Europe/Chisinau
Europe/Copenhagen
Europe/Dublin
Europe/Gibraltar
Europe/Helsinki
Europe/Istanbul
Europe/Kaliningrad
Europe/Kiev
Europe/Lisbon
Europe/London
Europe/Luxembourg
Europe/Madrid
Europe/Malta
Europe/Minsk
Europe/Monaco
Europe/Moscow
Europe/Oslo
Europe/Paris
Europe/Prague
Europe/Riga
Europe/Rome
Europe/Samara
Europe/Simferopol
Europe/Sofia
Europe/Stockholm
Europe/Tallinn
Europe/Tirane
Europe/Vaduz
Europe/Vienna
Europe/Vilnius
Europe/Warsaw
Europe/Zurich
```
------
#### [ Indian ]
```
Indian/Antananarivo
Indian/Chagos
Indian/Christmas
Indian/Cocos
Indian/Comoro
Indian/Kerguelen
Indian/Mahe
Indian/Maldives
Indian/Mauritius
Indian/Mayotte
Indian/Reunion
```
------
#### [ Pacific ]
```
Pacific/Apia
Pacific/Auckland
Pacific/Chatham
Pacific/Easter
Pacific/Efate
Pacific/Enderbury
Pacific/Fakaofo
Pacific/Fiji
Pacific/Funafuti
Pacific/Galapagos
Pacific/Gambier
Pacific/Guadalcanal
Pacific/Guam
Pacific/Honolulu
Pacific/Kiritimati
Pacific/Kosrae
Pacific/Majuro
Pacific/Marquesas
Pacific/Nauru
Pacific/Niue
Pacific/Norfolk
Pacific/Noumea
Pacific/Pago_Pago
Pacific/Palau
Pacific/Pitcairn
Pacific/Ponape
Pacific/Port_Moresby
Pacific/Rarotonga
Pacific/Saipan
Pacific/Tahiti
Pacific/Tarawa
Pacific/Tongatapu
Pacific/Truk
Pacific/Wake
Pacific/Wallis
```
------
除 ** 之外，您不能更改后缀字段。启用数据格式转换或压缩时，Firehose 将根据配置附加文件扩展名。下表说明了 Firehose 附加的默认文件扩展名：
| 配置 | 文件扩展名 |
| --- | --- |
| 数据格式转换：Parquet | .parquet |
| 数据格式转换：ORC | .orc |
| 压缩：Gzip | .gz |
| 压缩：Zip | .zip |
| 压缩：Snappy | .snappy |
| 压缩：Hadoop-Snappy | .hsnappy |
您还可以在 Firehose 控制台或 API 中指定偏好的文件扩展名。文件扩展名必须以句点（.）开头，并且可以包含允许的字符：0-9a-z\$1-\$1.\$1‘()。文件扩展名不能超过 128 个字符。
**注意**
指定文件扩展名时，它将覆盖 Firehose 在启用[数据格式转换](https://docs.aws.amazon.com/firehose/latest/dev/record-format-conversion.html)或压缩时添加的默认文件扩展名。
# 了解 Amazon S3 对象的自定义前缀
传输到 Amazon S3 的对象遵循 的[名称格式](https://docs.aws.amazon.com/firehose/latest/dev/basic-deliver.html#s3-object-namekey)。您可以指定包含在运行时进行估算的表达式的自定义前缀。您指定的自定义前缀将覆盖的默认前缀 `yyyy/MM/dd/HH`。
您可以在自定义前缀中使用以下形式的表达式：`!{namespace:value}`，其中 `namespace` 可以是以下形式之一，如以下各部分所述。
+ `firehose`
+ `timestamp`
+ `partitionKeyFromQuery`
+ `partitionKeyFromLambda`
如果前缀以斜杠结束，则在 Amazon S3 存储桶中将显示为文件夹。有关更多信息，请参阅《[亚马逊*数据 FirehoseDeveloper指南》中的 Amazon* S3 对象名称格式](https://docs.aws.amazon.com/firehose/latest/dev/basic-deliver.html#s3-object-name)。
## `timestamp` 命名空间
此命名空间的有效值是有效的 [Java DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) 字符串的字符串。例如，对于 2018 年，表达式 `!{timestamp:yyyy}` 的计算结果为 `2018`。
在计算时间戳时，Firehose 将使用所写入 Amazon S3 对象中包含的最早记录的大致到达时间戳。
默认情况下，时间戳按 UTC 时间。但是，您可以指定偏好的时区。例如，如果您想使用日本标准时间而不是 UTC，则可以在 AWS 管理控制台 或 API 参数设置 ([CustomTimeZone](https://docs.aws.amazon.com/firehose/latest/APIReference/API_ExtendedS3DestinationConfiguration.html)) 中将时区配置为。 Asia/Tokyo 要查看支持的时区列表，请参阅 [Amazon S3 Object Name Format](https://docs.aws.amazon.com/firehose/latest/dev/basic-deliver.html#s3-object-name)。
如果您在同一前缀表达式中多次使用 `timestamp` 命名空间，则每个实例的计算结果为同一时刻。
## `firehose` 命名空间
您可以将两个值用于此命名空间：`error-output-type` 和 `random-string`。下表介绍了其使用方法。
**`firehose` 命名空间值**
| 转换 | 说明 | 示例输入 | 输出示例 | 注意 |
| --- | --- | --- | --- | --- |
| error-output-type | 根据您的 Firehose 直播的配置和失败原因，计算结果为以下字符串之一：\$1处理失败、-失败、splunk-failed、splunk-failed AmazonOpenSearchService、、\$1。 format-conversion-failed http-endpoint-failed如果您在同一表达式中多次使用它，则每个实例的计算结果为同一错误字符串。 | myPrefix/result=\$1\$1firehose:error-output-type\$1/\$1\$1timestamp:yyyy/MM/dd\$1 | myPrefix/result=processing-failed/2018/08/03 | 该 error-output-type值只能在 ErrorOutputPrefix字段中使用。 |
| random-string | 计算结果为 11 个字符的随机字符串。如果您在同一表达式中多次使用它，则每个实例的计算结果为一个新的随机字符串。 | myPrefix/\$1\$1firehose:random-string\$1/ | myPrefix/046b6c7f-0b/ | 您可以将它用于这两种前缀类型。您可以将此字符串放在格式字符串的开头以获取随机前缀，若想使用 Amazon S3 获得极高的吞吐量，此操作有时十分必要。 |
## `partitionKeyFromLambda` 和 `partitionKeyFromQuery` 命名空间
对于[动态分区](dynamic-partitioning.md)，您必须在 S3 存储桶前缀中使用以下表达式格式：`!{namespace:value}`，其中命名空间可以是 `partitionKeyFromQuery` 或 `partitionKeyFromLambda`，也可以是两者。如果使用内联解析为源数据创建分区键，则必须指定一个 S3 存储桶前缀值，该值由以下格式指定的表达式组成：`"partitionKeyFromQuery:keyID"`。如果使用 AWS Lambda 函数为源数据创建分区键，则必须指定一个 S3 存储桶前缀值，该值由以下格式指定的表达式组成：`"partitionKeyFromLambda:keyID"`。有关更多信息，请参阅 [Creating an Amazon Firehose stream](basic-create.md#basic-create.title) 中的“Choose Amazon S3 for Your Destination”。
## 语义规则
以下规则适用于 `Prefix` 和 `ErrorOutputPrefix` 表达式。
+ 对于 `timestamp` 命名空间，将计算未包含在单引号内的任何字符。换句话说，将按字面意思处理值字段中使用单引号进行转义的任何字符串。
+ 如果指定的前缀不包含时间戳名称空间表达式，则 Firehose 会将该表达式 `!{timestamp:yyyy/MM/dd/HH/}` 追加到 `Prefix` 字段中的值。
+ 序列 `!{` 只能出现在 `!{namespace:value}` 表达式中。
+ 仅当 `Prefix` 未包含任何表达式时，`ErrorOutputPrefix` 才能为空。在这种情况下，`Prefix` 的计算结果为 `yyyy/MM/DDD/HH/`，`ErrorOutputPrefix` 计算结果为 `yyyy/MM/DDD/HH/`。`DDD` 表示一年中的某天。
+ 如果您为 `ErrorOutputPrefix` 指定一个表达式，则您必须包含至少一个 `!{firehose:error-output-type}` 实例。
+ `Prefix` 无法包含 `!{firehose:error-output-type}`。
+ `Prefix` 和 `ErrorOutputPrefix` 在计算后都不能超过 512 个字符。
+ 如果目标位置是 Amazon Redshift，则 `Prefix` 不能包含表达式并且 `ErrorOutputPrefix` 必须为空。
+ 如果目标是 Amazon S OpenSearch ervice 或 Splunk，但未`ErrorOutputPrefix`指定任何值，Firehose 会使用`Prefix`该字段来记录失败的记录。
+ 当目标位置是 Amazon S3 时，Amazon S3 目标配置中的 `Prefix` 和 `ErrorOutputPrefix` 将分别用于成功记录和失败记录。如果使用 AWS CLI 或 API，则可使用 `ExtendedS3DestinationConfiguration` 指定具有自己的 `Prefix` 和 `ErrorOutputPrefix` 的 Amazon S3 *备份*配置。
+ 当您使用 AWS 管理控制台 并将目标设置为 Amazon S3 时，Firehose 将分别使用目标配置`ErrorOutputPrefix`中的`Prefix`和来记录成功记录和失败记录。如果使用表达式指定前缀，则必须指定错误前缀，包括 `!{firehose:error-output-type}`。
+ 当你`ExtendedS3DestinationConfiguration`与 AWS CLI、API 或者 CloudFormation（如果您指定了）一起使用时`S3BackupConfiguration`，Firehose 不会提供默认值。`ErrorOutputPrefix`
+ 创建 ErrorOutputPrefix 表达`partitionKeyFromQuery`式时不能使用`partitionKeyFromLambda`和命名空间。
## 示例前缀
**`Prefix` 和 `ErrorOutputPrefix` 示例**
| Input | 计算的前缀 [2018 年 8 月 27 日上午 10:30（UTC）] |
| --- | --- |
| `Prefix`：未指定 `ErrorOutputPrefix`: `myFirehoseFailures/!{firehose:error-output-type}/` | `Prefix`: `2018/08/27/10` `ErrorOutputPrefix`: `myFirehoseFailures/processing-failed/` |
| `Prefix`: `!{timestamp:yyyy/MM/dd}` `ErrorOutputPrefix`：未指定 | 输入无效：当 Prefix 包含表达式时，ErrorOutputPrefix 不能为空 |
| `Prefix`: `myFirehose/DeliveredYear=!{timestamp:yyyy}/anyMonth/rand=!{firehose:random-string}` `ErrorOutputPrefix`: `myFirehoseFailures/!{firehose:error-output-type}/!{timestamp:yyyy}/anyMonth/!{timestamp:dd}` | `Prefix`: `myFirehose/DeliveredYear=2018/anyMonth/rand=5abf82daaa5` `ErrorOutputPrefix`: `myFirehoseFailures/processing-failed/2018/anyMonth/10` |
| `Prefix`: `myPrefix/year=!{timestamp:yyyy}/month=!{timestamp:MM}/day=!{timestamp:dd}/hour=!{timestamp:HH}/` `ErrorOutputPrefix`: `myErrorPrefix/year=!{timestamp:yyyy}/month=!{timestamp:MM}/day=!{timestamp:dd}/hour=!{timestamp:HH}/!{firehose:error-output-type}` | `Prefix`: `myPrefix/year=2018/month=07/day=06/hour=23/` `ErrorOutputPrefix`: `myErrorPrefix/year=2018/month=07/day=06/hour=23/processing-failed` |
| `Prefix`: `myFirehosePrefix/` `ErrorOutputPrefix`：未指定 | `Prefix`: `myFirehosePrefix/2018/08/27/` `ErrorOutputPrefix`: `myFirehosePrefix/processing-failed/2018/08/27/` |
# 为 OpenSearch 服务配置索引轮换
对于 OpenSearch 服务目标，您可以从以下五个选项之一中指定基于时间的索引轮换选项：**NoRotation**、**OneHour**、**OneDay****OneWeek**、或**OneMonth**。
根据您选择的轮换选项，Amazon Data Firehose 会将 UTC 到达时间戳的一部分附加到您指定的索引名称。并相应地轮换附加的时间戳。以下示例显示了 S OpenSearch ervice 中每个索引轮换选项生成的索引名称，其中指定的索引名称为**myindex**，到达时间戳为`2016-02-25T13:00:00Z`。
| RotationPeriod | IndexName |
| --- | --- |
| NoRotation | myindex |
| OneHour | myindex-2016-02-25-13 |
| OneDay | myindex-2016-02-25 |
| OneWeek | myindex-2016-w08 |
| OneMonth | myindex-2016-02 |
**注意**
使用 `OneWeek` 选项时，Data Firehose 会采用 -w 格式（例如 `2020-w33`）自动创建索引，其中周数是使用 UTC 时间并根据以下美国惯例计算的：
一周从星期日开始
一年的第一周是指这一年中包含星期六的第一周
# 暂停和恢复数据传输
设置 Firehose 流后，流来源中的可用数据将持续传输到目的地。如果遇到流目标暂时不可用的情况（例如，在计划维护操作期间），您可能需要暂时暂停数据传输，并在目标位置再次可用时恢复。
**重要**
当您使用下述方法暂停和恢复流时，在恢复流之后，您会看到很少有记录被传输到 Amazon S3 中的错误存储桶，而其余流继续传输到目的地。这是该方法的已知局限性，之所以发生这种情况，是因为有少量记录在多次重试后无法传输到目的地，被跟踪为失败。
## 暂停 Firehose 流
要暂停 Firehose 中的流传输，请先删除 Firehose 因传输失败而写入 S3 备份位置的权限。例如，如果您想暂停带有 OpenSearch 目标的 Firehose 直播，则可以通过更新权限来实现。有关更多信息，请参阅[授予 Firehose 访问公共 OpenSearch 服务目标的](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-es)权限。
删除 `s3:PutObject` 操作的 `"Effect": "Allow"` 权限，并显式添加一条语句，该语句对用于备份失败传输的 S3 存储桶的 `s3:PutObject` 操作应用 `Effect": "Deny"` 权限。接下来，关闭直播目标（例如，关闭目标 OpenSearch 网域），或者移除 Firehose 写入目标的权限。要更新其他目的地的权限，请查看[使用 Amazon Data Firehose 控制访问权限](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html)中的相关目的地部分。完成这两个操作后，Firehose 将停止传输直播，你可以使用 Fi [rehose 的CloudWatch 指标](https://docs.aws.amazon.com/firehose/latest/dev/cloudwatch-metrics.html)进行监控。
**重要**
在 Firehose 中暂停流传输时，需要确保流的来源（例如，Kinesis Data Streams 中或 Kafka 托管服务中）配置为保留数据，直到恢复流传输并将数据传输到目的地为止。如果源是 DirectPut，Firehose 将保留数据 24 小时。如果您在数据留存期到期之前未恢复流并传输数据，则可能会发生数据丢失。
## 恢复 Firehose 流
要恢复传输，请先打开目的地，并确保 Firehose 有权限将流传输到目的地，以还原之前对流目的地所做的更改。接下来，还原之前对应用于 S3 存储桶的权限所做的更改，以备份失败的传输。也就是说，应用 `s3:PutObject` 操作 `"Effect": "Allow"` 的权限，并删除 `s3:PutObject` 操作的 `"Effect": "Deny"` 权限，后者供 S3 存储桶用于备份失败的传输。最后，使用 [Firehose 的CloudWatch 指标进行](https://docs.aws.amazon.com/firehose/latest/dev/cloudwatch-metrics.html)监控，以确认直播已传送到目的地。要查看错误并对其进行故障排除，请使用[适用于 Firehose 的亚马逊 CloudWatch 日志监控](https://docs.aws.amazon.com/firehose/latest/dev/monitoring-with-cloudwatch-logs.html)。