管理数据湖、区域和资产的元数据

本指南介绍了数据湖、区域和资产的 Dataplex Universal Catalog 元数据，以及如何使用 Dataplex Universal Catalog API 来管理这些元数据。

概览

Dataplex Universal Catalog 会扫描以下内容：

  • 数据湖中的结构化和半结构化数据资产，用于将表元数据提取到表实体中
  • 非结构化数据（例如图片和文本），用于将文件集元数据提取到文件集实体中

您可以使用 Dataplex Universal Catalog Metadata API 执行以下操作：

  • 查看、修改和删除表和文件集实体的元数据
  • 创建自己的表或文件集实体元数据

您可以使用以下工具分析 Dataplex Universal Catalog 元数据：

  • 用于搜索和添加标记的 Data Catalog（已弃用）
  • Dataproc Metastore 和 BigQuery，用于表元数据查询和分析处理

Dataplex Universal Catalog API

本部分总结了 Dataplex Universal Catalog API 及其关键资源。

控制平面 API

Dataplex Universal Catalog 控制平面 API 允许创建和管理数据湖、可用区和资产资源。

  • 数据湖：一种 Dataplex Universal Catalog 服务实例，可用于管理组织内各个项目中的存储资源。

  • 区域：数据湖内资产的逻辑分组。在数据湖中使用多个区域，以便根据数据准备情况、工作负载或组织结构来整理数据。

  • 资产：存储资源，其中包含存储在 Cloud Storage 存储分区或 BigQuery 数据集中的数据，这些资源已附加到数据湖内的区域。

Metadata API

使用 Dataplex Universal Catalog Metadata API 在表和文件集实体及分区中创建和管理元数据。Dataplex Universal Catalog 会扫描数据湖中的数据资产或您提供的数据资产，以创建实体和分区。实体和分区会保留对关联的资源和物理存储位置的引用。

主要概念

表格实体：

具有明确定义架构的结构化数据的元数据。表格实体由实体 ID 和数据位置唯一标识。您可以在 BigQuery 和 Dataproc Metastore 中查询表实体元数据：

  • Cloud Storage 对象：Cloud Storage 对象的元数据，可通过 Cloud Storage API 进行访问。
  • BigQuery 表：BigQuery 表的元数据，可通过 BigQuery API 进行访问。
文件集实体：

有关非结构化（通常无架构）数据的元数据。文件集通过实体 ID 和数据位置进行唯一标识。每个文件集都有一个数据格式。

分区：

表或文件集实体中一部分数据的元数据，由一组键值对和数据位置标识。

试用 API

您可以使用 Dataplex Universal Catalog lakes.zones.entities 和 lakes.zones.partitions API 参考文档页面查看与每个 API 关联的参数和字段。使用每个 API 方法的参考文档随附的试用此 API 面板，通过不同的参数和字段发出 API 请求。您可以构建、查看和提交请求，而无需生成凭据，然后查看服务返回的响应。

以下部分提供了相关信息，可帮助您了解和使用 Dataplex Universal Catalog 元数据 API。

实体

列出实体

如需限制服务返回的实体列表，请向 list entities 请求网址添加 filter 查询参数。

获取实体

默认情况下，Get Entity 响应包含基本实体元数据。如需检索其他架构元数据，请将 view 查询参数添加到请求网址。

兼容性详情：虽然 Dataplex 通用目录元数据在元数据 API 中集中注册，但只有与 BigQuery 和 Apache Hive Metastore 兼容的实体表元数据才会发布到 BigQuery 和 Dataproc Metastore。Get Entity API 会返回 CompatibilityStatus 消息，其中指明表元数据是否与 BigQuery 和 Hive Metastore 兼容，如果不兼容，则说明不兼容的原因。

更新实体

使用此 API 可修改实体元数据，包括您或 Dataplex Universal Catalog 是否将管理实体元数据。

  • 此 API 会完全替换所有可变的 Entity 字段。 以下实体字段是不可变的，如果您在更新请求中指定这些字段，系统会忽略它们：
  • 为所有可变实体字段（包括所有架构字段）指定值，即使这些值未发生变化也是如此。
  • 提供 etag 字段。您可以先提交 entities.get 请求来获取 etag，该请求会在响应中返回实体的 etag。
  • 更新架构字段：您可以更新 Dataplex Universal Catalog 发现的表架构，以提高其准确性：
    • 如果架构是文件集，请将所有架构字段留空。
    • 如需定义重复字段，请将模式设置为 REPEATED。如需定义结构体字段，请将类型设置为 RECORD。
    • 您可以设置架构的 userManaged 字段，以指定是由您还是 Dataplex Universal Catalog 管理表元数据。默认设置为 Dataplex Universal Catalog 管理。如果 userManaged 设置为 true，则当 EntityView 设置为 SCHEMA 或 FULL 时，此设置会包含在 entities.get 请求返回的信息中。
  • 更新分区字段：
    • 对于非 Hive 样式的分区数据，Dataplex Universal Catalog 发现功能会自动生成分区键。例如，对于数据路径 gs://root/2020/12/31，系统会生成分区键 p0、p1 和 p2。为了使查询更加直观，您可以将 p0、p1 和 p2 分别更新为 year、month 和 day。
    • 如果您将分区样式更新为 Hive 样式，则分区字段将不可变。
  • 更新其他元数据字段：您可以更新自动生成的 mimeType、CompressionFormat、CsvOptions 和 JsonOptions 字段，以帮助 Dataplex Universal Catalog 发现数据。Dataplex Universal Catalog 发现功能将在下次运行时使用新值。

创建实体

使用 entities.create API 创建表或文件集元数据实体。填写必需字段和相关的可选字段，或者让 Dataplex Universal Catalog 发现服务填写可选字段。

删除实体

  • 提供 etag 字段。您可以先提交 entities.get 请求来获取 etag，该请求会在响应中返回实体的 etag。

如果删除了原始区域中表或文件集的底层数据，则在下次发现扫描时，系统会自动删除相应表或文件集的元数据。如果受管理区域中某个表的底层数据被删除，则相应地，系统不会删除该表的元数据，而是会报告数据缺失操作。如需解决此问题，请通过元数据 API 显式删除表元数据实体。

分区

列出分区

如需限制服务返回的分区列表，请向 list partitions 请求网址添加 filter 查询参数。

示例：

  • ?filter="Country=US AND State=CA AND City=Sunnyvale"
  • ?filter="year < 2000 AND month > 12 AND Date > 10"

获取分区

如需获取分区，您必须在网址末尾附加分区键值，以完成请求网址，格式为 partitions/value1/value2/…./value10。

示例：如果某个分区的具有值 {Country=US, State=CA, City=Sunnyvale}，则 GET 请求网址应以 /partitions/US/CA/Sunnyvale 结尾。

重要提示：附加的网址值必须经过双重编码。例如，url_encode(url_encode(value)) 可用于对“US:CA/CA#Sunnyvale”进行编码，使请求网址以 /partitions/US%253ACA/CA%2523Sunnyvale 结尾。响应中的名称字段会保留编码格式。

创建分区

如需为数据源创建自定义分区，请使用 partitions.create API。使用 Cloud Storage 路径指定必需的位置字段。

删除分区

通过将分区键值附加到请求网址的末尾来完成请求网址，格式为 partitions/value1/value2/…./value10。

示例：如果某个分区的值为 {Country=US, State=CA, City=Sunnyvale}，则请求网址应以 /partitions/US/CA/Sunnyvale 结尾。

重要提示：附加的网址值必须符合 RFC-1034 的要求，或者必须进行双重编码，例如，将 US:/CA#/Sunnyvale 编码为 US%3A/CA%3A/Sunnyvale。

后续步骤