自 2026 年 4 月 20 日起，BigLake 將改名為 Lakehouse for Apache Iceberg。BigLake metastore 現在稱為 Lakehouse 執行階段目錄。湖倉 API、用戶端程式庫、CLI 指令和 IAM 名稱維持不變，仍會參照 BigLake。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

設定 Lakehouse Iceberg REST 目錄

對於新的工作流程，建議您使用 Lakehouse 執行階段目錄中的 Apache Iceberg REST 目錄端點。

這個端點可做為單一事實來源，讓查詢引擎之間順暢互通。可讓 Apache Spark 等引擎以一致的方式探索、讀取及管理 Google Cloud Lakehouse 資料表。

如果您使用開放原始碼引擎存取 Cloud Storage 中的資料，且需要與其他引擎 (包括 BigQuery) 互通，這個方法就是不錯的選擇。支援憑證販售等功能，可進行精細的存取控管，以及跨區域複製和災難復原。

相較之下，BigQuery 的自訂 Apache Iceberg 目錄端點是較早的整合項目。現有工作流程仍可繼續使用，但 REST 目錄提供更標準化且功能豐富的體驗。

事前準備

繼續操作前，請先熟悉 Lakehouse 執行階段目錄和 Iceberg REST 目錄端點總覽。

確認專案已啟用計費功能 Google Cloud 。
啟用 BigLake API。
啟用 API 時所需的角色
如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。
啟用 API

必要的角色

如要取得在 Lakehouse 執行階段目錄中使用 Apache Iceberg REST 目錄端點所需的權限，請要求管理員授予您下列 IAM 角色：

執行管理工作，例如管理目錄使用者存取權、儲存空間存取權和目錄的憑證販售模式：
- 專案的 BigLake 管理員 (roles/biglake.admin)
- Cloud Storage bucket 的儲存空間管理員 (roles/storage.admin)
以憑證販售模式讀取資料表資料：專案的 BigLake 檢視者 (roles/biglake.viewer)。如果您使用 Managed Service for Apache Spark、Managed Service for Apache Spark 或 Dataflow 等查詢引擎讀取資料表資料，請將這個角色授予您在該引擎中執行工作的服務帳戶。
以憑證販售模式寫入資料表資料：專案中的 BigLake 編輯者 (roles/biglake.editor)。如果您使用 Managed Service for Apache Spark、Managed Service for Apache Spark 或 Dataflow 等查詢引擎寫入資料表資料，請將這個角色授予您在該引擎中執行工作的服務帳戶。
在憑證販售模式中，使用自動佈建的 Lakehouse 執行階段目錄服務帳戶：目標 Cloud Storage bucket 的「Storage 物件使用者」 (roles/storage.objectUser)。建立目錄後，請明確將儲存空間 bucket 的 Storage 物件使用者角色 (roles/storage.objectUser)，授予目錄自動佈建的 Lakehouse 執行階段目錄服務帳戶。
在非憑證臨時配發模式下讀取目錄資源和資料表資料：
- 專案的「BigLake Viewer」(BigLake 檢視者) (roles/biglake.viewer)
- Cloud Storage 值區的「Storage 物件檢視者」 (roles/storage.objectViewer)
在非憑證臨時配發模式下管理目錄資源及寫入資料表資料：
- 專案的 BigLake 編輯者 (roles/biglake.editor)
- Storage 物件使用者 (roles/storage.objectUser) Cloud Storage 值區
透過 BigQuery 目錄聯盟執行資料操縱語言 (DML) 作業：
- 專案的「BigQuery 資料編輯者」 (roles/bigquery.dataEditor)
- Cloud Storage 值區的Storage 管理員 (roles/storage.admin)。如果您使用 Managed Service for Apache Spark 等查詢引擎執行 DML 作業，請將這些角色授予您在該引擎中執行工作時使用的服務帳戶。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

限制

Apache Iceberg REST 目錄端點受以下限制：

一般限制

使用 Compute Engine 2.3 映像檔版本 2.3.16 以上的 Managed Service for Apache Spark 時，只有 BigQuery 目錄同盟支援 Trino。
使用憑證臨時配發模式時，您必須將 io-impl 屬性設為 org.apache.iceberg.gcp.gcs.GCSFileIO。系統不支援預設值 org.apache.iceberg.hadoop.HadoopFileIO。

資料表限制

透過 Apache Iceberg REST 目錄端點管理的資料表不支援精細存取控管 (FGAC)，例如資料列層級和資料欄層級安全防護機制。

資料限制

系統僅支援 Parquet 檔案。如要進一步瞭解 BigQuery 如何處理 Parquet 檔案，請參閱從 Cloud Storage 載入 Parquet 資料。
Iceberg metadata.json 檔案大小上限為 1 MB。如要提高這項上限，請與 Google 帳戶團隊聯絡。

查詢限制

您無法在 BigQuery 中，建立由 Apache Iceberg REST 目錄端點管理的 Apache Iceberg 資料表檢視區塊。
您無法使用五部分名稱 ID 在 BigQuery 中查詢 Apache Iceberg 中繼資料表 (例如 .snapshots 或 .files)，但可以使用 Spark 查詢這些資料表。

設定 Iceberg REST 目錄端點

設定目錄之前，建議先閱讀 Apache Iceberg REST 目錄端點總覽，瞭解資源階層、目錄類型和命名結構。

在 Lakehouse 執行階段目錄中使用 Apache Iceberg REST 目錄端點時，請按照下列一般步驟操作：

根據 Iceberg REST 目錄端點總覽，選擇目錄資料倉儲位置 (Cloud Storage 或 BigQuery)。
如果您使用 Cloud Storage gs:// 倉庫，請建立指向倉庫位置的目錄。
設定用戶端應用程式，以使用 Apache Iceberg REST 目錄端點。
建立命名空間或結構定義，整理資料表。
使用已設定的用戶端建立及查詢資料表。

建立目錄

您可以建立使用使用者憑證或憑證販售模式的目錄。

有了使用者憑證，目錄就能將存取目錄的使用者身分傳遞至 Cloud Storage，以進行授權檢查。
憑證販售是一種儲存空間存取委派機制，可讓 Lakehouse 執行階段目錄管理員直接控管 Lakehouse 執行階段目錄資源的權限，因此目錄使用者不必直接存取 Cloud Storage 值區。Google Cloud 的 Lakehouse 管理員可藉此授予使用者特定資料檔案的權限。

注意事項

建立目錄前，請先熟悉地點規定。

建立命名空間時，系統會自動使用與目錄相同的區域。
如果目錄使用多區域值區，且您想搭配 BigQuery 多區域 (US 或 EU) 使用，就必須刪除並重新建立目錄，才能指定主要位置。

使用者憑證

控制台

在 Google Cloud 控制台中開啟「Lakehouse」Lakehouse頁面。

前往 Lakehouse
按一下「建立目錄」。
在「選取 Cloud Storage bucket」欄位中，輸入要與目錄搭配使用的 Cloud Storage bucket 名稱。或者，按一下「瀏覽」選擇現有值區，或建立新值區。每個 Cloud Storage bucket 只能有一個目錄。
在「Authentication method」部分，選取「End-user credentials」。
點選「建立」。

gcloud

使用 gcloud biglake iceberg catalogs create 指令。

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user \
    [--primary-location LOCATION]

更改下列內容：

CATALOG_NAME：目錄名稱。如果是Apache Iceberg 的受管理 Lakehouse REST 目錄資料表，這個名稱通常會與 REST 目錄使用的 Cloud Storage bucket ID 相符。舉例來說，如果 bucket 是 gs://bucket-id，目錄名稱可能是 bucket-id。從 BigQuery 查詢這些資料表時，這個名稱也會做為目錄 ID。
PROJECT_ID：您的 Google Cloud 專案 ID。
LOCATION：(選用) 目錄的主要區域，確保與 BigQuery 互通。如果是美國地區 (例如 US 或 us-central1) 或歐盟地區 (例如 EU 或 europe-west4) 的 Cloud Storage 值區，請分別指定 US 或 EU，確保目錄可供存取，並可從對應的 BigQuery 多區域查詢。詳情請參閱「值區和目錄區域」。

憑證臨時配發模式

目錄管理員在建立或更新目錄時，會啟用憑證販售功能。目錄使用者接著可以指示 Apache Iceberg REST 目錄端點傳回範圍縮減的儲存空間憑證，方法是在設定 Apache Iceberg REST 目錄端點時指定存取權委派。

自動佈建的 Lakehouse 執行階段目錄服務帳戶，必須在目標 Cloud Storage bucket 上具備明確的 Storage 物件使用者角色 (roles/storage.objectUser)。根據預設，建立的連結只有檢視權限。如果沒有這個角色，供應的憑證就沒有足夠的範圍來執行儲存空間寫入作業。如果您使用 gcloud 或 Terraform 等工具，則必須手動授予這個角色。

控制台

在 Google Cloud 控制台中開啟「Lakehouse」Lakehouse頁面。

前往 Lakehouse
按一下「建立目錄」。「建立目錄」頁面隨即開啟。
在「選取 Cloud Storage bucket」，輸入要與目錄搭配使用的 Cloud Storage bucket 名稱。或者，按一下「瀏覽」，從現有值區清單中選擇，或建立新值區。每個 Cloud Storage bucket 只能有一個目錄。
在「Authentication method」部分，選取「Credential vending mode」。
點選「建立」。

系統會建立目錄，並開啟「目錄詳細資料」頁面。
在「驗證方法」下方，按一下「設定 bucket 權限」。
在對話方塊中，按一下「確認」。

這會驗證目錄的服務帳戶是否具備儲存空間 bucket 的「Storage 物件管理員」角色。

gcloud

使用 gcloud biglake iceberg catalogs create 指令。

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

更改下列內容：

CATALOG_NAME：目錄名稱。這個名稱通常與 Lakehouse Iceberg REST 目錄使用的 Cloud Storage bucket ID 相符。舉例來說，如果 bucket 是 gs://bucket-id，目錄名稱可能是 bucket-id。從 BigQuery 查詢這些資料表時，這個名稱也會做為目錄 ID。
PROJECT_ID：您的 Google Cloud 專案 ID。
LOCATION：(選用) 目錄的主要區域，確保與 BigQuery 互通。如果是位於美國區域 (例如 US 或 us-central1) 或歐盟區域 (例如 EU 或 europe-west4) 的 Cloud Storage bucket，請分別指定 US 或 EU，確保目錄可供查詢，且可從對應的 BigQuery 多區域存取。詳情請參閱「值區和目錄區域」。

建立目錄後，請將儲存空間 bucket 的「Storage 物件使用者」角色 (roles/storage.objectUser)，明確授予目錄自動佈建的 Lakehouse 執行階段目錄服務帳戶。

設定用戶端應用程式

建立目錄後，請設定用戶端應用程式以使用該目錄。這些範例說明如何設定憑證販售功能，以及如何設定不含憑證販售功能。

叢集

如要在 Managed Service for Apache Spark 上使用 Spark 和 Apache Iceberg REST 目錄端點，請先建立包含 Apache Iceberg 元件的叢集：

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION

更改下列內容：

CLUSTER_NAME：叢集名稱。
PROJECT_ID：您的 Google Cloud 專案 ID。
REGION：Managed Service for Apache Spark 叢集的區域。
DATAPROC_VERSION：Managed Service for Apache Spark 映像檔版本，例如 2.2。

建立叢集後，請設定 Spark 工作階段，以使用 Apache Iceberg REST 目錄端點：

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

更改下列內容：

CATALOG_NAME：Apache Iceberg REST 目錄端點的名稱。
APP_NAME：Spark 會話名稱。
REST_API_VERSION：設為 v1，使用 API 的穩定版本。如需解決資料沿襲產生作業的已知問題，請設為 v1beta。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。
PROJECT_ID：使用 Apache Iceberg REST 目錄端點時，系統會向這個專案收取費用，這可能與擁有 Cloud Storage 值區的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。

使用憑證臨時配發功能設定

如要使用憑證販售功能，您必須使用憑證販售模式的目錄，並將 X-Iceberg-Access-Delegation 標頭新增至 Iceberg REST 目錄要求，值為 vended-credentials，方法是在 SparkSession 建構工具中新增下列程式碼：

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

憑證臨時配發範例

以下範例會使用憑證販售功能設定查詢引擎：

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

詳情請參閱 Apache Iceberg 說明文件的「RESTCatalog 中的標頭」一節。

在下列版本中，Managed Service for Apache Spark 叢集支援 Apache Iceberg 的 Google 授權流程：

Compute Engine 2.2 映像檔版本上的 Managed Service for Apache Spark 2.2.65 以上版本。
Compute Engine 2.3 映像檔版本上的 Managed Service for Apache Spark 2.3.11 以上版本。

無伺服器

將 PySpark 批次工作負載提交至 Managed Service for Apache Spark，並採用下列設定：

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

更改下列內容：

PYSPARK_FILE：PySpark 應用程式檔案的 gs:// Cloud Storage 路徑。
PROJECT_ID：您的 Google Cloud 專案 ID。
REGION：Managed Service for Apache Spark 批次工作負載的區域。
RUNTIME_VERSION：Managed Service for Apache Spark 執行階段版本，例如 2.2。
CATALOG_NAME：Apache Iceberg REST 目錄端點的名稱。
REST_API_VERSION：設為 v1，使用 API 的穩定版本。如需解決資料沿襲產生作業的已知問題，請設為 v1beta。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。

使用憑證臨時配發功能設定

如要使用憑證販售功能，您必須使用憑證販售模式的目錄，並將 X-Iceberg-Access-Delegation 標頭新增至 Apache Iceberg REST 目錄端點要求，值為 vended-credentials，方法是在 Managed Service for Apache Spark 設定中新增下列程式碼行：

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

憑證臨時配發範例

以下範例會使用憑證販售功能設定查詢引擎：

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=gs://CLOUD_STORAGE_BUCKET_NAME,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

詳情請參閱 Apache Iceberg 說明文件的「RESTCatalog 中的標頭」一節。

Managed Service for Apache Spark 在下列執行階段版本中，支援 Apache Iceberg 的 Google 授權流程：

Managed Service for Apache Spark 2.2 執行階段 2.2.60 以上版本
Managed Service for Apache Spark 2.3 執行階段 2.3.10 以上版本

Trino

如要搭配 Apache Iceberg REST 目錄端點使用 Trino，請建立含有 Trino 元件的 Managed Service for Apache Spark 叢集，並使用 gcloud dataproc clusters create --properties 旗標設定目錄屬性。以下範例會建立名為 CATALOG_NAME 的 Trino 目錄：

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

更改下列內容：

CLUSTER_NAME：叢集名稱。
REGION：Managed Service for Apache Spark 叢集區域。
DATAPROC_VERSION：Managed Service for Apache Spark 映像檔版本，例如 2.2。
NETWORK_ID：叢集網路 ID。詳情請參閱「Managed Service for Apache Spark 叢集網路設定」。
CATALOG_NAME：使用 Apache Iceberg REST 目錄端點的 Trino 目錄名稱。
REST_API_VERSION：設為 v1，使用 API 的穩定版本。如需解決資料沿襲產生作業的已知問題，請設為 v1beta。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。
PROJECT_ID：用於 Lakehouse 執行階段目錄的 Google Cloud 專案 ID。

建立叢集後，請連線至主要 VM 執行個體，並使用 Trino CLI：

trino --catalog=CATALOG_NAME

在下列版本中，Managed Service for Apache Spark Trino 支援 Apache Iceberg 的 Google 授權流程：

Compute Engine 2.2 執行階段版本上的 Managed Service for Apache Spark 2.2.65 以上版本
Compute Engine 上的 Managed Service for Apache Spark 2.3 執行階段版本 2.3.11 以上版本
不支援 Compute Engine 3.0 上的 Managed Service for Apache Spark。

使用憑證臨時配發功能設定

Managed Service for Apache Spark Trino 不支援憑證販售。

Apache Iceberg 1.10 以上版本

開放原始碼 Apache Iceberg 1.10 以上版本已內建支援 GoogleAuthManager 中的 Google 授權流程。以下範例說明如何設定 Spark，以使用 Lakehouse 執行階段目錄和 Apache Iceberg REST 目錄端點。

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

更改下列內容：

CATALOG_NAME：Apache Iceberg REST 目錄端點的名稱。
APP_NAME：Spark 會話名稱。
REST_API_VERSION：設為 v1，使用 API 的穩定版本。如需解決資料沿襲產生作業的已知問題，請設為 v1beta。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。
PROJECT_ID：使用 Apache Iceberg REST 目錄端點時，系統會向這個專案收取費用，這可能與擁有 Cloud Storage 值區的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。

使用憑證臨時配發功能設定

上述範例未使用憑證臨時配發。如要使用憑證販售功能，您必須以憑證販售模式使用目錄，並將 X-Iceberg-Access-Delegation 標頭新增至 Apache Iceberg REST 目錄端點要求，值為 vended-credentials，方法是在 SparkSession 建構工具中新增下列程式碼行：

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

憑證臨時配發範例

以下範例會使用憑證販售功能設定查詢引擎：

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

詳情請參閱 Apache Iceberg 說明文件的「RESTCatalog 中的標頭」一節。

先前的 Apache Iceberg 版本

如果是 1.10 之前的 Apache Iceberg 開放原始碼版本，您可以透過設定具有下列項目的工作階段，設定標準 OAuth 驗證：

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

更改下列內容：

CATALOG_NAME：Apache Iceberg REST 目錄端點的名稱。
APP_NAME：Spark 會話名稱。
REST_API_VERSION：設為 v1，使用 API 的穩定版本。如需解決資料沿襲產生作業的已知問題，請設為 v1beta。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。
PROJECT_ID：使用 Apache Iceberg REST 目錄端點時，系統會向這個專案收取費用，這可能與擁有 Cloud Storage 值區的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。
TOKEN：您的驗證權杖，效期為一小時，例如使用 gcloud auth application-default print-access-token 產生的權杖。

使用憑證臨時配發功能設定

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

憑證臨時配發範例

以下範例會使用憑證販售功能設定查詢引擎：

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

詳情請參閱 Apache Iceberg 說明文件的「RESTCatalog 中的標頭」一節。

建立命名空間或結構定義

設定用戶端後，請建立命名空間或結構定義，整理資料表。建立命名空間或結構定義的語法會因查詢引擎而異。下列範例說明如何使用 Spark 和 Trino 建立這些項目。

Spark

Cloud Storage 倉儲

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")

將 NAMESPACE_NAME 替換為命名空間的名稱。

Trino

Cloud Storage 倉儲

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

更改下列內容：

CATALOG_NAME：使用 Apache Iceberg REST 目錄端點的 Trino 目錄名稱。
SCHEMA_NAME：結構定義名稱。

在 BigQuery 中查詢資料表

在 BigQuery 中，透過 Apache Iceberg REST 目錄端點建立資料表後，查詢方式取決於您使用的是 Cloud Storage bucket 倉庫或 BigQuery 聯合查詢。

Cloud Storage bucket 倉庫：如果您使用 gs:// 倉庫路徑設定用戶端，請使用四部分名稱 (P.C.N.T) project.catalog.namespace.table 從 BigQuery 查詢資料表。如要進一步瞭解 P.C.N.T 結構，請參閱「Iceberg REST 目錄概念」。catalog 元件是 Lakehouse 執行階段目錄目錄資源的名稱。如要進一步瞭解如何查詢資料表，請參閱查詢資料表。
BigQuery 聯邦：如果您使用 bq:// 倉庫路徑設定用戶端，您建立的資料表會顯示在 BigQuery 中，且可使用標準 BigQuery SQL 直接查詢：
```
SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;
```
更改下列內容：
- NAMESPACE_NAME：命名空間名稱。
- TABLE_NAME：資料表名稱。

搭配使用目錄同盟與 BigQuery

如要瞭解目錄同盟，請參閱 Iceberg REST 目錄概念。如要啟用聯盟，請在「設定用戶端應用程式」中，使用用戶端設定範例的 WAREHOUSE_PATH 欄位，以 bq://projects/PROJECT_ID 倉庫格式設定用戶端。您也可以選擇加入 BigQuery 位置，使用 bq://projects/PROJECT_ID/locations/LOCATION 格式將日後的請求限制在單一位置。

由於這些資源是由 BigQuery 管理，您必須具備適用的必要權限。

為聯盟設定用戶端後，即可為聯盟資料表建立命名空間。

Spark

如要使用 BigQuery 目錄同盟，請加入 LOCATION 和 DBPROPERTIES 子句：

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

更改下列內容：

NAMESPACE_NAME：命名空間名稱。
BUCKET_NAME：您用於目錄的 Cloud Storage bucket。
LOCATION：BigQuery 位置。預設值為 US 多區域位置。

Trino

如要使用 BigQuery 目錄聯盟，請加入 LOCATION 和 gcp-region 屬性：

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

更改下列內容：

CATALOG_NAME：使用 Apache Iceberg REST 目錄端點的 Trino 目錄名稱。
SCHEMA_NAME：結構定義名稱。
BUCKET_NAME：您用於目錄的 Cloud Storage bucket。
LOCATION：BigQuery 位置。預設值為 US 多區域位置。

後續步驟

瞭解如何查詢資料表，以及如何透過 BigQuery 使用目錄聯盟。
瞭解如何在 Google Cloud 控制台中管理目錄。
瞭解 Apache Iceberg 專用 Lakehouse REST 目錄資料表。

設定 Lakehouse Iceberg REST 目錄 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

限制

設定 Iceberg REST 目錄端點

建立目錄

使用者憑證

控制台

gcloud

憑證臨時配發模式

控制台

gcloud

設定用戶端應用程式

叢集

使用憑證臨時配發功能設定

憑證臨時配發範例

無伺服器

使用憑證臨時配發功能設定

憑證臨時配發範例

Trino

使用憑證臨時配發功能設定

Apache Iceberg 1.10 以上版本

使用憑證臨時配發功能設定

憑證臨時配發範例

先前的 Apache Iceberg 版本

使用憑證臨時配發功能設定

憑證臨時配發範例

建立命名空間或結構定義

Spark

Cloud Storage 倉儲

Trino

Cloud Storage 倉儲

在 BigQuery 中查詢資料表

搭配使用目錄同盟與 BigQuery

Spark

Trino

後續步驟

設定 Lakehouse Iceberg REST 目錄