View a markdown version of this page

用于 Amazon S3 交付的 S3 输出密钥模板 - Amazon Kinesis Data Streams
Default 模板模板变量模板规则有效和无效的示例

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

用于 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}（缺少右大括号） 否 未封闭的变量占位符。