注册表格

注册现有 Apache Iceberg 表会将其元数据集成到 Lakehouse 运行时目录中，从而使表数据可在命名空间内用于查询和管理。此过程不同于表创建，后者会初始化新的空表结构及其关联的存储空间。

准备工作

1. 验证是否已为您的 Google Cloud 项目启用结算功能。

2. 启用 BigLake API。

   启用 API 所需的角色

   如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

   启用 API

3. 使用 Apache Iceberg REST 目录端点设置 Lakehouse 运行时目录。

所需的角色

如需获得注册表所需的权限，请让管理员向您授予项目和存储桶的以下 IAM 角色：

• 注册表格：
  • BigLake Admin (roles/biglake.admin) - 您的项目
  • Storage Admin (roles/storage.admin) - 目标 Cloud Storage 存储桶

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

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

注册表格

注册现有 Iceberg 表。

gcloud

如需使用 gcloud 注册表，请运行 gcloud biglake iceberg tables register 命令。

gcloud biglake iceberg tables register TABLE_NAME \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    --namespace="NAMESPACE_NAME" \
    --metadata-location="METADATA_LOCATION" \
    [--overwrite]

替换以下内容：

• TABLE_NAME：要分配给已注册表的名称。
• PROJECT_ID： Google Cloud 项目 ID。
• CATALOG_ID：目录 ID。
• NAMESPACE_NAME：目录命名空间名称。
• METADATA_LOCATION：相应表的最新元数据 JSON 文件的 Cloud Storage URI，例如 gs://my-bucket/path/to/metadata/00001.metadata.json。
• --overwrite：（可选）如果表已存在，则覆盖该表。

REST

如需使用 REST API 注册 Iceberg 表，请向 RegisterIcebergTable 端点发出 POST 请求：

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/register

请求正文必须包含具有以下结构的 JSON 载荷：

{
  "name": "TABLE_NAME",
  "metadata-location": "METADATA_LOCATION",
  "overwrite": OVERWRITE
}

替换以下内容：

• PROJECT_ID： Google Cloud 项目 ID。
• CATALOG_ID：目录 ID。
• NAMESPACE_NAME：目录命名空间名称。
• TABLE_NAME：已注册的表的名称。
• METADATA_LOCATION：相应表的最新元数据 JSON 文件的 Cloud Storage URI。
• OVERWRITE：如果表存在，则为 true 以进行覆盖，否则为 false。

后续步骤

• 了解如何列出表。
• 了解如何查询表。
• 了解如何管理表 ACL。