自 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 Iceberg REST Catalog API 為基礎的全代管標準化介面。

這個端點是單一事實來源，可讓查詢引擎順暢互通。讓 Apache Spark 等引擎探索、讀取及管理 Google Cloud Lakehouse 資料表。

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

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

事前準備

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

如果您有現有的第 1 版 (V1) Apache Iceberg 資料表，必須先升級，才能搭配 Apache Iceberg REST 目錄端點使用。詳情請參閱「將 Iceberg V1 資料表升級至 V2」。

確認專案已啟用計費功能 Google Cloud 。
啟用 BigLake API。
啟用 API 時所需的角色
您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API

必要的角色

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

執行管理工作，例如管理目錄使用者存取權、儲存空間存取權和目錄的憑證販售模式：
- BigLake 管理員 (roles/biglake.admin) 專案
- 所有相關聯 Cloud Storage 值區的Storage 管理員 (roles/storage.admin)。
在 Lakehouse 目錄中註冊資料表：專案的 BigLake 管理員 (roles/biglake.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 檢視者」 (roles/biglake.viewer)
- 所有相關聯的 Cloud Storage 值區。Storage 物件檢視者 (roles/storage.objectViewer)
在非憑證臨時配發模式下管理目錄資源及寫入資料表資料：
- 專案的 BigLake 編輯者 (roles/biglake.editor)
- 所有相關聯的 Cloud Storage 值區都具有「Storage 物件使用者」 (roles/storage.objectUser) 權限。

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

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

限制

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

一般限制

支援 Apache Iceberg V2 資料表 (正式發布版) 和 V3 資料表 (預先發布版)。不支援 Iceberg V1 資料表。如要透過 Apache Iceberg REST 目錄端點使用現有的 V1 表格，必須先將這些表格升級至支援的版本。
使用憑證販售模式時，如果查詢引擎允許您為目錄連線設定 io-impl 屬性，則必須將其設為 org.apache.iceberg.gcp.gcs.GCSFileIO。
目前憑證販售模式不支援階層命名空間 bucket。

資料表限制

您無法使用 BigQuery 資料定義語言 (DDL) 或資料操縱語言 (DML) 陳述式，在 Apache Iceberg REST 目錄端點中建立或修改資料表。您可以使用 BigQuery API (透過 bq 指令列工具或用戶端程式庫) 修改這些資料表，但這麼做可能會導致變更與外部引擎不相容。
透過 Apache Iceberg REST 目錄端點管理的資料表不支援精細存取控管 (FGAC)，例如資料列層級和資料欄層級安全防護機制。
禁止將 Iceberg 資料表屬性 write.data.path 或 write.metadata.path 設為預設值以外的值。
資料表路徑必須巢狀內嵌於父項命名空間路徑中 (例如 gs://{namespace_path}/.../{table_name})。為避免發生衝突並提升安全性，系統會自動在產生的位置附加隨機字串後置字串 (例如 gs://{namespace_path}/{table_name}/{random_suffix})。

資料限制

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

查詢限制

您無法使用五部分名稱 ID 在 BigQuery 中查詢 Apache Iceberg 中繼資料表 (例如 .snapshots 或 .files)，但可以使用 Spark 查詢這些資料表。

注意事項

建立目錄時，請考慮下列設定。

bucket 類型

您可以選擇建立單一值區目錄或多個值區目錄。

多 bucket (bl://) 目錄 (建議)：這項設定可讓目錄關聯多個 bucket，並獨立於任何 bucket 名稱命名目錄。
單一 bucket (gs://)：這項設定會將目錄限制為單一 bucket，並將目錄名稱鎖定為 bucket 名稱。不建議用於新專案。

憑證模式 (範圍)

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

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

自動佈建的 Lakehouse 執行階段目錄服務帳戶，需要所有相關聯 Cloud Storage bucket 的明確 Storage 物件使用者角色 (roles/storage.objectUser)。根據預設，該帳戶完全沒有存取權。如果沒有這個角色，供應的憑證就沒有足夠的範圍來執行儲存空間寫入作業。如果您使用 gcloud 或 Terraform 等工具，則必須手動授予這個角色。

自動佈建的目錄服務帳戶建立作業最終會保持一致。也就是說，服務帳戶需要一段時間才能在系統中傳播。如果您在建立服務帳戶後立即嘗試授予角色，要求可能會失敗。如要瞭解存取權變更平均需要多久才能生效，請參閱「存取權變更生效」一文。

位置

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

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

設定 Iceberg REST 目錄端點

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

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

選擇目錄類型：多 bucket (bl://) 目錄 (建議) 或單一 bucket (gs://) 目錄。
建立指向倉庫位置的目錄。
設定用戶端應用程式，以使用 Apache Iceberg REST 目錄端點。
建立命名空間或結構定義，整理資料表。
使用已設定的用戶端建立及查詢資料表。

建立目錄

請按照下列步驟，根據偏好的憑證模式和值區類型建立目錄。

控制台

建立多個 bucket (bl://) 目錄 (建議做法)

這項設定可讓目錄關聯多個 bucket，並獨立於任何 bucket 名稱命名目錄。

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

前往 Lakehouse
按一下「建立目錄」。
在「目錄類型」部分，選取「Iceberg REST 目錄」。
在「Lakehouse catalog bucket options」(Lakehouse 目錄 bucket 選項) 中，選取「Multiple bucket catalog」(多個 bucket 目錄)。
在「Default Catalog Cloud Storage path」(預設目錄 Cloud Storage 路徑) 中，輸入或瀏覽要與目錄搭配使用的 Cloud Storage 路徑。
在「目錄 ID」中，輸入目錄的自訂名稱。
在「主要位置」部分，選取一個位置。位置必須靠近主要 bucket 的區域。
按一下「繼續」。
在「資料路徑」步驟中，視需要新增其他 Cloud Storage 路徑。
按一下「繼續」。
在「Authentication method」(驗證方法) 部分，選取「End-user credentials」(使用者憑證) 或「Credential vending mode」(憑證臨時配發模式)。
點選「建立」。

目錄建立完成後，系統會開啟「目錄詳細資料」頁面。
如果您選取「憑證臨時配發模式」，請執行下列額外步驟：
1. 在「驗證方式」下方，按一下「設定 bucket 權限」。
2. 在對話方塊中，按一下「確認」。

建立單一 bucket (`gs://`) 目錄

在「目錄類型」部分，選取「Iceberg REST 目錄」。
在「Lakehouse 目錄 bucket 選項」部分，選取「單一 bucket 目錄」。
在「Default Catalog Cloud Storage path」(預設目錄 Cloud Storage 路徑) 中，輸入或瀏覽要與目錄搭配使用的 Cloud Storage 路徑。 (如果是單一 bucket (gs://) 目錄，每個 bucket 只能有一個目錄，且目錄名稱與 bucket 名稱相符)。
按一下「繼續」。
在「Authentication method」(驗證方法) 部分，選取「End-user credentials」(使用者憑證) 或「Credential vending mode」(憑證臨時配發模式)。
點選「建立」。
如果您選取「憑證臨時配發模式」，請執行下列額外步驟：
1. 在「驗證方式」下方，按一下「設定 bucket 權限」。
2. 在對話方塊中，按一下「確認」。

gcloud

建立多個 bucket (bl://) 目錄 (建議做法)

這項設定可讓目錄關聯多個 bucket，並獨立於任何 bucket 名稱命名目錄。

如要建立多個 bucket (bl://) 目錄 (建議做法)，請執行 gcloud biglake iceberg catalogs create 指令。

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    --credential-mode CREDENTIAL_MODE \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    [--primary-location LOCATION]

更改下列內容：

CATALOG_NAME：目錄名稱。如果是多 bucket (bl://) 目錄 (建議)，這是您的自訂目錄名稱。如果是單一 bucket (gs://) 目錄，這會與 REST 目錄使用的 Cloud Storage bucket ID 相符。
PROJECT_ID：您的 Google Cloud專案 ID。
DEFAULT_LOCATION：指定目錄的預設儲存位置。您可以指定 bucket (gs://my-bucket) 或子路徑 (gs://my-bucket/path)。目錄中的所有命名空間和資料表都必須位於指定路徑下。舉例來說，如果您指定 gs://my-bucket/path，就無法在 gs://my-bucket/another/path 下方建立命名空間或資料表。
CREDENTIAL_MODE：驗證方式。使用 使用者憑證的 end-user，或憑證臨時配發模式的 vended-credentials。

注意：如果您使用憑證販售模式，則必須在所有相關聯的儲存空間 bucket 上，明確授予目錄的自動佈建 Lakehouse 執行階段目錄服務帳戶「Storage 物件使用者」角色 (roles/storage.objectUser)。
RESTRICTED_LOCATIONS：(選用) 以半形逗號分隔的額外允許儲存位置清單，格式為 gs://my-bucket-1/...,gs://my-bucket-2/...。如果您指定路徑 (例如 gs://my-bucket/path)，該值區中的任何命名空間或資料表都必須位於該路徑下。預設位置和受限位置的所有已設定 Cloud Storage 位置，都必須位於相同的地理區域群組或管轄區 (例如美國、歐洲、加拿大或亞洲)。舉例來說，您無法混合使用美國和歐洲的值區。如需支援的位置清單，請參閱「Lakehouse 位置」。

警告：請避免設定與其他目錄重疊的路徑，以免未經授權的憑證曝光。詳情請參閱「跨多個 bucket 的儲存空間」。
LOCATION：(選用) 目錄的主要區域，確保與 BigQuery 互通。如果是美國區域 (例如 US 或 us-central1) 或歐盟區域 (例如 EU 或 europe-west4) 的 Cloud Storage bucket，請分別指定 US 或 EU，確保目錄可供存取，並可從對應的 BigQuery 多區域查詢。詳情請參閱「值區和目錄區域」。

建立單一 bucket (`gs://`) 目錄

如要建立單一 bucket (gs://) 目錄，請執行下列指令：

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode CREDENTIAL_MODE

更改下列內容：

CATALOG_NAME：目錄名稱。如果是多 bucket (bl://) 目錄 (建議)，這是您的自訂目錄名稱。如果是單一 bucket (gs://) 目錄，這會與 REST 目錄使用的 Cloud Storage bucket ID 相符。
PROJECT_ID：您的 Google Cloud專案 ID。
CREDENTIAL_MODE：驗證方式。使用 end-user 適用於使用者憑證，或使用 vended-credentials 適用於憑證臨時配發模式。

設定用戶端應用程式

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

叢集

使用簡化的設定屬性 (建議)，或手動指定屬性，在 Compute Engine 叢集上建立 Managed Service for Apache Spark。

使用屬性簡化設定 (建議)

使用目錄資源建立叢集：

gcloud dataproc clusters create CLUSTER_NAME \
  --enable-component-gateway \
  --project=PROJECT_ID \
  --region=REGION \
  --optional-components=ICEBERG \
  --image-version=DATAPROC_VERSION \
  --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

更改下列內容：

CLUSTER_NAME：叢集名稱。
PROJECT_ID：您的 Google Cloud 專案 ID。
REGION：Managed Service for Apache Spark 叢集區域。
DATAPROC_VERSION：Managed Service for Apache Spark 映像檔版本，例如 2.3。
CATALOG_NAME：本機 Spark 目錄的名稱 (例如 my_catalog)。這可以與 CATALOG_ID 相同。
CATALOG_ID：您建立的目錄 ID。

在 PySpark 應用程式檔案中，建立 SparkSession，但不指定目錄設定：

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

手動設定

如果您不使用簡化設定屬性，請按照上述步驟建立叢集，但不要使用 --properties 標記。然後手動設定 SparkSession：

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_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') \
  .getOrCreate()

更改下列內容：

CATALOG_NAME：本機 Spark 目錄的名稱 (例如 my_catalog)。
APP_NAME：Spark 會話名稱。
REST_API_VERSION：設為 v1，使用穩定版 API。
WAREHOUSE_PATH：倉庫的路徑。如果是 BigLake 目錄，請使用 bl://projects/PROJECT_ID/catalogs/CATALOG_ID。如果是 Cloud Storage bucket 目錄，請使用 gs://CLOUD_STORAGE_BUCKET_NAME。
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('spark.sql.defaultCatalog', 'CATALOG_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(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .getOrCreate()

詳情請參閱 Apache Iceberg 說明文件的「Headers in the 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="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

更改下列內容：

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.3。
CATALOG_NAME：本機 Spark 目錄的名稱 (例如 my_catalog)。這可以與 CATALOG_ID 相同。
CATALOG_ID：您建立的目錄 ID。

在 PySpark 應用程式檔案中，建立 SparkSession，但不指定目錄設定：

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

手動設定

如果您未使用簡化設定屬性，則必須手動指定目錄設定：

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.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

更改下列內容：

PYSPARK_FILE：PySpark 應用程式檔案的 gs:// Cloud Storage 路徑。
REGION：Managed Service for Apache Spark 批次工作負載的區域。
RUNTIME_VERSION：Managed Service for Apache Spark 執行階段版本，例如 2.3。
CATALOG_NAME：本機 Spark 目錄的名稱 (例如 my_catalog)。
REST_API_VERSION：設為 v1，使用穩定版 API。
WAREHOUSE_PATH：倉庫的路徑。如果是 BigLake 目錄，請使用 bl://projects/PROJECT_ID/catalogs/CATALOG_ID。如果是 Cloud Storage bucket 目錄，請使用 gs://CLOUD_STORAGE_BUCKET_NAME。
PROJECT_ID：使用 Apache Iceberg REST 目錄端點時，系統會向這個專案收取費用，這可能與擁有 Cloud Storage 值區的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。

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

如要使用憑證販售功能，您必須以憑證販售模式使用目錄，並將 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=WAREHOUSE_PATH,\
    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.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\"
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions

詳情請參閱 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。
WAREHOUSE_PATH：倉庫的路徑。如果是 BigLake 目錄，請使用 bl://projects/PROJECT_ID/catalogs/CATALOG_ID。如果是 Cloud Storage bucket 目錄，請使用 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 2.3 執行階段版本上的 Managed Service for Apache Spark 2.3.11 以上版本
不支援 Compute Engine 3.0 上的 Managed Service for Apache Spark。

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

憑證販售僅適用於 Trino 481 以上版本。

Apache Iceberg 1.10 以上版本

開放原始碼 Apache Iceberg 1.10 以上版本已內建 GoogleAuthManager 的 Google 授權流程支援。以下範例說明如何設定 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：本機 Spark 目錄的名稱 (例如 my_catalog)。
APP_NAME：Spark 會話名稱。
REST_API_VERSION：設為 v1，使用穩定版 API。
WAREHOUSE_PATH：倉庫的路徑。如果是 BigLake 目錄，請使用 bl://projects/PROJECT_ID/catalogs/CATALOG_ID。如果是 Cloud Storage bucket 目錄，請使用 gs://CLOUD_STORAGE_BUCKET_NAME。
PROJECT_ID：使用 Apache Iceberg REST 目錄端點時，系統會向這個專案收取費用，這可能與擁有 Cloud Storage 值區的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。

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

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

.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', '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(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：本機 Spark 目錄的名稱 (例如 my_catalog)。
APP_NAME：Spark 會話名稱。
REST_API_VERSION：設為 v1，使用穩定版 API。
WAREHOUSE_PATH：倉庫的路徑。如果是 BigLake 目錄，請使用 bl://projects/PROJECT_ID/catalogs/CATALOG_ID。如果是 Cloud Storage bucket 目錄，請使用 gs://CLOUD_STORAGE_BUCKET_NAME。
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', '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(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 建立這些項目。

控制台

前往 Google Cloud 控制台的「Lakehouse」Lakehouse。

前往 Lakehouse
選取現有目錄，或建立新目錄 (如果沒有)。
在選單列中，按一下「+ 建立命名空間」。
在「命名空間名稱」欄位中，輸入命名空間的專屬名稱。
在「Location」(位置) 部分，指定要與命名空間建立關聯的路徑：
- 多個值區 (bl://) (建議)：只要自訂位置位於目錄允許的位置 (default_location 或 restricted_locations)，即可設定任何自訂位置。如未指定位置，系統會在目錄的預設位置 (例如 gs://{path-to-default-location}/{namespace_name}) 下建立命名空間。
- 單一 bucket (gs://)：系統會自動從目錄的單一 bucket 繼承命名空間位置。
點選「建立」。

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：結構定義名稱。

升級目錄

如果您有現有的單一 bucket (gs://) 目錄，可以將其升級為多個 bucket (bl://) 目錄類型 (建議)。升級後，您就能關聯多個 bucket，並設定受限位置，同時保留原始目錄名稱。

後續步驟

瞭解如何在 Google Cloud 控制台中管理目錄。
瞭解 Apache Iceberg 專用 Lakehouse REST 目錄資料表。

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

事前準備

必要的角色

限制

注意事項

bucket 類型

憑證模式 (範圍)

位置

設定 Iceberg REST 目錄端點

建立目錄

控制台

建立單一 bucket (gs://) 目錄

gcloud

建立單一 bucket (gs://) 目錄

設定用戶端應用程式

叢集

使用屬性簡化設定 (建議)

手動設定

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

憑證臨時配發範例

無伺服器

使用屬性簡化設定 (建議)

手動設定

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

憑證臨時配發範例

Trino

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

Apache Iceberg 1.10 以上版本

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

憑證臨時配發範例

先前的 Apache Iceberg 版本

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

憑證臨時配發範例

建立命名空間或結構定義

控制台

Spark

Cloud Storage 倉儲

Trino

Cloud Storage 倉儲

升級目錄

後續步驟

設定 Lakehouse Iceberg REST 目錄端點

建立單一 bucket (`gs://`) 目錄

建立單一 bucket (`gs://`) 目錄