自 2026 年 4 月 20 日起，BigLake 现已更名为 Lakehouse。BigLake metastore 现已更名为 Lakehouse 运行时目录。Lakehouse API、客户端库、CLI 命令和 IAM 名称保持不变，仍引用 BigLake。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

设置 Apache Iceberg REST Catalog 端点

借助 Lakehouse 运行时目录中的 Apache Iceberg REST 目录端点，您可以在多个查询引擎中发现、读取和管理 Lakehouse 中的 Apache Iceberg 表。此端点基于 Apache Iceberg REST Catalog API 构建，可作为开源或第三方引擎（例如 Apache Spark）的单一事实来源，这些引擎可访问 Cloud Storage 中的数据并与 BigQuery 互操作。

该端点支持凭证分发（用于委托存储访问权限）以及跨区域复制和灾难恢复。虽然现有工作流可以继续使用早期的适用于 BigQuery 的自定义 Apache Iceberg 目录端点，但请为新目录使用 Apache Iceberg REST 目录端点，以获得更标准化且功能更丰富的界面。

准备工作

验证是否已为您的 Google Cloud 项目启用结算功能。
启用 BigLake API（如果尚未启用）。
启用 API 所需的角色
如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。
启用 API
在继续操作之前，请先熟悉 Lakehouse 运行时目录和 Iceberg REST 目录端点概览。
如果您有现有的第 1 版 (V1) Apache Iceberg 表，则必须先升级这些表，然后才能将其与 Apache Iceberg REST Catalog 端点搭配使用。如需了解详情，请参阅将 Iceberg V1 表升级到 V2。

所需的角色

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

执行管理任务，例如管理目录用户访问权限、存储空间访问权限和目录的凭证自动售卖模式：
- 针对项目的 BigLake Admin (roles/biglake.admin) 角色
- 针对所有关联 Cloud Storage 存储桶的 Storage Admin (roles/storage.admin) 角色。
在 Lakehouse 运行时目录中创建（注册）表：针对项目的 BigLake Admin (roles/biglake.admin) 角色。
在凭据自动售卖模式下读取表数据：项目的 BigLake Viewer (roles/biglake.viewer) 角色。如果您使用 Managed Service for Apache Spark 或 Dataflow 等查询引擎读取表数据，请向您用于在该引擎中运行作业的服务账号授予此角色。
以凭据自动售卖模式写入表数据：项目的 BigLake Editor (roles/biglake.editor) 角色。如果您使用 Managed Service for Apache Spark 或 Dataflow 等查询引擎写入表数据，请向您用于在该引擎中运行作业的服务账号授予此角色。
在凭证分发模式下使用自动预配的 Lakehouse 运行时目录服务账号：对所有关联的 Cloud Storage 存储桶拥有 Storage Object User (roles/storage.objectUser) 角色。创建目录后，请向目录的自动预配 Lakehouse 运行时目录服务账号明确授予所有关联存储桶的 Storage Object User 角色 (roles/storage.objectUser)。
在非凭证自动售卖模式下读取目录资源和表数据：
- 项目的 BigLake Viewer (roles/biglake.viewer) 角色
- 针对所有关联 Cloud Storage 存储桶的 Storage Object Viewer (roles/storage.objectViewer)。
在非凭证自动售卖模式下管理目录资源和写入表数据：
- 项目的 BigLake Editor (roles/biglake.editor) 角色
- 针对所有关联 Cloud Storage 存储桶的 Storage Object User (roles/storage.objectUser) 角色。

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

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

限制

Apache Iceberg REST Catalog 端点受以下限制：

一般限制

支持 Apache Iceberg V2 表（正式版）和 V3 表（预览版）。不支持 Iceberg V1 表。在将现有 V1 表与 Apache Iceberg REST 目录端点搭配使用之前，您必须将其升级到受支持的版本。
使用凭据分发模式时，如果查询引擎允许您为目录连接设置 io-impl 属性，则必须将其设置为 org.apache.iceberg.gcp.gcs.GCSFileIO。

表限制

使用 BigQuery 数据定义语言 (DDL) 或数据操纵语言 (DML) 语句在 Apache Iceberg REST 目录端点中创建或修改表的功能处于预览版阶段，需要启用 gcp.biglake.bigquery-dml.enabled 表属性。如需了解详情，请参阅配置表选项。
通过 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 文件大小上限为 1MB。如需申请提高此限制，请与您的 Google 客户支持团队联系。

查询限制

无法在 BigQuery 中使用五部分名称标识符查询 Apache Iceberg 元数据表（例如 .snapshots 或 .files）；您可以使用 Spark 查询这些表。

注意事项

创建目录时，请考虑以下配置。

存储桶类型

您可以选择创建多存储桶目录或单存储桶目录。

多存储桶目录（推荐）：此配置可让您的目录关联多个存储桶，并让您独立于任何存储桶名称来命名目录。
单存储桶：此配置会将目录限制为单个存储桶，并将目录名称锁定为存储桶名称。不建议在新项目中使用。

如需详细了解这些配置之间的差异，请参阅目录和存储位置。

凭证模式（范围）

您可以创建使用最终用户凭据或凭据分发模式的目录。

最终用户凭据：目录会将访问它的最终用户的身份传递给 Cloud Storage，以进行授权检查。
凭据分发模式：一种存储访问权限委托机制，可让 Lakehouse 运行时目录管理员直接控制 Lakehouse 运行时目录资源的权限，从而无需目录用户直接访问 Cloud Storage 存储桶。它允许 Google Cloud 的 Lakehouse 管理员向用户授予对特定数据文件的权限。

自动预配的 Lakehouse 运行时目录服务账号需要对所有关联的 Cloud Storage 存储桶拥有明确的 Storage Object User 角色 (roles/storage.objectUser)。默认情况下，它没有任何访问权限。如果没有此角色，则提供的凭据将没有足够的范围来执行存储写入。如果您使用 gcloud 或 Terraform 等工具，则必须手动授予此角色。

自动预配的目录服务账号的创建最终一致。这意味着服务账号需要一段时间才能在整个系统中生效。如果您在创建服务账号后立即尝试向其授予角色，请求可能会失败。如需了解访问权限更改传播的平均时间，请参阅访问权限更改传播。

位置

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

创建命名空间时，它会自动使用与目录相同的区域。
如果您的目录使用多区域存储桶，并且您希望将其与 BigQuery 多区域（US 或 EU）搭配使用，则必须删除并重新创建目录以指定主要位置。
如需根据数据驻留要求将目录请求直接路由到特定区域，您可以将工具和查询引擎配置为使用区域端点 (https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog)，而不是全球端点 (https://biglake.googleapis.com/iceberg/v1/restcatalog)。

设置 Iceberg REST Catalog 端点

在设置目录之前，我们建议您先阅读 Apache Iceberg REST 目录端点概览，了解其资源层次结构、目录类型和命名结构。

以下是在 Lakehouse 运行时目录中使用 Apache Iceberg REST Catalog 端点时要遵循的一般步骤：

选择目录类型：多存储桶目录（推荐）或单存储桶目录。
创建一个指向仓库位置的目录。
将客户端应用配置为使用 Apache Iceberg REST 目录端点。
创建命名空间或架构来整理表。
使用配置的客户端创建和查询表。

创建目录

请按照以下步骤，根据您首选的凭证模式和存储桶类型创建目录。

控制台

创建多存储桶目录（推荐）

通过此配置，您的目录可以关联多个存储桶，并且您可以独立于任何存储桶名称来命名目录。

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

前往 Lakehouse
点击创建目录。
对于目录类型，选择 Iceberg Rest 目录。
在 Lakehouse 目录存储桶选项部分，选择多个存储桶目录。
对于默认目录 Cloud Storage 路径，输入或浏览要与目录搭配使用的 Cloud Storage 路径。
在目录 ID 部分，为目录输入自定义名称。
在主要位置部分，选择一个位置。位置必须靠近主存储桶的区域。
点击继续。
在数据路径步骤中，根据需要添加其他 Cloud Storage 路径。
点击继续。
对于身份验证方法，选择最终用户凭证或凭证分发模式。
点击创建。

系统会创建您的目录，并打开目录详情页面。
如果您选择了凭证分发模式，请执行以下额外步骤：
1. 在身份验证方法下，点击设置存储桶权限。
2. 在对话框中，点击确认。

创建单存储桶目录

对于目录类型，选择 Iceberg Rest 目录。
对于 Lakehouse 运行时目录存储桶选项，选择单存储桶目录。
对于默认目录 Cloud Storage 路径，输入或浏览要与目录搭配使用的 Cloud Storage 路径。（对于单存储桶目录，每个存储桶只能有一个目录，并且目录名称与存储桶名称一致）。
点击继续。
对于身份验证方法，选择最终用户凭证或凭证分发模式。
点击创建。
如果您选择了凭证分发模式，请执行以下额外步骤：
1. 在身份验证方法下，点击设置存储桶权限。
2. 在对话框中，点击确认。

gcloud

创建多存储桶目录（推荐）

通过此配置，您的目录可以关联多个存储桶，并且您可以独立于任何存储桶名称来命名目录。

如需创建多存储桶目录（推荐），请运行 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：目录的名称。对于多存储桶目录（推荐），这是您的自定义目录名称。
PROJECT_ID： Google Cloud项目 ID。
DEFAULT_LOCATION：指定目录的默认存储位置。您可以指定存储桶 (gs://my-bucket) 或子路径 (gs://my-bucket/path)。目录中的所有命名空间和表都必须位于指定路径下。例如，如果您指定 gs://my-bucket/path，则无法在 gs://my-bucket/another/path 下创建命名空间或表。
CREDENTIAL_MODE：身份验证方法。使用 end-user 表示最终用户凭证，或使用 vended-credentials 表示凭证分发模式。

注意：如果您使用凭证自动发放模式，则必须向目录的自动预配 Lakehouse 运行时目录服务账号明确授予所有关联存储桶的 Storage Object User 角色 (roles/storage.objectUser)。
RESTRICTED_LOCATIONS：（可选）以英文逗号分隔的其他允许存储位置列表，格式为 gs://my-bucket-1/...,gs://my-bucket-2/...。如果您指定了路径（例如 gs://my-bucket/path），则该存储桶中的任何命名空间或表都必须位于该路径下。默认位置和受限位置的所有已配置 Cloud Storage 位置都必须位于同一地理区域组或管辖区（例如美国、欧洲、加拿大或亚洲）。例如，您不能将美国境内的存储桶与欧洲境内的存储桶混合。如需查看支持的位置列表，请参阅 Lakehouse 位置。

警告：避免配置与其他目录重叠的路径，以防止未经授权的凭证泄露。如需了解详情，请参阅多存储桶目录。
LOCATION：（可选）目录的主要区域，用于确保与 BigQuery 的互操作性。对于美国区域（例如 US 或 us-central1）或欧盟区域（例如 EU 或 europe-west4）中的 Cloud Storage 存储桶，请分别指定 US 或 EU，以确保可从相应的 BigQuery 多区域访问和查询目录。如需了解详情，请参阅存储桶和目录区域。

创建单存储桶目录

如需创建单存储桶目录，请运行以下命令：

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

替换以下内容：

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

使用凭证分发进行配置

如需使用凭证分发，您必须使用凭证分发模式下的目录，并通过向 SparkSession 构建器添加以下行，将值为 vended-credentials 的 X-Iceberg-Access-Delegation 标头添加到 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('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 文档中的RESTCatalog 中的标头部分。

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

Managed Service for Apache Spark on Compute Engine 2.2 映像版本 2.2.65 及更高版本。
Managed Service for Apache Spark on Compute Engine 2.3 映像版本 2.3.11 及更高版本。

无服务器

使用简化的配置属性（推荐）或手动指定属性，向 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"

替换以下内容：

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

使用凭证分发进行配置

如需使用凭证发放功能，您必须使用凭证发放模式下的目录，并通过在 Managed Service for Apache Spark 配置中添加以下行，将值为 vended-credentials 的 X-Iceberg-Access-Delegation 标头添加到 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=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

如需将 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：仓库的路径。对于 BigLake 目录，请使用 bl://projects/PROJECT_ID/catalogs/CATALOG_ID。对于 Cloud Storage 存储桶目录，请使用 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 授权流程：

Managed Service for Apache Spark on Compute Engine 2.2 运行时版本 2.2.65 及更高版本
Managed Service for Apache Spark on Compute Engine 2.3 运行时版本 2.3.11 及更高版本
不支持 Managed Service for Apache Spark on Compute Engine 3.0。

使用凭证分发进行配置

只有 Trino 481 及更高版本支持凭证发放。

Apache Iceberg 1.10 或更高版本

开源 Apache Iceberg 1.10 及更高版本内置了对 GoogleAuthManager 中 Google 授权流的支持。以下示例展示了如何将 Spark 配置为使用 Apache Iceberg REST Catalog 端点。

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

使用凭证分发进行配置

上面的示例不使用凭证分发。如需使用凭证发放功能，您必须使用凭证发放模式下的目录，并通过向 SparkSession 构建器添加以下行，将 X-Iceberg-Access-Delegation 标头添加到 Apache Iceberg REST 目录端点请求中，其值为 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：对于 API 的稳定版本，设置为 v1。
WAREHOUSE_PATH：仓库的路径。对于 BigLake 目录，请使用 bl://projects/PROJECT_ID/catalogs/CATALOG_ID。对于 Cloud Storage 存储桶目录，请使用 gs://CLOUD_STORAGE_BUCKET_NAME。
PROJECT_ID：使用 Apache Iceberg REST 目录端点所产生的费用将计入该项目，该项目可能与拥有 Cloud Storage 存储桶的项目不同。如需详细了解使用 REST API 时的项目配置，请参阅系统参数。
TOKEN：您的身份验证令牌，有效期为一小时，例如使用 gcloud auth application-default print-access-token 生成的令牌。

使用凭证分发进行配置

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

.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
选择现有目录，如果没有，请创建一个。
在菜单栏中，点击 + 创建命名空间。
在命名空间名称字段中，为命名空间输入一个唯一的名称。
对于位置，指定要与命名空间关联的路径：
- 多存储桶（推荐）：您可以设置任何自定义位置，只要该位置位于目录允许的位置（default_location 或 restricted_locations）下即可。如果您未指定位置，则系统会在目录的默认位置（例如 gs://{path-to-default-location}/{namespace_name}）下创建命名空间。
- 单存储桶：命名空间位置会自动沿用目录的单存储桶位置。
点击创建。

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：架构的名称。

升级目录

如果您已有单存储桶目录，则可以将其升级为多存储桶目录类型（推荐）。升级后，您可以关联多个存储桶并配置受限位置，同时保留原始目录名称。

后续步骤

了解如何在 Google Cloud 控制台中管理目录。
了解由 Lakehouse 管理的 Apache Iceberg 表。

设置 Apache Iceberg REST Catalog 端点 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

限制

注意事项

存储桶类型

凭证模式（范围）

位置

设置 Iceberg REST Catalog 端点

创建目录

控制台

创建单存储桶目录

gcloud

创建单存储桶目录

配置客户端应用

集群

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

手动配置

使用凭证分发进行配置

含凭证分发的示例

无服务器

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

手动配置

使用凭证分发进行配置

含凭证分发的示例

Trino

使用凭证分发进行配置

Apache Iceberg 1.10 或更高版本

使用凭证分发进行配置

含凭证分发的示例

之前的 Apache Iceberg 版本

使用凭证分发进行配置

含凭证分发的示例

创建命名空间或架构

控制台

Spark

Cloud Storage 仓库

Trino

Cloud Storage 仓库

升级目录

后续步骤

设置 Apache Iceberg REST Catalog 端点