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

# 了解 Amazon S3 对象的自定义前缀
<a name="s3-prefixes"></a>

传输到 Amazon S3 的对象遵循 <evaluated prefix><suffix> 的[名称格式](https://docs.amazonaws.cn/firehose/latest/dev/basic-deliver.html#s3-object-namekey)。您可以指定包含在运行时进行估算的表达式的自定义前缀。您指定的自定义前缀将覆盖的默认前缀 `yyyy/MM/dd/HH`。

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

如果前缀以斜杠结束，则在 Amazon S3 存储桶中将显示为文件夹。有关更多信息，请参阅《[亚马逊*数据 FirehoseDeveloper指南》中的 Amazon* S3 对象名称格式](https://docs.amazonaws.cn/firehose/latest/dev/basic-deliver.html#s3-object-name)。

## `timestamp` 命名空间
<a name="timestamp-namespace"></a>

此命名空间的有效值是有效的 [Java DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) 字符串的字符串。例如，对于 2018 年，表达式 `!{timestamp:yyyy}` 的计算结果为 `2018`。

在计算时间戳时，Firehose 将使用所写入 Amazon S3 对象中包含的最早记录的大致到达时间戳。

默认情况下，时间戳按 UTC 时间。但是，您可以指定偏好的时区。例如，如果您想使用日本标准时间而不是 UTC，则可以在 Amazon Web Services 管理控制台 或 API 参数设置 ([CustomTimeZone](https://docs.amazonaws.cn/firehose/latest/APIReference/API_ExtendedS3DestinationConfiguration.html)) 中将时区配置为。 Asia/Tokyo 要查看支持的时区列表，请参阅 [Amazon S3 Object Name Format](https://docs.amazonaws.cn/firehose/latest/dev/basic-deliver.html#s3-object-name)。

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

## `firehose` 命名空间
<a name="firehose-namespace"></a>

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


**`firehose` 命名空间值**  

| 转换 | 说明 | 示例输入 |  输出示例 | 注意 | 
| --- | --- | --- | --- | --- | 
| error-output-type | 根据您的 Firehose 直播的配置和失败原因，计算结果为以下字符串之一：\$1处理失败、-失败、splunk-failed、splunk-failed AmazonOpenSearchService、、\$1。 format-conversion-failed http-endpoint-failed如果您在同一表达式中多次使用它，则每个实例的计算结果为同一错误字符串。 | myPrefix/result=\$1\$1firehose:error-output-type\$1/\$1\$1timestamp:yyyy/MM/dd\$1 | myPrefix/result=processing-failed/2018/08/03 | 该 error-output-type值只能在 ErrorOutputPrefix字段中使用。 | 
| random-string |  计算结果为 11 个字符的随机字符串。如果您在同一表达式中多次使用它，则每个实例的计算结果为一个新的随机字符串。  | myPrefix/\$1\$1firehose:random-string\$1/ | myPrefix/046b6c7f-0b/ | 您可以将它用于这两种前缀类型。您可以将此字符串放在格式字符串的开头以获取随机前缀，若想使用 Amazon S3 获得极高的吞吐量，此操作有时十分必要。 | 

## `partitionKeyFromLambda` 和 `partitionKeyFromQuery` 命名空间
<a name="dynamic-partitioning-namespaces"></a>

对于[动态分区](dynamic-partitioning.md)，您必须在 S3 存储桶前缀中使用以下表达式格式：`!{namespace:value}`，其中命名空间可以是 `partitionKeyFromQuery` 或 `partitionKeyFromLambda`，也可以是两者。如果使用内联解析为源数据创建分区键，则必须指定一个 S3 存储桶前缀值，该值由以下格式指定的表达式组成：`"partitionKeyFromQuery:keyID"`。如果使用 Amazon Lambda 函数为源数据创建分区键，则必须指定一个 S3 存储桶前缀值，该值由以下格式指定的表达式组成：`"partitionKeyFromLambda:keyID"`。有关更多信息，请参阅 [Creating an Amazon Firehose stream](basic-create.md#basic-create.title) 中的“Choose Amazon S3 for Your Destination”。

## 语义规则
<a name="prefix-rules"></a>

以下规则适用于 `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` 将分别用于成功记录和失败记录。如果使用 Amazon CLI 或 API，则可使用 `ExtendedS3DestinationConfiguration` 指定具有自己的 `Prefix` 和 `ErrorOutputPrefix` 的 Amazon S3 *备份*配置。
+ 当您使用 Amazon Web Services 管理控制台 并将目标设置为 Amazon S3 时，Firehose 将分别使用目标配置`ErrorOutputPrefix`中的`Prefix`和来记录成功记录和失败记录。如果使用表达式指定前缀，则必须指定错误前缀，包括 `!{firehose:error-output-type}`。
+ 当你`ExtendedS3DestinationConfiguration`与 Amazon CLI、API 或者 Amazon CloudFormation（如果您指定了）一起使用时`S3BackupConfiguration`，Firehose 不会提供默认值。`ErrorOutputPrefix`
+ 创建 ErrorOutputPrefix 表达`partitionKeyFromQuery`式时不能使用`partitionKeyFromLambda`和命名空间。

## 示例前缀
<a name="s3-prefix-examples"></a>


**`Prefix` 和 `ErrorOutputPrefix` 示例**  

| Input | 计算的前缀 [2018 年 8 月 27 日上午 10:30（UTC）] | 
| --- | --- | 
|  `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/`  |