本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 了解 Amazon Data Firehose 中的資料交付
當您將資料傳送至 Firehose 串流時，資料會自動傳送至您選擇的目的地。下表說明資料交付至不同目的地的方式。
| 目標 | 詳細資訊 |
| --- | --- |
| 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 Service 和 OpenSearch Serverless | 對於交付至 OpenSearch Service 和 OpenSearch Serverless 的資料，Amazon Data Firehose 會根據 Firehose 串流的緩衝組態來緩衝傳入的記錄。然後，它會產生 OpenSearch Service 或 OpenSearch Serverless 大量請求，在您的 OpenSearch Service 叢集或 OpenSearch Serverless 集合為多個記錄建立索引。將單行 JSON 物件傳送到 Amazon Data Firehose 之前，請確定您的記錄已進行 UTF-8 編碼並扁平化。此外，您還必須將 OpenSearch Service 叢集的 rest.action.multi.allow\$1explicit\$1index 選項設定為 true (預設值)，才能夠根據每筆記錄設定的明確索引接受大量請求。如需更多資訊，請參閱《Amazon OpenSearch Service 開發人員指南》中的 [Amazon OpenSearch Service 進階選項](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 Tables 和 Snowflake 目的地除外。
**Topics**
+ [了解跨 AWS 帳戶和區域的交付](across.md)
+ [了解 HTTP 端點交付請求和回應規格](httpdeliveryrequestresponse.md)
+ [處理資料交付失敗](retry.md)
+ [設定 Amazon S3 物件名稱格式](s3-object-name.md)
+ [設定 OpenSearch Service 的索引輪換](es-index-rotation.md)
+ [暫停和繼續資料交付](pause-restart-stream.md)
# 了解跨 AWS 帳戶和區域的交付
Amazon Data Firehose 支援跨 AWS 帳戶將資料交付至 HTTP 端點目的地。您選擇做為目的地的 Firehose 串流和 HTTP 端點可以屬於不同的 AWS 帳戶。
Amazon Data Firehose 也支援跨 AWS 區域將資料交付至 HTTP 端點目的地。您可以將資料從一個 AWS 區域中的 Firehose 串流傳遞到另一個區域中的 HTTP 端點 AWS 。您也可以將 HTTP 端點 URL 設定為所需的目的地，將資料從 Firehose 串流交付到 AWS 區域外的 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 回應格式規格。HTTP 端點有 3 分鐘的時間在 Amazon Data Firehose 逾時該請求之前回應請求。Amazon Data Firehose 會將不符合適當格式的回應視為交付失敗。
## 要求格式
**路徑和 URL 參數**
這些是由您作為單一 URL 欄位的一部分直接進行設定。Amazon 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**
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 不會修改和/或編碼設定的值，並照原樣使用內容。
**HTTP 標頭 – X-Amz-Firehose-Common-Attributes**
該標頭包含與整個請求和/或請求中的所有記錄有關的共同屬性 (中繼資料)。這些是由您在建立 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 狀態碼必須在 2XX、4XX 或 5XX 的範圍內。
Amazon Data Firehose 伺服器不遵循重新導向 (3XX 狀態碼）。只將回應碼 200 視為成功將記錄交付至 HTTP/EP。會將回應碼 413 (大小已超出) 視為永久失效，如果已設定，則不會將記錄批次傳送至錯誤儲存貯體。會將所有其他回應碼視為可重試的錯誤，並受限於稍後解釋的輪詢重試演算法。
**標頭 – 內容類型**
唯一可接受的內容類型是應用程式/json。
**HTTP 標頭 – Content-Encoding**
不能使用 Content-Encoding。必須對主體進行解壓縮。
**HTTP 標頭 – Content-Length**
如果回應有主體，則 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
}
```
**錯誤回應處理**
在所有錯誤情況下，Amazon Data Firehose 伺服器會使用指數退避演算法重新嘗試交付相同批次的記錄。重試會使用初始退避時間 (1 秒) 和抖動係數 (15%) 進行退避，並且每次後續重試都會使用新增抖動的公式 (initial-backoff-time \$1 (multiplier(2) ^ retry\$1count)) 來退避。退避時間受限於 2 分鐘的間隔上限。例如，在第 n 次重試時，退避時間為 = MAX(120， 2^n) \$1 random(0.85， 1.15)。
在上一個方程式中所指定的參數可能會發生變更。如需確切的初始退避時間、最大退避時間、倍數和指數退避演算法中使用的抖動百分比，請參閱 AWS Firehose 文件。
每次後續重試嘗試時，交付記錄的存取金鑰和/或目的地可能會根據 Firehose 串流的更新組態而變更。Amazon Data Firehose 服務會盡最大努力跨重試使用相同的 request-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 Service 和 OpenSearch Serverless
對於 OpenSearch Service 和 OpenSearch Serverless 目的地，您可以在 Firehose 串流建立期間指定重試持續時間 (0–7200 秒）。
交付至您的 OpenSearch Service 叢集或 OpenSearch Serverless 集合的資料可能會因為幾個原因而失敗。例如，您可能有不正確的 OpenSearch Service 叢集或 Firehose 串流的 OpenSearch Serverless 集合組態、OpenSearch Service 叢集或維護中的 OpenSearch Serverless 集合、網路故障或類似事件。在這些情況下，Amazon Data Firehose 會在指定的時間內重試，然後略過該特定索引請求。略過的文件會傳輸至 S3 儲存貯體的 `AmazonOpenSearchService_failed/`資料夾，以供手動回填使用。
對於 OpenSearch Server，每份文件具有下列 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 Serverless，每份文件具有下列 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 物件金鑰名稱會遵循 ** 格式，其中尾碼的格式為 *-------- *，且每次 Firehose 串流的組態變更時都會增加 1。您可以變更 Firehose 串流組態 （例如，S3 儲存貯體的名稱、緩衝提示、壓縮和加密）。您可以使用 Firehose 主控台或 [UpdateDestination](https://docs.aws.amazon.com/firehose/latest/APIReference/API_UpdateDestination.html) API 操作來執行此操作。
對於 *<評估字首>*，Firehose 會新增格式為 的預設時間字首`YYYY/MM/dd/HH`。此字首會在儲存貯體中建立邏輯階層，其中每個正斜線 (/) 會在階層中建立層級。您可以指定自訂字首來修改此結構，其中包含在執行時間評估的表達式。如需如何指定自訂字首的資訊，請參閱 [Amazon Simple Storage Service 物件的自訂字首](https://docs.aws.amazon.com/firehose/latest/dev/s3-prefixes.html)。
根據預設，用於時間字首和尾碼的時區為 UTC，但您可以將其變更為您偏好的時區。例如，若要使用日本標準時間而非 UTC，您可以在 AWS 管理主控台 或 [API 參數設定 (CustomTimeZone)](https://docs.aws.amazon.com/firehose/latest/APIReference/API_ExtendedS3DestinationConfiguration.html) 中將時區設定為亞洲/東京。下列清單包含 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 附加的預設副檔名：
| Configuration | 副檔名 |
| --- | --- |
| 資料格式轉換：Parquet | .parquet |
| 資料格式轉換：ORC | .orc |
| 壓縮：Gzip | .gz |
| 壓縮：Zip | .zip |
| 壓縮：Snappy | .snappy |
| 壓縮：Hadoop-Snappy | .hsnappy |
您也可以在 Firehose 主控台或 API 中指定您偏好的副檔名。副檔名必須以句號 (.) 開頭，且可包含允許的字元：0-9a-z！-\$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 儲存貯體內的資料夾。如需詳細資訊，請參閱[《Amazon Data FirehoseDeveloper 指南》中的 Amazon S3 物件名稱格式](https://docs.aws.amazon.com/firehose/latest/dev/basic-deliver.html#s3-object-name)。 * FirehoseDeveloper *
## `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，您可以在 或 API 參數設定 ([CustomTimeZone](https://docs.aws.amazon.com/firehose/latest/APIReference/API_ExtendedS3DestinationConfiguration.html)) AWS 管理主控台 中將時區設定為亞洲/東京。若要查看支援的時區清單，請參閱 [Amazon S3 物件名稱格式](https://docs.aws.amazon.com/firehose/latest/dev/basic-deliver.html#s3-object-name)。
若您在同一字首表達式內多次使用 `timestamp` 命名空間，每個執行個體的評估結果都是相同的時間。
## `firehose` 命名空間
此命名空間可使用兩個值：`error-output-type` 和 `random-string`。下表說明如何使用這兩個值。
**`firehose` 命名空間值**
| Conversion (轉換) | Description | 範例輸入 | 範例輸出 | 備註 |
| --- | --- | --- | --- | --- |
| error-output-type | 根據 Firehose 串流的組態以及失敗原因，評估下列其中一個字串：\$1processing-failed， AmazonOpenSearchService-failed， splunk-failed， format-conversion-failed， http-endpoint-failed\$1。若您在同一表達式內多次使用此值，每個執行個體的評估結果都是相同的錯誤字串。 | 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"`。如需詳細資訊，請參閱建立 Amazon Firehose 串流中的「為您的目的地選擇 Amazon S3」。 [](basic-create.md#basic-create.title)
## 語義規則
下列規則適用於 `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 OpenSearch Service 或 Splunk 且未指定`ErrorOutputPrefix`任何 時，Firehose 會使用 `Prefix` 欄位來記錄失敗。
+ 當目的地為 Amazon S3 時，Amazon S3 目的地組態中的 `Prefix` 和 `ErrorOutputPrefix` 會分別用於成功的記錄和失敗的記錄。如果您使用 AWS CLI 或 API，則可以透過其自己的 `Prefix` 和 `ErrorOutputPrefix` 使用 `ExtendedS3DestinationConfiguration` 來指定 Amazon S3 *備份*組態。
+ 當您使用 AWS 管理主控台 並將目的地設定為 Amazon S3 時，Firehose 會在目的地組態`ErrorOutputPrefix`中分別使用 `Prefix`和 來成功記錄和失敗記錄。如果您使用表達式指定字首，則必須指定包含 的錯誤字首`!{firehose:error-output-type}`。
+ 當您`ExtendedS3DestinationConfiguration`搭配 AWS CLI、 API 或 使用 CloudFormation時，如果您指定 `S3BackupConfiguration`，Firehose 不會提供預設的 `ErrorOutputPrefix`。
+ 建立 ErrorOutputPrefix 運算式時，您無法使用 `partitionKeyFromLambda` 和 `partitionKeyFromQuery` 命名空間。
## 範例字首
**`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 Service 的索引輪換
您能夠針對 OpenSearch Service 目的地指定一個以時間為基礎的索引輪換選項，其中包括下列五種選擇：**NoRotation**、**OneHour**、**OneDay**、**OneWeek** 或 **OneMonth**。
根據您選擇的輪換選項，Amazon Data Firehose 會將 UTC 到達時間戳記的一部分附加至您指定的索引名稱。並依此輪換該時間戳記。下方範例是 OpenSearch Service 中每個索引輪換選項產生的索引名稱，其中指定的索引名稱為 **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 Service 目的地](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 將停止交付串流，而且您可以使用 [Firehose 的 CloudWatch 指標](https://docs.aws.amazon.com/firehose/latest/dev/cloudwatch-metrics.html)來監控此動作。
**重要**
當您在 Firehose 中暫停串流交付時，您需要確保串流的來源 （例如 Kinesis Data Streams 或 Managed Service for Kafka) 已設定為保留資料，直到串流交付恢復且資料交付至目的地為止。如果來源是 DirectPUT，Firehose 會保留資料 24 小時。如果您未繼續串流，並在資料保留期限到期之前交付資料，則可能會發生資料遺失。
## 繼續 Firehose 串流
若要繼續交付，請先開啟目的地，並確保 Firehose 具有將串流交付至目的地的許可，將先前所做的變更還原至串流目的地。接下來，還原先前套用至 S3 儲存貯體的許可變更，以備份失敗的交付。也就是說，套用動作 `s3:PutObject` 的 `"Effect": "Allow"` 許可，並對用於備份失敗交付的 S3 儲存貯體的動作 `s3:PutObject` 移除 `"Effect": "Deny"` 許可。最後，使用 [Firehose 的 CloudWatch 指標](https://docs.aws.amazon.com/firehose/latest/dev/cloudwatch-metrics.html)進行監控，以確認串流已交付至目的地。若要檢視和疑難排解錯誤，請使用 [Firehose 的 Amazon CloudWatch Logs 監控](https://docs.aws.amazon.com/firehose/latest/dev/monitoring-with-cloudwatch-logs.html)。