创建目录

借助 Lakehouse 运行时目录，您可以在 无边界 Lakehouse 中创建 目录端点。

目录端点指向底层 Cloud Storage 存储桶，并提供元数据层，让查询引擎和开源工作负载可以直接与您的表互动。创建目录端点时，您可以选择最终用户凭据或凭据分发模式进行存储访问权限委托。

准备工作

1. 阅读 Lakehouse 运行时目录简介，了解 Lakehouse 运行时目录的工作原理以及该服务的限制。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

所需的角色

如需获得创建目录和注册表所需的权限，请让您的管理员为您授予以下 IAM 角色：

• 创建目录：
  • 针对项目的 BigLake Admin (roles/biglake.admin) 角色
  • 针对项目的 Storage Admin (roles/storage.admin) 角色
• 创建（注册）表： BigLake Admin (roles/biglake.admin) 针对您的项目。注册表需要特定的表注册权限 (biglake.tables.register)，该权限包含在 BigLake Admin 角色中。
• 在凭据分发模式下使用自动预配的目录服务帐号： Storage Object User (roles/storage.objectUser) 针对目标 Cloud Storage 存储桶。创建目录后，请向自动预配的服务帐号明确授予存储桶的 Storage Object User 角色 (roles/storage.objectUser)。

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

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

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

创建目录

请按照以下步骤根据您偏好的凭据模式和存储桶类型创建目录。如需详细了解不同的目录类型，请参阅 Apache Iceberg REST 目录端点简介。

注意： 在 Google Cloud 中创建或管理多存储桶目录时， 请为默认存储位置和受限存储 位置指定 Cloud Storage 路径 (gs://)。 bl://projects/PROJECT_ID/catalogs/CATALOG_ID URI 格式仅在客户端配置期间使用，用于在从查询引擎（例如 Spark 或 Trino）进行连接时标识 目录数据仓库。

控制台

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

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

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

   前往 Lakehouse

2. 点击创建目录 。

3. 对于目录类型，选择Iceberg Rest Catalog。

4. 对于 Lakehouse 目录存储桶选项 ，选择多存储桶目录 。

5. 对于默认目录 Cloud Storage 路径，输入或浏览要与目录搭配使用的 Cloud Storage 路径。

6. 对于目录 ID，输入目录的自定义名称。

7. 对于主要位置 ，选择一个位置。该位置必须靠近主存储桶的区域。

8. 点击继续 。

9. 在数据路径 步骤中，根据需要添加其他 Cloud Storage 路径。

10. 点击继续 。

11. 对于身份验证方法 ，选择最终用户凭据 或凭据分发模式 。

12. 点击创建 。

    系统会创建您的目录，并打开目录详情 页面。

13. 如果您选择了凭据分发模式，请执行以下额外步骤：

    1. 在身份验证方法 下，点击设置存储桶权限。
    2. 在对话框中，点击确认 。

创建单存储桶 (gs://) 目录

注意 ：强烈建议新项目不要使用单存储桶配置。此配置会将您的目录限制为单个存储桶，并将目录名称锁定为存储桶名称。

1. 对于目录类型，选择Iceberg Rest Catalog或Hive Metastore。
2. 对于 Lakehouse 目录存储桶选项 ，选择 单存储桶目录 。
3. 对于默认目录 Cloud Storage 路径，输入或浏览要与目录搭配使用的 Cloud Storage 路径。 （对于单存储桶 (gs://) 目录，每个存储桶只能有一个目录，并且 目录名称与存储桶名称一致）。
4. 点击继续 。
5. 对于身份验证方法 ，选择最终用户凭据 或凭据分发模式 。
6. 点击创建 。
7. 如果您选择了凭据分发模式，请执行以下额外步骤：
   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 多区域进行访问和查询。如需了解详情，请参阅存储桶和目录区域。

创建单存储桶 (gs://) 目录

注意 ：强烈建议新项目不要使用单存储桶配置。此配置会将您的目录限制为单个存储桶，并将目录名称锁定为存储桶名称。

如需创建单存储桶 (gs://) 目录，请运行以下命令：

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

替换以下内容：

• CATALOG_NAME：目录的名称。对于 单存储桶 (gs://) 目录，此名称与 REST 目录使用的 Cloud Storage 存储桶 ID 一致。
• PROJECT_ID：您的 Google Cloud 项目 ID。
• CREDENTIAL_MODE：身份验证方法。对于最终用户凭据，请使用 end-user；对于凭据分发模式，请使用 vended-credentials。

REST

创建 Iceberg REST 目录

如需使用 REST API 创建目录管理端点，请向 CreateIcebergCatalog 端点发出 POST 请求：

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?icebergCatalogId=CATALOG_ID

请求正文必须包含 IcebergCatalog JSON 载荷，用于定义目录配置，例如底层 Cloud Storage 存储桶数据仓库和身份验证模式。

替换以下内容：

• PROJECT_ID：您的 Google Cloud 项目 ID。
• CATALOG_ID：Lakehouse 运行时目录的 ID。