View a markdown version of this page

Amazon S3 交付的 S3 輸出金鑰範本 - Amazon Kinesis Data Streams
預設範本範本變數範本規則有效和無效的 範例

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

Amazon S3 交付的 S3 輸出金鑰範本

交付至一般用途 Amazon S3 儲存貯體時，您可以設定 S3 輸出金鑰範本，以控制交付檔案的物件金鑰結構。金鑰範本為選用 – 如果未指定，Amazon S3 交付會使用預設範本。

預設範本

如果您未指定自訂金鑰範本，Amazon S3 交付會使用下列預設值：

kinesis-channel/!{channel-name}/!{channel-id}/!{yyyy}/!{MM}/!{dd}/!{HH}/!{channel-name}-!{channel-id}-!{yyyy}-!{MM}-!{dd}-!{HH}-!{mm}!{extension}

最後一個正斜線 (/) 之前的部分會形成物件金鑰字首 （資料夾結構），而最後一個區段會形成物件名稱。預設範本會依頻道和小時整理交付的物件，並在物件名稱中重複相同的值，讓每個物件都自我描述。Amazon Kinesis Data Streams 會自動將唯一的尾碼附加到每個物件金鑰，因此即使範本不包含足以區分物件金鑰的時間元件，物件金鑰也是唯一的。

範本變數

下列變數可用於您的金鑰範本：

S3 金鑰範本變數
變數 說明 範例值
!{channel-name} 交付的名稱。 my-channel
!{channel-id} 交付的唯一識別符。 abc123def456
!{stream-name} 來源 Kinesis Data Streams 串流的名稱。 my-stream
!{yyyy} 四位數年份 (UTC)。 2026
!{yy} 兩位數年份 (UTC)。 26
!{MM} 兩位數月份 (UTC)，零填充。 07
!{dd} 一個月中的兩位數日 (UTC)，零填充。 20
!{HH} 兩位數小時 (UTC，24 小時），零填充。 14
!{mm} 兩位數分鐘 (UTC)，零填充。 30
!{extension} 從設定的壓縮類型衍生的副檔名 （例如 .gz GZIP 或 .zst ZSTD)。如果存在，它必須出現在範本的結尾。 .gz
!{extension:.literal} 您指定的常值副檔名。必須以句點開頭，且只包含小寫字母和句點。如果存在，它必須出現在範本的結尾。 !{extension:.json}

範本規則

金鑰範本必須符合下列規則：

  • 展開所有變數後，產生的物件金鑰不得超過 1，024 個字元的 Amazon S3 物件金鑰限制。由於 Amazon Kinesis Data Streams 會附加最多 38 個字元的唯一尾碼，因此擴展的範本本身不得超過 986 個字元。

  • 不得包含路徑周遊：無連續句點 (..)、無僅限句點的路徑區段 (.)，且開頭不得為正斜線 ()/。

  • 不得包含連續斜線 (//)。

  • 每個變數預留位置都必須關閉 （每個預留位置!{都必須有相符的 })，而且必須使用支援的變數名稱。

  • 允許的文字字元為英數字元和下列字元：! - _ ' . * ( ) / =。= 字元可讓您表達 Hive 樣式的分割，例如 year=!{yyyy}/month=!{MM}/。

  • 範本最多可包含一個延伸預留位置 (!{extension} 或 !{extension:.literal})，若有的話，它必須出現在範本的結尾。

  • 啟用壓縮 (GZIP 或 ZSTD) 時，範本必須包含延伸預留位置。

注意

您不需要在範本中包含唯一性變數。Amazon Kinesis Data Streams 會自動將唯一的尾碼附加到每個交付的物件金鑰。

有效和無效的 範例

金鑰範本範例
範本 有效 Reason
!{channel-name}/!{yyyy}/!{MM}/!{dd}/!{HH}/records!{extension} 是 使用支援的變數，並以單一延伸預留位置結尾。
data/stream=!{stream-name}/!{yyyy}-!{MM}-!{dd}/!{HH}!{mm}!{extension:.json} 是 Hive 樣式分割，尾端為常值延伸。
!{channel-name}/!{channel-id} 是 最小範本。Kinesis Data Streams 會自動附加唯一的尾碼。
/data/!{channel-name}!{extension} 否 從正斜線開始。
data/../!{channel-name}!{extension} 否 包含路徑周遊 (..)。
data//!{channel-name}!{extension} 否 包含連續斜線 (//)。
!{channel-name}!{extension}/!{yyyy} 否 延伸預留位置不在範本的結尾。
data/!{partition-id}!{extension} 否 !{partition-id} 不是支援的變數。
data/!{channel-name} （使用 GZIP 或 ZSTD 壓縮） 否 壓縮已啟用，但範本沒有延伸預留位置。
data/!{channel-name}/!{yyyy} （缺少關閉拉條） 否 未關閉的變數預留位置。