本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 了解 Amazon S3 物件的自訂字首
<a name="s3-prefixes"></a>

交付至 Amazon S3 的物件會遵循 <evaluated prefix><suffix> [的名稱格式](https://docs.aws.amazon.com/firehose/latest/dev/basic-deliver.html#s3-object-namekey)。您可以指定自訂字首，其中包含在執行時間評估的表達式。您指定的自訂字首會覆寫 的預設字首`yyyy/MM/dd/HH`。

自訂字首可使用下列形式的運算式：`!{namespace:{{value}}}`，其中 `namespace` 可為以下項目之一，如下列部分所述。
+  `firehose` 
+ `timestamp`
+ `partitionKeyFromQuery`
+ `partitionKeyFromLambda`

如果字首結尾為斜線，看起來會像是 Amazon S3 儲存貯體內的資料夾。如需詳細資訊，請參閱[《Amazon Data FirehoseDeveloper 指南》中的 Amazon S3 物件名稱格式](https://docs.aws.amazon.com/firehose/latest/dev/basic-deliver.html#s3-object-name)。 * FirehoseDeveloper *

## `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，您可以在 或 API 參數設定 ([CustomTimeZone](https://docs.aws.amazon.com/firehose/latest/APIReference/API_ExtendedS3DestinationConfiguration.html)) AWS 管理主控台 中將時區設定為亞洲/東京。若要查看支援的時區清單，請參閱 [Amazon S3 物件名稱格式](https://docs.aws.amazon.com/firehose/latest/dev/basic-deliver.html#s3-object-name)。

若您在同一字首表達式內多次使用 `timestamp` 命名空間，每個執行個體的評估結果都是相同的時間。

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

此命名空間可使用兩個值：`error-output-type` 和 `random-string`。下表說明如何使用這兩個值。


**`firehose` 命名空間值**  

| Conversion (轉換) | Description | 範例輸入 | 範例輸出 | 備註 | 
| --- | --- | --- | --- | --- | 
| error-output-type | 根據 Firehose 串流的組態以及失敗原因，評估下列其中一個字串：{processing-failed， AmazonOpenSearchService-failed， splunk-failed， 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` 命名空間
<a name="dynamic-partitioning-namespaces"></a>

對於[動態分割](dynamic-partitioning.md)，您必須在 S3 儲存貯體字首中使用下列運算式格式：`!{namespace:value}`，其中命名空間可以是 `partitionKeyFromQuery` 或 `partitionKeyFromLambda`，也可以是兩者。如果您使用內嵌剖析來建立來源資料的分割索引鍵，則必須指定由以下格式指定之運算式所組成的 S3 儲存貯體字首值：`"partitionKeyFromQuery:keyID"`。如果您使用 AWS Lambda 函數為來源資料建立分割索引鍵，則必須指定由以下格式指定之運算式所組成的 S3 儲存貯體字首值：`"partitionKeyFromLambda:keyID"`。如需詳細資訊，請參閱建立 Amazon Firehose 串流中的「為您的目的地選擇 Amazon S3」。 [](basic-create.md#basic-create.title)

## 語義規則
<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 OpenSearch Service 或 Splunk 且未指定`ErrorOutputPrefix`任何 時，Firehose 會使用 `Prefix` 欄位來記錄失敗。
+ 當目的地為 Amazon S3 時，Amazon S3 目的地組態中的 `Prefix` 和 `ErrorOutputPrefix` 會分別用於成功的記錄和失敗的記錄。如果您使用 AWS CLI 或 API，則可以透過其自己的 `Prefix` 和 `ErrorOutputPrefix` 使用 `ExtendedS3DestinationConfiguration` 來指定 Amazon S3 *備份*組態。
+ 當您使用 AWS 管理主控台 並將目的地設定為 Amazon S3 時，Firehose 會在目的地組態`ErrorOutputPrefix`中分別使用 `Prefix`和 來成功記錄和失敗記錄。如果您使用表達式指定字首，則必須指定包含 的錯誤字首`!{firehose:error-output-type}`。
+ 當您`ExtendedS3DestinationConfiguration`搭配 AWS CLI、 API 或 使用 CloudFormation時，如果您指定 `S3BackupConfiguration`，Firehose 不會提供預設的 `ErrorOutputPrefix`。
+ 建立 ErrorOutputPrefix 運算式時，您無法使用 `partitionKeyFromLambda` 和 `partitionKeyFromQuery` 命名空間。

## 範例字首
<a name="s3-prefix-examples"></a>


**`Prefix` 及 `ErrorOutputPrefix` 範例**  

| Input | 評估的字首 (於 2018 年 8 月 27 日上午 10:30 UTC) | 
| --- | --- | 
| `Prefix`：未指定<br />`ErrorOutputPrefix`: `myFirehoseFailures/!{firehose:error-output-type}/` | `Prefix`: `2018/08/27/10`<br />`ErrorOutputPrefix`: `myFirehoseFailures/processing-failed/` | 
| `Prefix`: `!{timestamp:yyyy/MM/dd}`<br />`ErrorOutputPrefix`：未指定 | 無效輸入：Prefix 具有表達式時，ErrorOutputPrefix 不可為零 | 
| `Prefix`: `myFirehose/DeliveredYear=!{timestamp:yyyy}/anyMonth/rand=!{firehose:random-string}`<br />`ErrorOutputPrefix`: `myFirehoseFailures/!{firehose:error-output-type}/!{timestamp:yyyy}/anyMonth/!{timestamp:dd}` | `Prefix`: `myFirehose/DeliveredYear=2018/anyMonth/rand=5abf82daaa5`<br />`ErrorOutputPrefix`: `myFirehoseFailures/processing-failed/2018/anyMonth/10` | 
| `Prefix`: `myPrefix/year=!{timestamp:yyyy}/month=!{timestamp:MM}/day=!{timestamp:dd}/hour=!{timestamp:HH}/`<br />`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/`<br />`ErrorOutputPrefix`: `myErrorPrefix/year=2018/month=07/day=06/hour=23/processing-failed` | 
| `Prefix`: `myFirehosePrefix/`<br />`ErrorOutputPrefix`：未指定 | `Prefix`: `myFirehosePrefix/2018/08/27/`<br />`ErrorOutputPrefix`: `myFirehosePrefix/processing-failed/2018/08/27/` |