使用 BigLake metastore Iceberg REST 目錄

建議您使用 BigLake metastore 中的 Apache Iceberg REST 目錄，進行新的工作流程。為所有 Iceberg 資料提供單一可靠資料來源，在查詢引擎之間建立互通性。查詢引擎 (例如 Apache Spark) 可透過這個目錄，以一致的方式探索 Iceberg 資料表、從中讀取中繼資料，以及管理這些資料表。

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

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

事前準備

繼續操作前，請先熟悉 BigLake metastore。

Verify that billing is enabled for your Google Cloud project.
Enable the BigLake API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API

必要的角色

如要取得在 BigLake metastore 中使用 Iceberg REST 目錄所需的權限，請要求管理員授予下列 IAM 角色：

執行管理工作，例如管理目錄使用者存取權、儲存空間存取權和目錄的憑證販售模式：
- BigLake 管理員 (roles/biglake.admin) 專案
- Cloud Storage 值區的儲存空間管理員 (roles/storage.admin)
以憑證販售模式讀取資料表資料：專案的 BigLake 檢視者 (roles/biglake.viewer)
以憑證販售模式寫入資料表資料：專案的 BigLake 編輯者 (roles/biglake.editor)
在非憑證臨時配發模式下讀取目錄資源和表格資料：
- 專案的「BigLake Viewer」(BigLake 檢視者) (roles/biglake.viewer)
- Storage 物件檢視者 (roles/storage.objectViewer) 在 Cloud Storage 值區上
在非憑證臨時配發模式下管理目錄資源及寫入資料表資料：
- 專案的 BigLake 編輯者 (roles/biglake.editor)
- Storage 物件使用者 (roles/storage.objectUser) Cloud Storage 值區

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

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

限制

Iceberg REST 目錄有下列限制：

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

目錄資源

BigLake metastore 中的 Apache Iceberg REST 目錄會使用資源階層來整理資料。

Apache Iceberg REST 目錄資源

下表概略說明 BigLake metastore 中 Apache Iceberg REST 目錄使用的資源。

資源	說明
目錄	目錄是頂層容器，可讓您將命名空間和資料表劃分成不同目錄，整理成邏輯群組。
命名空間	用於整理目錄中資料表的邏輯分組，功能類似於資料庫、結構定義或目錄。
資料表	資料表包含可查詢的資料列和資料欄定義。

支援的目錄

設定用戶端時，請指定倉庫位置。這項選擇會決定目錄的運作方式，以及如何與其他 Google Cloud服務整合。

目錄類型	說明
Cloud Storage 值區	目錄中的所有資料都儲存在單一 Cloud Storage bucket 中；如要跨多個 bucket 共用資料，則必須使用多個目錄。
BigQuery 聯合	您可以使用 Iceberg REST 目錄，管理及查詢 BigQuery 可見的資料表。詳情請參閱「搭配使用目錄同盟和 BigQuery」。

目錄倉儲詳細資料

建議

Cloud Storage 值區資料倉儲 (gs://)：這是標準做法，目錄會直接管理您指定的 Cloud Storage 值區中的 Iceberg 中繼資料和資料檔案。這個選項可讓您直接控管資料版面配置，並支援憑證販售，以進行精細的存取權控管。您可藉此建立及管理 Apache Iceberg 專用 BigLake 資料表。

重要事項： 如果目錄使用 Cloud Storage bucket 做為倉庫，目錄名稱也會是目錄資源的 ID。

舉例來說，如果您建立 bucket 來儲存目錄，並將其命名為 iceberg-bucket，則目錄名稱和 bucket 名稱都是 iceberg-bucket。稍後在 BigQuery 中查詢目錄時，會使用 P.C.N.T 語法。例如 my-project.biglake-catalog-id.quickstart_namespace.quickstart_table。

舊版

BigQuery 聯合 (bq://)：這個方法可讓您使用 Iceberg REST 目錄管理及查詢 BigQuery 可見的資料表，不必建立目錄資源。詳情請參閱「搭配使用目錄同盟和 BigQuery」。

P.C.N.T 命名結構

從 BigQuery 查詢 BigLake Metastore 資料表時，您會使用四部分命名結構，通常稱為 P.C.N.T：

Project：擁有目錄的 Google Cloud 專案 ID。
Catalog：BigLake Metastore 目錄的名稱。
命名空間：Iceberg 命名空間 (相當於 BigQuery 資料集)。
Table：資料表名稱。

例如 my-project.biglake-catalog-id.my-namespace.my-table。

設定 Iceberg REST 目錄

在 BigLake Metastore 中使用 Apache Iceberg REST 目錄時，請按照下列一般步驟操作：

瞭解並選擇目錄倉庫位置，可以是 Cloud Storage 或 BigQuery。
如果您使用 Cloud Storage gs:// 倉庫，請建立指向倉庫位置的目錄。
設定用戶端應用程式，以使用 Iceberg REST 目錄。
建立命名空間或結構定義，整理資料表。
使用已設定的用戶端建立及查詢資料表。

建立目錄

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

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

使用者憑證

控制台

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

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

gcloud

使用 gcloud beta biglake iceberg catalogs create 指令。

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

更改下列內容：

CATALOG_NAME：目錄名稱。如果是Apache Iceberg 的受管理 BigLake 資料表，這個名稱通常會與 REST 目錄使用的 Cloud Storage 值區 ID 相符。舉例來說，如果值區是 gs://bucket-id，目錄名稱可能是 bucket-id。從 BigQuery 查詢這些資料表時，這個名稱也會做為目錄 ID。
PROJECT_ID：您的 Google Cloud 專案 ID。

憑證臨時配發模式

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

控制台

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

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

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

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

設定用戶端應用程式

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

叢集

如要在 Dataproc 上使用 Spark 和 Iceberg REST 目錄，請先建立包含 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：Dataproc 叢集的區域。
DATAPROC_VERSION：Dataproc 映像檔版本，例如 2.2。

建立叢集後，請設定 Spark 工作階段，以使用 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

更改下列內容：

CATALOG_NAME：Iceberg REST 目錄的名稱。
APP_NAME：Spark 會話名稱。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。
PROJECT_ID：使用 Iceberg REST 目錄時，系統會向這個專案收取費用，這可能與擁有 Cloud Storage 值區的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。

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

如要使用憑證販售功能，您必須使用憑證販售模式的目錄，並將 X-Iceberg-Access-Delegation 標頭新增至 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

Dataproc 叢集在下列版本中支援 Iceberg 的 Google 授權流程：

Dataproc on Compute Engine 2.2 映像檔版本 2.2.65 以上。
Dataproc on Compute Engine 2.3 映像檔版本 2.3.11 以上。

無伺服器

將 PySpark 批次工作負載提交至 Google Cloud Serverless 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/v1/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,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false"

更改下列內容：

PYSPARK_FILE：PySpark 應用程式檔案的 gs:// Cloud Storage 路徑。
PROJECT_ID：您的 Google Cloud 專案 ID。
REGION：Dataproc 批次工作負載的區域。
RUNTIME_VERSION：Serverless for Apache Spark 執行階段版本，例如 2.2。
CATALOG_NAME：Iceberg REST 目錄的名稱。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。

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

如要使用憑證販售功能，您必須以憑證販售模式使用目錄，並將 X-Iceberg-Access-Delegation 標頭新增至 Iceberg REST 目錄要求，值為 vended-credentials，方法是在 Serverless 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/v1/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.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

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

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

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

Trino

如要搭配 Iceberg REST 目錄使用 Trino，請建立含有 Trino 元件的 Dataproc 叢集，並使用 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/v1/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：Dataproc 叢集區域。

DATAPROC_VERSION：Dataproc 映像檔版本，例如 2.2。

NETWORK_ID：叢集網路 ID。詳情請參閱「Dataproc 叢集網路設定」。
CATALOG_NAME：使用 Iceberg REST 目錄的 Trino 目錄名稱。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。
PROJECT_ID：用於 BigLake metastore 的 Google Cloud 專案 ID。

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

trino --catalog=CATALOG_NAME

在下列版本中，Dataproc Trino 支援 Iceberg 的 Google 授權流程：

Dataproc on Compute Engine 2.2 執行階段版本 2.2.65 以上
Dataproc on Compute Engine 2.3 執行階段版本 2.3.11 以上
不支援 Compute Engine 3.0 上的 Dataproc。

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

Dataproc Trino 不支援憑證販售。

Iceberg 1.10 以上版本

開放原始碼 Iceberg 1.10 以上版本已內建 GoogleAuthManager 的 Google 授權流程支援。以下範例說明如何設定 Apache Spark，以使用 BigLake metastore 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

更改下列內容：

CATALOG_NAME：Iceberg REST 目錄的名稱。
APP_NAME：Spark 會話名稱。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。
PROJECT_ID：使用 Iceberg REST 目錄時的計費專案，可能與擁有 Cloud Storage bucket 的專案不同。如要瞭解使用 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

先前的 Iceberg 版本

如果是 1.10 之前的開放原始碼 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

更改下列內容：

CATALOG_NAME：Iceberg REST 目錄的名稱。

APP_NAME：Spark 會話名稱。

WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。
PROJECT_ID：使用 Iceberg REST 目錄時的計費專案，可能與擁有 Cloud Storage bucket 的專案不同。如要瞭解使用 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

詳情請參閱 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：使用 Iceberg REST 目錄的 Trino 目錄名稱。
SCHEMA_NAME：結構定義名稱。

在 BigQuery 中查詢資料表

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

Cloud Storage bucket 倉庫：如果您使用 gs:// 倉庫路徑設定用戶端，請使用四部分名稱 (P.C.N.T) project.catalog.namespace.table 從 BigQuery 查詢資料表。catalog 元件是 BigLake Metastore 目錄資源的名稱。詳情請參閱「查詢資料表」。
BigQuery 聯邦：如果您使用 bq:// 倉庫路徑設定用戶端，您建立的資料表會顯示在 BigQuery 中，並可使用標準 BigQuery SQL 直接查詢：
```
SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;
```
更改下列內容：
- NAMESPACE_NAME：命名空間名稱。
- TABLE_NAME：資料表名稱。

搭配使用目錄同盟與 BigQuery

您可以使用 Iceberg REST 目錄介面，管理及查詢 BigQuery 可見的資料表。BigQuery 聯合目錄不需要您建立目錄資源，只要啟用 BigQuery API，即可在任何專案中使用。這可讓您：

在 BigQuery 中建立及管理外部 Iceberg 資料表。
使用 Iceberg REST 目錄，在 BigQuery 中查詢 Apache Iceberg 專用 BigLake 資料表。

由於這些資源是由 BigQuery 管理，您必須具備適用的必要權限。聯合目錄不支援憑證販售。

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

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

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：使用 Iceberg REST 目錄的 Trino 目錄名稱。
SCHEMA_NAME：結構定義名稱。
BUCKET_NAME：您用於目錄的 Cloud Storage bucket。
LOCATION：BigQuery 位置。預設值為 US 多區域位置。

定價

如需定價詳情，請參閱「BigLake 定價」一文。

後續步驟

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

使用 BigLake metastore Iceberg REST 目錄 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

限制

目錄資源

Apache Iceberg REST 目錄資源

支援的目錄

目錄倉儲詳細資料

P.C.N.T 命名結構

設定 Iceberg REST 目錄

建立目錄

使用者憑證

控制台

gcloud

憑證臨時配發模式

控制台

設定用戶端應用程式

叢集

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

憑證臨時配發範例

無伺服器

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

憑證臨時配發範例

Trino

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

Iceberg 1.10 以上版本

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

憑證臨時配發範例

先前的 Iceberg 版本

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

憑證臨時配發範例

建立命名空間或結構定義

Spark

Cloud Storage 倉儲

Trino

Cloud Storage 倉儲

在 BigQuery 中查詢資料表

搭配使用目錄同盟與 BigQuery

Spark

Trino

定價

後續步驟

使用 BigLake metastore Iceberg REST 目錄