了解 Amazon S3 对象的自定义前缀 - Amazon Data Firehose
timestamp 命名空间firehose 命名空间partitionKeyFromLambda 和 partitionKeyFromQuery 命名空间语义规则示例前缀

将 Amazon Data Firehose 流传输到亚马逊 S3 中的 Apache Iceberg Tables 处于预览阶段，可能会发生变化。

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

了解 Amazon S3 对象的自定义前缀

交付到 Amazon S3 的对象的名称格式为<evaluated prefix><suffix>。您可以指定包含在运行时计算的表达式的自定义前缀。您指定的自定义前缀将覆盖的默认前缀YYYY/MM/dd/HH。

您可以在自定义前缀中使用以下形式的表达式：!{namespace:value}，其中 namespace 可以是以下形式之一，如以下各部分所述。

  • firehose

  • timestamp

  • partitionKeyFromQuery

  • partitionKeyFromLambda

如果前缀以斜杠结束，则在 Amazon S3 存储桶中将显示为文件夹。有关更多信息，请参阅《亚马逊数据 FirehoseDeveloper指南》中的 Amazon S3 对象名称格式。

timestamp 命名空间

此命名空间的有效值是有效的 Java DateTimeFormatter 字符串的字符串。例如，对于 2018 年，表达式 !{timestamp:yyyy} 的计算结果为 2018。

在评估时间戳时，Firehose 使用正在写入的 Amazon S3 对象中包含的最旧记录的大致到达时间戳。

默认情况下，时间戳位于。UTC但是，您可以指定自己喜欢的时区。例如，如果您想使用日本标准时间代替，则可以在 AWS Management Console 或API参数设置 (CustomTimeZone) 中将时区配置为亚洲/东京。UTC要查看支持的时区列表，请参阅 Amazon S3 对象名称格式。

如果您在同一前缀表达式中多次使用 timestamp 命名空间，则每个实例的计算结果为同一时刻。

firehose 命名空间

您可以将两个值用于此命名空间：error-output-type 和 random-string。下表介绍了其使用方法。

firehose 命名空间值
转换 描述 示例输入 示例输出 注意
error-output-type 根据您的 Firehose 直播的配置和失败原因，计算结果为以下字符串之一：{处理失败、-失败、splunk-failed、splunk-failed AmazonOpenSearchService、、}。 format-conversion-failed http-endpoint-failed

如果您在同一表达式中多次使用它，则每个实例的计算结果为同一错误字符串。

 myPrefix/result=!{firehose:error-output-type}/!{timestamp:yyyy/MM/dd} myPrefix/result=processing-failed/2018/08/03 该 error-output-type 值只能在 ErrorOutputPrefix字段中使用。
random-string

计算结果为 11 个字符的随机字符串。如果您在同一表达式中多次使用它，则每个实例的计算结果为一个新的随机字符串。

 myPrefix/!{firehose:random-string}/ myPrefix/046b6c7f-0b/ 您可以将它用于这两种前缀类型。

您可以将此字符串放在格式字符串的开头以获取随机前缀，若想使用 Amazon S3 获得极高的吞吐量，此操作有时十分必要。

partitionKeyFromLambda 和 partitionKeyFromQuery 命名空间

对于动态分区，您必须在 S3 存储桶前缀中使用以下表达式格式：!{namespace:value}，其中命名空间可以是 partitionKeyFromQuery 或 partitionKeyFromLambda，也可以是两者。如果使用内联解析为源数据创建分区键，则必须指定一个 S3 存储桶前缀值，该值由以下格式指定的表达式组成："partitionKeyFromQuery:keyID"。如果使用 AWS Lambda 函数为源数据创建分区键，则必须指定一个 S3 存储桶前缀值，该值由以下格式指定的表达式组成："partitionKeyFromLambda:keyID"。有关更多信息，请参阅创建亚马逊 Firehose 直播中的 “选择亚马逊 S3 作为您的目的地”。

语义规则

以下规则适用于 Prefix 和 ErrorOutputPrefix 表达式。

  • 对于 timestamp 命名空间，将计算未包含在单引号内的任何字符。换句话说，将按字面意思处理值字段中使用单引号进行转义的任何字符串。

  • 如果您指定的前缀不包含时间戳命名空间表达式，Firehose 会将该!{timestamp:yyyy/MM/dd/HH/}表达式附加到字段中的值。Prefix

  • 序列 !{ 只能出现在 !{namespace:value} 表达式中。

  • 仅当 Prefix 未包含任何表达式时，ErrorOutputPrefix 才能为空。在这种情况下，Prefix 的计算结果为 <specified-prefix>yyyy/MM/DDD/HH/，ErrorOutputPrefix 计算结果为 <specified-prefix><error-output-type>YYYY/MM/DDD/HH/。DDD 表示一年中的某天。

  • 如果您为 ErrorOutputPrefix 指定一个表达式，则您必须包含至少一个 !{firehose:error-output-type} 实例。

  • Prefix 无法包含 !{firehose:error-output-type}。

  • Prefix 和 ErrorOutputPrefix 在计算后都不能超过 512 个字符。

  • 如果目标位置是 Amazon Redshift，则 Prefix 不能包含表达式并且 ErrorOutputPrefix 必须为空。

  • 如果目标是 Amazon S OpenSearch ervice 或 Splunk，但未ErrorOutputPrefix指定任何值，Firehose 会使用Prefix该字段来记录失败的记录。

  • 当目标位置是 Amazon S3 时，Amazon S3 目标配置中的 Prefix 和 ErrorOutputPrefix 将分别用于成功记录和失败记录。如果您使用 AWS CLI 或API，则可以使用使用自己的Prefix和ExtendedS3DestinationConfiguration来指定 Amazon S3 备份配置ErrorOutputPrefix。

  • 当您使用 AWS Management Console 并将目标设置为 Amazon S3 时，Firehose 将分别使用目标配置ErrorOutputPrefix中的Prefix和来记录成功记录和失败记录。如果您指定前缀但未指定错误前缀，Firehose 会自动将错误前缀设置为。!{firehose:error-output-type}/

  • 当你ExtendedS3DestinationConfiguration与 AWS CLI、或一起使用时 API AWS CloudFormation，如果你指定了S3BackupConfiguration，Firehose 不会提供默认值。ErrorOutputPrefix

  • 创建 ErrorOutputPrefix 表达partitionKeyFromQuery式时不能使用partitionKeyFromLambda和命名空间。

示例前缀

Prefix 和 ErrorOutputPrefix 示例
输入 已评估前缀（2018 年 8 月 27 日UTC上午 10:30）

Prefix：未指定

ErrorOutputPrefix: myFirehoseFailures/!{firehose:error-output-type}/

Prefix: 2018/08/27/10

ErrorOutputPrefix: myFirehoseFailures/processing-failed/

Prefix: !{timestamp:yyyy/MM/dd}

ErrorOutputPrefix：未指定

 输入无效：当 Prefix 包含表达式时，ErrorOutputPrefix 不能为空

Prefix: myFirehose/DeliveredYear=!{timestamp:yyyy}/anyMonth/rand=!{firehose:random-string}

ErrorOutputPrefix: myFirehoseFailures/!{firehose:error-output-type}/!{timestamp:yyyy}/anyMonth/!{timestamp:dd}

Prefix: myFirehose/DeliveredYear=2018/anyMonth/rand=5abf82daaa5

ErrorOutputPrefix: myFirehoseFailures/processing-failed/2018/anyMonth/10

Prefix: myPrefix/year=!{timestamp:yyyy}/month=!{timestamp:MM}/day=!{timestamp:dd}/hour=!{timestamp:HH}/

ErrorOutputPrefix: myErrorPrefix/year=!{timestamp:yyyy}/month=!{timestamp:MM}/day=!{timestamp:dd}/hour=!{timestamp:HH}/!{firehose:error-output-type}

Prefix: myPrefix/year=2018/month=07/day=06/hour=23/

ErrorOutputPrefix: myErrorPrefix/year=2018/month=07/day=06/hour=23/processing-failed

Prefix: myFirehosePrefix/

ErrorOutputPrefix：未指定

Prefix: myFirehosePrefix/2018/08/27/

ErrorOutputPrefix: myFirehosePrefix/processing-failed/2018/08/27/