创建目录

借助 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 角色中。
• 在凭证分发模式下使用自动预配的目录服务账号：目标 Cloud Storage 存储桶上的 Storage Object User (roles/storage.objectUser)。创建目录后，向自动预配的服务账号明确授予存储桶的 Storage Object User 角色 (roles/storage.objectUser)。

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

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

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

创建目录

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

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

控制台

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

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

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

   前往 Lakehouse

2. 点击创建目录，然后选择 Lakehouse 运行时目录。

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

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

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

6. 在目录 ID 部分，为目录输入自定义名称。

7. 在主要位置部分，选择一个位置。位置必须靠近主存储桶的区域。

8. 点击继续。

9. 在数据路径步骤中，如果您想添加其他 Cloud Storage 路径，请点击添加路径，然后输入或浏览路径。

10. 点击继续。

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

    注意 ：如果您选择最终用户凭据，Lakehouse 运行时目录不会自动管理目录中的表。您无法启用表管理任务，例如压缩和快照到期。

12. 点击创建。

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

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

    1. 在身份验证方法下，点击设置存储桶权限（如果您的目录使用多个存储桶，则点击为存储桶设置权限）。
    2. 在对话框中，点击确认。

创建单存储桶目录

注意：请避免对新项目使用单存储桶配置。此配置会将您的目录限制为单个存储桶，并将目录名称锁定为存储桶名称。

1. 在 Lakehouse 页面上，点击创建目录，然后选择 Lakehouse 运行时目录。
2. 对于目录类型，选择 Iceberg Rest 目录或 Hive Metastore。
3. 如果您选择了 Iceberg Rest 目录，请在 Lakehouse 目录存储桶选项中选择单存储桶目录。
4. 对于默认目录 Cloud Storage 存储桶（或 Apache Hive 目录端点的默认目录 Cloud Storage 路径），输入或浏览要与目录搭配使用的 Cloud Storage 存储桶。对于单存储桶目录，每个存储桶只能有一个目录，并且目录名称与存储桶名称一致。
5. 点击继续。
6. 对于身份验证方法，选择最终用户凭证或凭证分发模式。
7. 点击创建。
8. 如果您选择了凭证分发模式，请执行以下额外步骤：
   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 表示凭证分发模式。如果您指定 end-user，则 Lakehouse 运行时目录不会自动管理目录中的表。您无法启用表管理任务，例如压缩和快照到期。

  注意： 如果您使用凭证发放模式，则必须向目录的自动预配 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 与该目录使用的 Cloud Storage 存储桶 ID 一致。
• PROJECT_ID：您的 Google Cloud项目 ID。
• CREDENTIAL_MODE：身份验证方法。 使用 end-user 表示最终用户凭证，或使用 vended-credentials 表示凭证分发模式。

REST

创建 Apache Iceberg REST Catalog 端点

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

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg-catalog-id=CATALOG_ID

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

替换以下内容：

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