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

# Amazon S3 交付的 S3 輸出金鑰範本
<a name="data-delivery-s3-key-template"></a>

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

## 預設範本
<a name="data-delivery-s3-key-template-default"></a>

 如果您未指定自訂金鑰範本，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 會自動將唯一的尾碼附加到每個物件金鑰，因此即使範本不包含足以區分物件金鑰的時間元件，物件金鑰也是唯一的。

## 範本變數
<a name="data-delivery-s3-key-template-variables"></a>

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


**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} | 

## 範本規則
<a name="data-delivery-s3-key-template-rules"></a>

 金鑰範本必須符合下列規則：
+ 展開所有變數後，產生的物件金鑰不得超過 1，024 個字元的 Amazon S3 物件金鑰限制。由於 Amazon Kinesis Data Streams 會附加最多 38 個字元的唯一尾碼，因此擴展的範本本身不得超過 986 個字元。
+ 不得包含路徑周遊：無連續句點 (`..`)、無僅限句點的路徑區段 (`.`)，且開頭不得為正斜線 ()`/`。
+ 不得包含連續斜線 (`//`)。
+ 每個變數預留位置都必須關閉 （每個預留位置`!{`都必須有相符的 `}`)，而且必須使用支援的變數名稱。
+ 允許的文字字元為英數字元和下列字元：`! - _ ' . * ( ) / =`。`=` 字元可讓您表達 Hive 樣式的分割，例如 `year=!{yyyy}/month=!{MM}/`。
+ 範本最多可包含一個延伸預留位置 (`!{extension}` 或 `!{extension:.{{literal}}}`)，若有的話，它必須出現在範本的結尾。
+ 啟用壓縮 (GZIP 或 ZSTD) 時，範本必須包含延伸預留位置。

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

## 有效和無效的 範例
<a name="data-delivery-s3-key-template-examples"></a>


**金鑰範本範例**  

| 範本 | 有效 | 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} （缺少關閉拉條） | 否 | 未關閉的變數預留位置。 |