View a markdown version of this page

用于 Amazon S3 交付的 S3 输出密钥模板 - Amazon Kinesis Data Streams
Default 模板模板变量模板规则有效和无效的示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

用于 Amazon S3 交付的 S3 输出密钥模板

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

Default 模板

如果您未指定自定义密钥模板，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 数据流的名称。 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}

模板规则

密钥模板必须符合以下规则：

  • 扩展所有变量后，生成的对象密钥不得超过 Amazon S3 对象密钥限制，即 1,024 个字符。由于 Amazon Kinesis 数据流会附加最多 38 个字符的唯一后缀，因此扩展模板本身不得超过 986 个字符。

  • 不得包含路径遍历：没有连续的句点 (..)，没有仅限句点的路径段 (.)，并且不得以正斜杠 () 开头。/

  • 不得包含连续的斜杠 (//)。

  • 每个变量占位符都必须关闭（每个占位符!{必须有匹配}项），并且必须使用支持的变量名称。

  • 允许使用的文字字符是字母数字字符和以下字符:. ! - _ ' . * ( ) / = 该=角色可以让你表达 Hive-style 分区，例如year=!{yyyy}/month=!{MM}/。

  • 模板最多可以包含一个扩展占位符（!{extension}或!{extension:.literal}），如果存在，它必须出现在模板的末尾。

  • 启用压缩（GZIP 或 ZSTD）时，模板必须包含扩展占位符。

注意

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

有效和无效的示例

关键模板示例
模板 有效 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}（缺少右大括号） 否 未封闭的变量占位符。