自 2026 年 4 月 20 日起，BigLake 现在称为 Lakehouse for Apache Iceberg。BigLake metastore 现已更名为 Lakehouse 运行时目录。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，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。
启用 API

所需角色

如需获得在 Lakehouse 运行时目录中使用 Apache Iceberg REST 目录端点所需的权限，请让管理员未您授予以下 IAM 角色：

执行管理任务，例如管理目录用户访问权限、存储访问权限和目录的凭证分发模式：
- 针对项目的 BigLake Admin (roles/biglake.admin) 角色
- 针对 Cloud Storage 存储桶的 Storage Admin (roles/storage.admin) 角色
在凭证分发模式下读取表数据： BigLake Viewer (roles/biglake.viewer) 针对项目的角色。如果您使用 Managed Service for Apache Spark、Managed Service for Apache Spark 或 Dataflow 等查询引擎读取表数据，请向您用于在该引擎中运行作业的服务帐号授予此角色。
在凭证分发模式下写入表数据： BigLake Editor (roles/biglake.editor) 针对项目的角色。如果您使用 Managed Service for Apache Spark、Managed Service for Apache Spark 或 Dataflow 等查询引擎写入表数据，请向您用于在该引擎中运行作业的服务帐号授予此角色。
在凭证分发模式下使用自动预配的 Lakehouse 运行时目录服务帐号： Storage Object User (roles/storage.objectUser) 针对目标 Cloud Storage 存储桶。创建目录后，请向目录的自动预配 Lakehouse 运行时目录服务帐号明确授予存储桶的 Storage Object User 角色 (roles/storage.objectUser)。
在非凭证分发模式下读取目录资源和表数据：
- BigLake Viewer (roles/biglake.viewer) 针对项目的角色
- Storage Object Viewer (roles/storage.objectViewer) 针对 Cloud Storage 存储桶
在非凭证分发模式下管理目录资源和写入表数据：
- 针对项目的 BigLake Editor (roles/biglake.editor) 角色
- 针对 Cloud Storage 存储桶的 Storage Object User (roles/storage.objectUser) 角色
使用 BigQuery 目录联合执行数据操纵语言 (DML) 操作：
- BigQuery Data Editor (roles/bigquery.dataEditor) 项目的
- Cloud Storage 存储桶的 roles/storage.adminStorage Admin ( ) 角色。如果您使用 Managed Service for Apache Spark 等查询引擎执行 DML 操作，请向您用于在该引擎中运行作业的服务帐号授予这些角色。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

限制

Apache Iceberg REST 目录端点受以下限制：

一般限制

仅支持 Iceberg V2 表；不支持 Iceberg V1 表。如果您有现有的 Iceberg V1 表，则必须先将其升级到 V2（例如，运行 ALTER TABLE catalog.schema.table SET TBLPROPERTIES ('format-version'='2'); 或使用类似的引擎操作），然后才能将其与 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 文件大小上限为 1MB。如需申请提高此限制，请与您的 Google 客户支持团队联系。

查询限制

无法在 BigQuery 中创建通过 Apache Iceberg REST 目录端点管理的 Apache Iceberg 表的视图。
无法在 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 管理员 Lakehouse向用户授予对特定数据文件的权限。

注意事项

在创建目录之前，请先熟悉位置要求。

创建命名空间时，它会自动使用与目录相同的区域。
如果您的目录使用多区域存储桶，并且您希望将其与 BigQuery 多区域（US 或 EU）搭配使用，则必须删除并重新创建目录以指定主要位置。

最终用户凭证

控制台

在 Google Cloud 控制台中打开 Lakehouse 页面。

前往 Lakehouse
点击创建目录 。
在选择 Cloud Storage 存储桶 字段中，输入要与目录搭配使用的 Cloud Storage 存储桶的名称。或者，点击浏览以选择现有存储桶或创建新存储桶。每个 Cloud Storage 存储桶只能有一个目录。
对于身份验证方法 ，选择最终用户凭证 。
点击创建。

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：目录的名称。对于 Lakehouse 运行时目录支持的 Apache Iceberg 表，此名称通常与 REST 目录使用的 Cloud Storage 存储桶 ID 匹配，例如，如果您的存储桶是 gs://bucket-id，则目录名称可能是 bucket-id。从 BigQuery 查询这些表时，此名称也用作目录标识符。
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 存储桶的 Storage Object User 角色 (roles/storage.objectUser)。默认情况下，它是在仅查看访问权限的情况下创建的。如果没有此角色，分发的凭证将没有足够的范围来执行存储写入操作。如果您使用 gcloud 或 Terraform 等工具，则必须手动授予此角色。

控制台

在 Google Cloud 控制台中打开 Lakehouse 页面。

前往 Lakehouse
点击 创建目录。系统会打开创建目录 页面。
对于选择 Cloud Storage 存储桶，输入要与目录搭配使用的 Cloud Storage 存储桶的名称。或者，点击浏览以从现有存储分区列表中进行选择或创建新存储分区。每个 Cloud Storage 存储桶只能有一个目录。
对于身份验证方法 ，选择凭证分发模式 。
点击创建。

系统会创建目录并打开目录详情 页面。
在身份验证方法 下，点击设置存储桶权限。
在对话框中，点击确认。

这会验证目录的服务帐号是否具有存储桶的 Storage Object Admin 角色。

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：目录的名称。此名称通常与 REST 目录使用的 Cloud Storage 存储桶 ID 匹配，例如，如果您的存储桶是 gs://bucket-id，则目录名称可能是 bucket-id。从 BigQuery 查询这些表时，此名称也用作目录标识符。
PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：（可选）目录的主要区域，以确保与 BigQuery 的互操作性。对于美国区域（例如 US 或 us-central1）或欧盟区域（例如 EU 或 europe-west4）中的 Cloud Storage 存储分区，请分别指定 US 或 EU，以确保目录可访问，并且可从相应的 BigQuery 多区域进行查询。如需了解更多信息，请参阅存储分区和目录区域。

创建目录后，请向目录的自动预配 Lakehouse 运行时目录服务帐号明确授予存储桶的 Storage Object User 角色 (roles/storage.objectUser)。

配置客户端应用

创建目录后，请将客户端应用配置为使用该目录。以下示例展示了如何配置凭证分发。

集群

如需在 Managed Service for Apache Spark 上将 Spark 与 Apache Iceberg REST 目录端点搭配使用，您可以使用属性来简化配置，也可以手动配置会话。

使用属性简化配置（推荐）

使用目录资源创建集群：

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION \
    --properties="dataproc: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.2。
CATALOG_NAME：要在 Spark 中使用的 Lakehouse 目录的名称。它可以与 CATALOG_ID 相同。
CATALOG_ID：您创建的 Lakehouse 目录的 ID。

然后，创建一个 Spark 会话，而无需指定手动目录参数：

from pyspark.sql import SparkSession

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

手动配置

如果您不使用集群属性，请按照上述说明创建集群（不使用 --properties 标志），然后手动配置 Spark 会话：

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：对于 API 的稳定版本，请设置为 v1。
WAREHOUSE_PATH：仓库的路径。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如需使用 BigQuery 目录联合，请参阅将目录联合与 BigQuery 搭配使用。
PROJECT_ID：使用 Apache Iceberg REST 目录端点所产生的费用将计入该项目，该项目可能与拥有 Cloud Storage 存储桶的项目不同。如需详细了解使用 REST API 时的项目配置，请参阅系统参数。

使用凭证分发进行配置

如需使用凭证分发，您必须使用凭证分发模式下的目录，并通过向 SparkSession构建器添加以下行，将 X-Iceberg-Access-Delegation标头添加到值为vended-credentials的 Iceberg REST 目录请求：

.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 映像版本 2.2.65 及更高版本的 Managed Service for Apache Spark。
Compute Engine 2.3 映像版本 2.3.11 及更高版本的 Managed Service for Apache Spark。

无服务器

使用属性（推荐）或通过指定所有参数，向 Managed Service for Apache Spark 提交 PySpark 批量工作负载，以简化配置。

使用属性简化配置（推荐）

使用目录资源提交批量作业：

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"

手动配置

如果您希望手动指定所有属性，请使用以下配置：

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：对于 API 的稳定版本，请设置为 v1。
WAREHOUSE_PATH：仓库的路径。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如需使用 BigQuery 目录联合，请参阅将目录联合与 BigQuery 搭配使用。

使用凭证分发进行配置

如需使用凭证分发，您必须使用凭证分发模式下的目录，并通过向 Managed Service for Apache Spark 配置添加以下行，将 X-Iceberg-Access-Delegation 标头添加到值为 vended-credentials 的 Apache Iceberg REST 目录端点请求：

.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

如需将 Trino 与 Apache Iceberg REST 目录端点搭配使用，请使用 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：对于 API 的稳定版本，请设置为 v1。
WAREHOUSE_PATH：仓库的路径。使用 gs://CLOUD_STORAGE_BUCKET_NAME。
PROJECT_ID：用于 Lakehouse 运行时目录的 Google Cloud 项目 ID 。

创建集群后，连接到主虚拟机实例，然后使用 Trino CLI：

trino --catalog=CATALOG_NAME

Managed Service for Apache Spark Trino 在以下版本中支持 Apache Iceberg 的 Google 授权流：

Compute Engine 2.2 运行时 2.2.65 及更高版本的 Managed Service for Apache Spark
Compute Engine 2.3 运行时 2.3.11 及更高版本的 Managed Service for Apache Spark
不支持 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：Apache Iceberg REST 目录端点的名称。
APP_NAME：Spark 会话的名称。
REST_API_VERSION：对于 API 的稳定版本，请设置为 v1。
WAREHOUSE_PATH：仓库的路径。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如需使用 BigQuery 目录联合，请参阅将目录联合与 BigQuery 搭配使用。
PROJECT_ID：使用 Apache Iceberg REST 目录端点所产生的费用将计入该项目，该项目可能与拥有 Cloud Storage 存储桶的项目不同。如需详细了解使用 REST API 时的项目配置，请参阅系统参数。

使用凭证分发进行配置

前面的示例未使用凭证分发。如需使用凭证分发，您必须使用凭证分发模式下的目录，并通过向 SparkSession构建器添加以下行，将 X-Iceberg-Access-Delegation标头添加到值为vended-credentials的 Apache Iceberg REST 目录端点请求：

.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：对于 API 的稳定版本，请设置为 v1。
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 创建它们。

控制台

在 Google Cloud 控制台中，前往 Lakehouse。

前往 Lakehouse
选择现有目录，或者如果没有目录，则创建一个目录。
在菜单栏中，点击 + 创建命名空间。
对于命名空间名称，输入命名空间的唯一名称。
对于位置，选择要与您的命名空间关联的 Cloud Storage 存储桶。
点击创建。

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 搭配使用。
了解如何在控制台中 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 仓库

后续步骤

设置 Lakehouse Iceberg REST 目录