创建目录

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

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

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

准备工作

  1. 阅读 关于 Lakehouse 运行时目录，了解 Lakehouse 运行时目录的工作原理以及服务的限制。
    2. 登录您的 Google Cloud 账号。如果您是 Google Cloud的新用户， 请创建一个账号，以评估我们的产品在 实际场景中的表现。新客户还可以获得 300 美元的免费抵用金，用于 运行、测试和部署工作负载。

    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.

    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

    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.

    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)。在多存储桶目录中注册表需要特定的表注册权限 (biglake.tables.register)，该权限包含在 BigLake Admin 角色中。
  • 在凭据分发模式下使用自动预配的目录服务帐号： Storage Object User (roles/storage.objectUser) 目标 Cloud Storage 存储分区。创建目录后，请在存储分区上向自动预配的服务帐号明确授予 Storage Object User 角色 (roles/storage.objectUser)。

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

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

创建目录

创建目录。

创建目录

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

控制台

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

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

  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

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

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

如需创建多存储桶 (bl://) 目录（推荐），请运行 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：目录的名称。对于多存储桶 (bl://) 目录（推荐），这是您的自定义目录名称。对于单存储桶 (gs://) 目录，此名称与 REST 目录使用的 Cloud Storage 存储桶 ID 一致。
  • 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：目录的名称。对于 多存储桶 (bl://) 目录（推荐），这是您的自定义 目录名称。对于单存储桶 (gs://) 目录，此名称与 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。