本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 用于 Amazon S3 交付的 S3 输出密钥模板
<a name="data-delivery-s3-key-template"></a>

 向通用的 Amazon S3 存储桶传输时，您可以配置 S3 输出密钥模板来控制已交付文件的对象密钥结构。密钥模板是可选的——如果未指定，Amazon S3 交付将使用默认模板。

## Default 模板
<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 数据流的名称。 | my-stream | 
| \!{yyyy} | Four-digit 年 (UTC)。 | 2026 | 
| \!{yy} | Two-digit 年 (UTC)。 | 26 | 
| \!{MM} | Two-digit 月 (UTC)，零填充。 | 07 | 
| \!{dd} | Two-digit 月中某一天 (UTC)，填充为零。 | 20 | 
| \!{HH} | Two-digit 小时（UTC，24 小时），零填充。 | 14 | 
| \!{mm} | Two-digit 分钟 (UTC)，零填充。 | 30 | 
| \!{extension} | 从配置的压缩类型（例如，对于 GZIP 或 ZSTD）派生.zst的文件扩展名。.gz如果存在，它必须出现在模板的末尾。 | .gz | 
| \!{extension:.{{literal}}} | 您指定的文字文件扩展名。必须以句点开头，并且仅包含小写字母和句点。如果存在，它必须出现在模板的末尾。 | \!{extension:.json} | 

## 模板规则
<a name="data-delivery-s3-key-template-rules"></a>

 密钥模板必须符合以下规则：
+ 扩展所有变量后，生成的对象密钥不得超过 Amazon S3 对象密钥限制，即 1,024 个字符。由于 Amazon Kinesis 数据流会附加最多 38 个字符的唯一后缀，因此扩展模板本身不得超过 986 个字符。
+ 不得包含路径遍历：没有连续的句点 (`..`)，没有仅限句点的路径段 (`.`)，并且不得以正斜杠 () 开头。`/`
+ 不得包含连续的斜杠 (`//`)。
+ 每个变量占位符都必须关闭（每个占位符`!{`必须有匹配`}`项），并且必须使用支持的变量名称。
+ 允许使用的文字字符是字母数字字符和以下字符:. `! - _ ' . * ( ) / =` 该`=`角色可以让你表达 Hive-style 分区，例如`year=!{yyyy}/month=!{MM}/`。
+ 模板最多可以包含一个扩展占位符（`!{extension}`或`!{extension:.{{literal}}}`），如果存在，它必须出现在模板的末尾。
+ 启用压缩（GZIP 或 ZSTD）时，模板必须包含扩展占位符。

**注意**  
 您无需在模板中包含唯一性变量。Amazon Kinesis 数据流会自动为每个交付的对象密钥附加一个唯一的后缀。

## 有效和无效的示例
<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-style 最后用文字扩展名进行分区。 | 
| \!{channel-name}/\!{channel-id} | 是 | 最小模板。Kinesis 数据流会自动附加一个唯一的后缀。 | 
| /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}（缺少右大括号） | 否 | 未封闭的变量占位符。 |