了解 Amazon S3 物件的自訂字首 - Amazon Data Firehose
timestamp 命名空間firehose 命名空間partitionKeyFromLambda 和 partitionKeyFromQuery 命名空間語義規則範例字首

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

了解 Amazon S3 物件的自訂字首

交付至 Amazon S3 的物件會遵循 <evaluated prefix><suffix> 的名稱格式。您可以指定自訂字首，其中包含在執行時間評估的表達式。您指定的自訂字首會覆寫 的預設字首yyyy/MM/dd/HH。

自訂字首可使用下列形式的運算式：!{namespace:value}，其中 namespace 可為以下項目之一，如下列部分所述。

  • firehose

  • timestamp

  • partitionKeyFromQuery

  • partitionKeyFromLambda

如果字首結尾為斜線，看起來會像是 Amazon S3 儲存貯體內的資料夾。如需詳細資訊，請參閱《Amazon Data FirehoseDeveloper 指南》中的 Amazon S3 物件名稱格式。 FirehoseDeveloper

timestamp 命名空間

此命名空間的有效值為 Java DateTimeFormatter 的有效字串。例如，在 2018 年，表達式 !{timestamp:yyyy} 的評估結果為 2018。

評估時間戳記時，Firehose 會使用所寫入 Amazon S3 物件中包含的最舊記錄的大致到達時間戳記。

根據預設，時間戳記為 UTC。但是，您可以指定您偏好的時區。例如，如果您想要使用日本標準時間而非 UTC，您可以在 AWS Management Console 或 API 參數設定 (CustomTimeZone) 中將時區設定為亞洲/東京。若要查看支援的時區清單，請參閱 Amazon S3 物件名稱格式。

若您在同一字首表達式內多次使用 timestamp 命名空間，每個執行個體的評估結果都是相同的時間。

firehose 命名空間

此命名空間可使用兩個值：error-output-type 和 random-string。下表說明如何使用這兩個值。

firehose 命名空間值
Conversion (轉換) 描述 範例輸入 範例輸出 備註
error-output-type 根據 Firehose 串流的組態，以及失敗原因，評估為下列其中一個字串：{processing-failed、AmazonOpenSearchService-failed、splunk-failed、 format-conversion-failed、http-endpoint-failed}。

若您在同一表達式內多次使用此值，每個執行個體的評估結果都是相同的錯誤字串。

 myPrefix/result=!{firehose:error-output-type}/!{timestamp:yyyy/MM/dd} myPrefix/result=processing-failed/2018/08/03 error-output-type 值僅能用於 ErrorOutputPrefix 欄位中。
random-string

評估結果為 11 個字元的隨機字串。若您在同一表達式內多次使用此值，每個執行個體的評估結果為新的隨機字串。

 myPrefix/!{firehose:random-string}/ myPrefix/046b6c7f-0b/ 可用於這兩種字首類型。

您可將其放在格式字串的開頭，以取得 Amazon S3 達到極高輸送量有時需要的隨機字首。

partitionKeyFromLambda 和 partitionKeyFromQuery 命名空間

對於動態分割，您必須在 S3 儲存貯體字首中使用下列運算式格式：!{namespace:value}，其中命名空間可以是 partitionKeyFromQuery 或 partitionKeyFromLambda，也可以是兩者。如果您使用內嵌剖析來建立來源資料的分割索引鍵，則必須指定由以下格式指定之運算式所組成的 S3 儲存貯體字首值："partitionKeyFromQuery:keyID"。如果您使用 AWS Lambda 函數為來源資料建立分割索引鍵，則必須指定由以下格式指定之運算式所組成的 S3 儲存貯體字首值："partitionKeyFromLambda:keyID"。如需詳細資訊，請參閱建立 Amazon Firehose 串流中的「為您的目的地選擇 Amazon S3」。

語義規則

下列規則適用於 Prefix 及 ErrorOutputPrefix 表達式。

  • 以 timestamp 命名空間而言，不在單引號內的任何字元都將納入評估。換言之，值欄位中任何以單引號逸出的字串都將依照字面意思處理。

  • 如果您指定的字首不包含時間戳記命名空間表達式，Firehose 會將表達式附加!{timestamp:yyyy/MM/dd/HH/}到 Prefix 欄位中的值。

  • 序列 !{ 僅出現於 !{namespace:value} 表達式。

  • 僅在 Prefix 不具表達式時，ErrorOutputPrefix 才可為零。在此情況下，Prefix 評估為 <specified-prefix>yyyy/MM/DDD/HH/，而 ErrorOutputPrefix 評估為 <specified-prefix><error-output-type>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 Management Console 並將目的地設定為 Amazon S3 時，Firehose 會在目的地組態ErrorOutputPrefix中分別使用 Prefix和 來成功記錄和失敗記錄。如果您使用表達式指定字首，則必須指定包含 的錯誤字首!{firehose:error-output-type}。

  • 當您ExtendedS3DestinationConfiguration搭配 AWS CLI、 API 使用 AWS CloudFormation，或者，如果您指定 S3BackupConfiguration，Firehose 不會提供預設的 ErrorOutputPrefix。

  • 建立 ErrorOutputPrefix 運算式時，您無法使用 partitionKeyFromLambda 和 partitionKeyFromQuery 命名空間。

範例字首

Prefix 及 ErrorOutputPrefix 範例
輸入 評估的字首 (於 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/