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

# 設定 Firehose 串流
<a name="apache-iceberg-stream"></a>

若要以 Apache Iceberg Tables 做為目的地建立 Firehose 串流，您必須設定下列項目。

**注意**  
用於交付至 S3 資料表儲存貯體中資料表的 Firehose 串流設定與 Amazon S3 中的 Apache Iceberg 資料表相同。

## 設定來源和目的地
<a name="apache-iceberg-stream-source"></a>

若要將資料交付至 Apache Iceberg Tables，請選擇串流的來源。

若要設定串流的來源，請參閱[設定來源設定](configure-source.md)。

接著，選擇 **Apache Iceberg Tables** 做為目的地，並提供 Firehose 串流名稱。

## 設定資料轉換
<a name="apache-iceberg-stream-data-transform"></a>

若要對資料執行自訂轉換，例如新增或修改傳入串流中的記錄，您可以將 Lambda 函數新增至 Firehose 串流。如需在 Firehose 串流中使用 Lambda 進行資料轉換的詳細資訊，請參閱 [轉換 Amazon Data Firehose 中的來源資料](data-transformation.md)。

對於 Apache Iceberg 資料表，您必須指定如何將傳入記錄路由到不同的目的地資料表，以及您要執行的操作。向 Firehose 提供所需路由資訊的其中一種方法是使用 Lambda 函數。

如需詳細資訊，請參閱將[記錄路由到不同的 Iceberg 資料表](apache-iceberg-format-input-record.md)。

## 連接資料目錄
<a name="apache-iceberg-stream-data-catalog"></a>

Apache Iceberg 需要資料目錄才能寫入 Apache Iceberg Tables。Firehose 與 AWS Glue Data Catalog for Apache Iceberg Tables 整合。

您可以在與 Firehose 串流 AWS Glue Data Catalog 相同的帳戶中，或在跨帳戶和與 Firehose 串流相同的區域中 （預設），或在不同的區域中使用 。

如果您要將 交付至 Amazon S3 資料表，而且您正在使用主控台來設定 Firehose 串流，請選取對應至 Amazon S3 資料表目錄的目錄。如果您使用 CLI 來設定 Firehose 串流，請在`CatalogConfiguration`輸入中使用 格式`CatalogARN`：`arn:aws:glue:<region>:<account-id>:catalog/s3tablescatalog/<s3 table bucket name>`。如需詳細資訊，請參閱[設定 Firehose 串流至 Amazon S3 資料表](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-integrating-firehose.html#firehose-stream-tables)。

**注意**  
Firehose 支援 Iceberg 資料表的三個操作：插入、更新和刪除。如果沒有指定的操作，Firehose 預設會插入、將每個傳入記錄新增為新資料列，以及保留重複項目。若要改為修改現有的記錄，請指定「更新」操作，該操作使用主索引鍵來尋找和變更現有的資料列。  
範例：  
預設 （插入）：多個相同的客戶記錄會建立重複的資料列。
指定的更新：新客戶地址會更新現有記錄。

## 設定 JQ 表達式
<a name="apache-iceberg-stream-jq-exp"></a>

對於 Apache Iceberg 資料表，您必須指定如何將傳入記錄路由到不同的目的地資料表，以及要執行的操作，例如插入、更新和刪除。您可以透過設定 Firehose 的 JQ 表達式來剖析並取得必要資訊來執行此操作。如需詳細資訊，請參閱[使用 JSONQuery 表達式將路由資訊提供給 Firehose](apache-iceberg-format-input-record-different.md#apache-iceberg-route-jq)。

## 設定唯一金鑰
<a name="apache-iceberg-stream-unique-key"></a>

**具有多個資料表的更新和刪除** – 唯一索引鍵是您來源記錄中的一個或多個欄位，可唯一識別 Apache Iceberg 資料表中的資料列。如果您只插入具有多個資料表的案例，則不需要設定唯一金鑰。如果您想要對特定資料表執行更新和刪除，則必須為這些必要資料表設定唯一金鑰。請注意，如果資料表中的資料列遺失，更新會自動插入資料列。如果您只有單一資料表，則可以設定唯一金鑰。對於更新操作，Firehose 會先放置刪除檔案，再放置插入。

您可以將每個資料表的唯一索引鍵設定為 Firehose 串流建立的一部分，也可以在[建立資料表](https://iceberg.apache.org/docs/1.5.1/spark-ddl/#create-table)或修改[資料表](https://iceberg.apache.org/docs/1.5.1/spark-ddl/#alter-table-set-identifier-fields)操作期間，在 Iceberg 中原生設定[identifier-field-ids](https://iceberg.apache.org/spec/#identifier-field-ids)。在建立串流期間為每個資料表設定唯一索引鍵是選用的。如果您在建立串流期間未為每個資料表設定唯一索引鍵，Firehose 會檢查`identifier-field-ids`所需的資料表，並將其用作唯一索引鍵。如果未設定兩者，則具有更新和刪除操作的資料交付會失敗。

若要設定本節，請提供您要更新或刪除資料的資料表的資料庫名稱、資料表名稱和唯一索引鍵。組態中每個資料表只能有項目。您不需要為僅附加的案例設定本節。如果資料表中的資料無法交付，您也可以選擇提供錯誤儲存貯體字首，如下列範例所示。

```
[
  {
    "DestinationDatabaseName": "MySampleDatabase",
    "DestinationTableName": "MySampleTable",
    "UniqueKeys": [
      "COLUMN_PLACEHOLDER"
    ],
    "S3ErrorOutputPrefix": "OPTIONAL_PREFIX_PLACEHOLDER"
  }
]
```

如果提供的欄名稱在整個資料表中是唯一的，Firehose 支援唯一索引鍵的組態。不過，它不支援將完整資料欄名稱做為唯一索引鍵。例如，如果資料欄名稱`_id`也出現在最上層，則名為 的金鑰`top._id`不會被視為唯一金鑰。如果 在整個資料表中`_id`是唯一的，則會使用它，無論其在資料表結構中的位置為何。這是最上層資料欄或巢狀資料欄。在下列範例中， `_id`是結構描述的有效唯一索引鍵，因為資料欄名稱在結構描述中是唯一的。

```
[
 "schema": {
  "type": "struct",
  "fields": [
    {
      "name": "top",
      "type": {
        "type": "struct",
        "fields": [
          { "name": "_id", "type": "string" },
          { "name": "name", "type": "string" }
        ]
      }
    },
    { "name": "user", "type": "string" }
  ]
}
]
```

在下列範例中， `_id`不是結構描述的有效唯一索引鍵，因為它同時用於頂層資料欄和巢狀結構。

```
[
"schema": {
  "type": "struct",
  "fields": [
    {
      "name": "top",
      "type": {
        "type": "struct",
        "fields": [
          { "name": "_id", "type": "string" },
          { "name": "name", "type": "string" }
        ]
      }
    },
    { "name": "_id", "type": "string" }
  ]
}
]
```

## 指定重試持續時間
<a name="apache-iceberg-stream-retry-duration"></a>

您可以使用此組態來指定 Firehose 在寫入 Amazon S3 中的 Apache Iceberg Tables 時，應嘗試重試的持續時間，以秒為單位。您可以為執行重試設定 0 到 7200 秒的任何值。根據預設，Firehose 會重試 300 秒。

## 處理失敗的交付或處理
<a name="apache-iceberg-stream-failed-delivery"></a>

您必須設定 Firehose 將記錄交付至 S3 備份儲存貯體，以防其在重試持續時間到期後處理或交付串流失敗。為此，請從 主控台的備份設定中設定 **S3 備份儲存貯**體和 **S3 備份儲存貯體錯誤輸出字首**。 ****

## 錯誤處理
<a name="apache-iceberg-handle-errors"></a>

Firehose 將所有交付錯誤傳送到 CloudWatch Logs 和 Amazon S3 錯誤儲存貯體。

錯誤清單：


|  **錯誤訊息**  |  ****Description****  | 
| --- | --- | 
| `Iceberg.NoSuchTable` | Firehose 正在寫入不存在的資料表，或資料表不是 V2 格式。Firehose 不支援 V1 格式的資料表。 | 
| `Iceberg.InvalidTableName` | 傳遞 null 或空白資料表名稱，或資料表不是 V2 格式。Firehosedoes 不支援 V1 格式的資料表。 | 
| `S3.AccessDenied` | 確定在先決條件步驟中建立的 IAM 角色具有必要的許可和信任政策。 | 
| `Glue.AccessDenied` | 確定在先決條件步驟中建立的 IAM 角色具有必要的許可和信任政策。 | 

## 設定緩衝提示
<a name="apache-iceberg-stream-buffer"></a>

Firehose 會將記憶體中的傳入串流資料緩衝至特定大小 **（緩衝大小**) 和一段特定時間 **（緩衝間隔**)，再交付至 Apache Iceberg Tables。您可以選擇 1–128 MiBs緩衝區大小，以及 0–900 秒的緩衝區間隔。較高的緩衝提示會導致較低的 S3 寫入次數、因較大的資料檔案而降低壓縮成本，以及更快的查詢執行時間，但延遲較高。較低的緩衝區提示值會以較低的延遲交付資料。

## 配置進階設定
<a name="apache-iceberg-stream-advance-settings"></a>

您可以設定 Apache Iceberg Tables 的伺服器端加密、錯誤記錄、許可和標籤。如需詳細資訊，請參閱[配置進階設定](create-configure-advanced.md)。您必須新增在 中建立的 IAM 角色[使用 Apache Iceberg 資料表做為目的地的先決條件](apache-iceberg-prereq.md)。Firehose 將擔任存取 AWS Glue 資料表和寫入 Amazon S3 儲存貯體的角色。

Firehose 串流建立可能需要幾分鐘的時間才能完成。成功建立 Firehose 串流後，您可以開始將資料擷取到其中，並且可以在 Apache Iceberg 資料表中檢視資料。