创建目录

创建目录端点（例如 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 角色中。
  • 在凭据贩售模式下使用自动预配的目录服务账号：目标 Cloud Storage 存储分区上的 Storage Object User (roles/storage.objectUser)。创建目录后，请明确向自动预配的服务账号授予存储分区的 Storage Object User 角色 (roles/storage.objectUser)。

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

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

创建目录

创建目录。

创建目录

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

控制台

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

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

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

    前往 Lakehouse

  2. 点击创建目录。

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

  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 运行时目录服务账号明确授予所有关联存储分区的存储对象用户角色 (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://) 目录，此值与 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。