创建目录

创建目录端点（例如 Apache Iceberg REST Catalog 端点或 Apache Hive 目录端点）会在 Lakehouse 运行时目录中建立管理端点。

此端点指向底层 Cloud Storage 存储桶，提供元数据层，让查询引擎和开源工作负载可以直接与您的表进行交互。

为 Lakehouse for Apache Iceberg 创建目录端点时，您可以选择最终用户凭据或凭据分发模式进行存储访问权限委托。

准备工作

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.

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)。

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

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

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

创建目录

创建目录。

控制台

创建多存储桶 (bl://) 目录（推荐）

注意 ：控制台中不支持多存储桶 (bl://) 目录（推荐）。 Google Cloud 如需更新此类目录，请使用 gcloud 或 REST API。

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

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

   前往 Lakehouse

2. 选择 创建目录。此时会打开创建目录 页面。

3. 选择目录配置：

   • 如需创建 Apache Iceberg REST Catalog，请选择 Iceberg REST Catalog 。

4. 配置目录：

   • 如果您选择 Iceberg REST Catalog ，请为目录类型选择 Cloud Storage 存储桶 ，然后选择要与 您的目录搭配使用的 Cloud Storage 存储桶。
   • 如果您选择 Hive 目录，请输入唯一的目录名称，然后选择 关联的 Cloud Storage 路径。

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

   如果您选择凭据分发模式，则自动预配的 Lakehouse 运行时目录服务帐号需要所有关联的 Cloud Storage 存储分区的明确 Storage Object User 角色 (roles/storage.objectUser)。默认情况下，它完全没有访问权限。如果没有此角色，分发的凭据就没有足够的范围来执行存储写入操作。

6. 选择创建 。

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

7. 在身份验证方法 下，选择设置存储桶权限 。

8. 在对话框中，选择确认 。

   这会验证目录的服务帐号是否具有所有关联存储分区的 Storage Object User 角色 (roles/storage.objectUser)。 如果您使用 gcloud 或 Terraform 创建目录，则必须手动授予此角色。

gcloud

创建多存储桶 (bl://) 目录（推荐）

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="biglake" \
    --default-location="DEFAULT_LOCATION" \
    [--restricted-locations="RESTRICTED_LOCATIONS"] \
    [--credential-mode="CREDENTIAL_MODE"] \
    [--primary-location="PRIMARY_LOCATION"]

替换以下内容：

• CATALOG_ID：Lakehouse 运行时目录的 ID。
• PROJECT_ID：您的 Google Cloud 项目 ID。
• DEFAULT_LOCATION：目录数据和元数据的基本 Cloud Storage 路径，格式为 gs://my-bucket/path 或 gs://my-bucket。目录中的所有命名空间和表都必须位于此路径下。例如，如果您指定 gs://my-bucket/path，则无法在 gs://my-bucket/another/path 下托管命名空间或表。
• RESTRICTED_LOCATIONS：（可选）以英文逗号分隔的其他允许的存储分区或路径列表。同样，如果您指定路径（例如 gs://my-bucket/path），则在该路径的存储桶下创建的所有命名空间和表都必须位于该路径内。安全警告 ：避免将路径配置为与其他目录重叠，以帮助防止凭据未经授权泄露。如需了解详情，请参阅跨多个存储分区的存储。
• CREDENTIAL_MODE：身份验证方法。对于最终用户凭据 ，请使用 end-user；对于凭据分发模式 ，请使用 vended-credentials。
• PRIMARY_LOCATION：（可选）目录的主要区域（例如 US 或 EU），以确保与 BigQuery 兼容。

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

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

如需创建单存储桶 (gs://) 目录，请将 --catalog-type 设置为 gcs-bucket：

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="gcs-bucket" \
    [--credential-mode="CREDENTIAL_MODE"]

替换以下内容：

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

REST

创建 Iceberg REST Catalog

如需使用 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。