此页面由 Cloud Translation API 翻译。

数据网格用户指南

Cortex Framework 的数据网格通过 BigQuery 元数据和 Dataplex Universal Catalog 扩展了数据基础，以实现数据治理、可发现性和访问权限控制。为此，我们提供了一组基本的元数据资源和 BigQuery 资产注释，这些资源和注释可以自定义，并且可以选择性地与数据基础一起部署。这些基本规范提供了一种自定义配置，可作为元数据基础来补充 Cortex Framework Data Foundation。在继续阅读本指南之前，请先了解 Data Mesh 概念。

本页中概述的步骤专门用于为 Cortex Framework 配置 Data Mesh。在数据网格目录部分中，找到每个工作负载的特定文件夹内的数据网格配置文件。

Cortex Framework 的数据网格架构

图 1。Cortex Framework 的数据网格架构。

设计

Cortex 的 Data Mesh 的设计与整体数据基础类似，包含三个阶段，每个阶段都有由 Cortex 或用户管理的不同子组件：

基本资源规范更新：每次发布时，Cortex 都会更新基本资源规范，为数据网格提供标准化的元数据基础。
资源规范自定义：在部署之前，用户可以根据自己的特定使用场景和要求调整资源规范。
数据网格部署和更新：用户可以在 Cortex 配置文件中启用数据网格。在 Cortex 部署期间，它会在数据资产之后部署。此外，用户还可以灵活地单独部署 Data Mesh 以进行进一步更新。

Cortex Framework 的数据网格设计

图 2。Cortex Framework 的数据网格设计。

数据网格目录

在以下位置找到每个工作负载和数据源的 Data Mesh 基本配置文件。请注意，目录包含不同的文件结构，但所有规范都类似地位于 config 文件夹下。

工作负载	数据源	目录路径
可运行	SAP ECC	`src/SAP/SAP_REPORTING/config/ecc`
	SAP S/4 HANA	`src/SAP/SAP_REPORTING/config/s4`
	Salesforce Sales Cloud (SFDC)	`src/SFDC/config`
	Oracle EBS	`src/OracleEBS/config`
营销	CM360	`src/marketing/src/CM360/config`
	Google Ads	`src/marketing/src/GoogleAds/config`
	Meta	`src/marketing/src/Meta/config`
	Salesforce Marketing Cloud (SFMC)	`src/marketing/src/SFMC/config`
	TikTok	`src/marketing/src/TikTok/config`
	YouTube（搭配 DV360）	`src/marketing/src/DV360/config`
	Google Analytics 4	`src/marketing/src/GA4/config`

元数据资源是在数据源级别定义的，每个 Google Cloud 项目使用一个 YAML 文件，其中包含所有资源的列表。用户可以根据需要扩展现有文件，或在该目录中创建包含其他资源规范的其他 YAML 文件。

资源注解是在资源级别定义的，并且包含目录中的许多 YAML 文件，每个文件包含一个注解。

启用 API 并验证权限

通过修改数据网格的默认值，您可以实现超出说明范围的功能。如果您需要修改 config.json 中数据网格的默认值，以实现说明以外的功能，请确保已按照下表中的说明设置必要的 API 和确认权限。在部署具有数据基础的数据网格时，请向部署用户或 Cloud Build 账号授予权限。如果部署涉及不同的源项目和目标项目，请确保在采用这些功能的两个项目中都启用了这些 API 和权限。

功能	权限角色	文档
BigQuery 资产和行访问权限	BigQuery Data Owner	如需了解详情，请参阅必需的角色（针对资产角色）和必需的权限（针对行角色）。
BigQuery 列访问权限	Policy Tag Admin	如需了解详情，请参阅用于列级访问权限控制的角色和使用列级访问权限控制限制访问权限文档。
目录标记	Data Catalog TagTemplate Owner	如需了解详情，请参阅使用 Data Catalog 标记 BigQuery 表和 Data Catalog IAM 文档。
Dataplex Universal Catalog 数据湖	Dataplex Universal Catalog Editor	如需了解详情，请参阅创建湖文档。

了解基本资源规格

配置 Cortex 的数据网格的主要接口是基本资源规范，这是一组开箱即用的 YAML 文件，用于定义已部署的元数据资源和注释。基本规范提供了初始建议和语法示例，但旨在进一步自定义以满足用户需求。这些规范分为两类：

可应用于各种数据资产的元数据资源。例如，用于定义如何使用业务网域标记资源的目录标记模板。
用于指定如何将元数据资源应用于特定数据资产的注释。例如，将特定表与“销售”网域相关联的目录标记。

以下各部分将引导您了解每种规范类型的基本示例，并说明如何自定义这些规范。基本规范标记为 ## CORTEX-CUSTOMER，如果启用了关联的部署选项，则应修改这些规范以适应部署。如需了解高级用法，请参阅 src/common/data_mesh/src/data_mesh_types.py 中这些规范架构的规范定义。

元数据资源

元数据资源是项目中存在的共享实体，可应用于许多数据资产。大多数规范都包含一个 display_name 字段，该字段需满足以下条件：

只能包含 Unicode 字母、数字 (0-9)、下划线 (_)、短划线 (-) 和空格 ( )。
不能以空格开头或结尾。
长度上限为 200 个字符。

在某些情况下，display_name 也用作 ID，这可能会带来额外的要求。在这些情况下，我们会提供指向规范文档的链接。

如果部署引用了不同源项目和目标项目中的元数据资源，则必须为每个项目定义一个规范。例如，Cortex Salesforce (SFDC) 包含两个 Lake 规范。一个用于原始区域和 CDC 区域，另一个用于报告。

Dataplex Universal Catalog 数据湖

Dataplex Universal Catalog 数据湖、区域和资产用于从工程角度整理数据。数据湖具有 region，数据区具有 location_type，这两者都与 Cortex 位置（config.json > location）相关。Cortex 位置定义了 BigQuery 数据集的存储位置，可以是单区域，也可以是多区域。可用区 location_type 应设置为 SINGLE_REGION | MULTI_REGION 以匹配该值。不过，Lake 区域必须始终是单个区域。如果 Cortex 位置和可用区 location_type 是多区域，请选择该组中的单个区域作为 Lake 区域。

要求
- 数据湖 display_name 用作 lake_id，必须符合官方要求。可用区和素材资源 display_name 也是如此。可用区 ID 在项目的所有数据湖中必须是唯一的。
- 数据湖规范必须与单个区域相关联。
- asset_name 应与 BigQuery 数据集的 ID 匹配，但 display_name 可以是更便于用户理解的标签。
限制
- Dataplex Universal Catalog 仅支持注册 BigQuery 数据集，而不支持注册单个表作为 Dataplex Universal Catalog 资产。
- 一项资产可能只能在一个区域中注册。
- Dataplex Universal Catalog 仅在某些位置受支持。如需了解详情，请参阅 Dataplex Universal Catalog 位置。

请参阅 lakes.yaml 中的以下示例。

这些资源在指定 data_mesh_types.Lakes 的 YAML 文件中定义。

目录标记模板

您可以使用 Data Catalog 标记模板为 BigQuery 表或各个列添加上下文。它们可帮助您从技术和业务角度对数据进行分类和了解，并与 Dataplex Universal Catalog 搜索工具集成。它们定义了可用于标记数据的特定字段，以及每个字段可包含的信息类型（例如文本、数字、日期）。目录标记是具有实际字段值的模板实例。

模板字段 display_name 用作字段 ID，必须遵循 TagTemplate 类中针对 TagTemplate.fields 指定的要求。如需详细了解支持的字段类型，请参阅 Data Catalog 字段类型。

Cortex Data Mesh 会将所有标记模板创建为可公开读取。此外，它还为标记模板规范引入了额外的 level 概念，用于定义标记应应用于整个素材资源、素材资源中的各个字段还是两者都应用，可能的值为：ASSET | FIELD | ANY。虽然目前并未严格执行此操作，但未来的验证检查可能会确保在部署期间将标记应用到适当的级别。

请参阅以下示例。

模板在指定 data_mesh_types.CatalogTagTemplates 的 YAML 文件中定义。

目录标记是模板的实例，将在下文的“资源注释”中进行讨论。

使用标记模板实现资源级和列级访问权限控制

Cortex Framework 支持对与目录标记模板关联的所有制品启用资产或列级访问权限控制。例如，如果用户希望根据业务线授予对素材资源的访问权限，则可以为 line_of_business 目录代码模板创建 asset_policies，并为每个业务网域指定不同的委托人。每项政策都接受 filters，可用于仅匹配具有特定值的标记。在这种情况下，我们可以匹配 domain 值。请注意，这些 filters 仅支持相等性匹配，不支持其他运算符。如果列出了多个过滤条件，结果必须满足所有过滤条件（例如，filter_a AND filter_b）。最终的资源政策集是直接在注释中定义的政策与模板政策中的政策的并集。

使用目录标记的列级访问权限控制功能也类似，它会对匹配的字段应用政策标记。不过，由于一列只能应用一个政策标记，因此优先级如下：

直接政策标记：如果直接在列注解中定义了政策标记，则该标记具有优先权。
匹配的标记模板政策：否则，访问权限由关联的目录标记模板中字段上定义的第一个匹配政策决定。

使用此功能时，我们强烈建议您同时启用或停用目录标记和访问控制列表 (ACL) 的部署。这可确保 ACL 得到正确部署。

如需了解此高级功能的规范，请参阅 data_mesh_types.CatalogTagTemplate 中 asset_policies 和 field_policies 参数的定义。

目录术语表

术语库是一种工具，可用于提供数据资产中特定列所用术语的字典，这些术语可能无法被普遍理解。用户可以在控制台中手动添加条款，但资源规范不支持此操作。

政策分类和标记

借助政策分类和标记，您可以以标准化方式对敏感数据资产实现列级访问权限控制。例如，可能存在一种用于控制特定业务线上的 PII 数据的分类法，其中只有某些群组可以读取已遮盖的数据、未遮盖的数据，或者根本没有读取权限。

如需详细了解政策分类和标记，请参阅列数据遮盖简介文档。以下部分尤其相关：

Cortex Framework 提供了一些示例政策标记，用于演示如何指定这些标记以及它们的潜在用途，但默认情况下，在 Data Mesh 部署中不会启用影响访问权限控制的资源。

请参阅以下示例。

政策分类在 YAML 文件中定义，这些文件指定了 data_mesh_types.PolicyTaxonomies。

素材资源注释

注释用于指定适用于特定资源的元数据，并且可以引用已定义的共享元数据资源。注释包括：

资产说明
字段说明
目录标记
资源、行和列级访问权限控制

Cortex Framework 数据基础为以下工作负载提供预配置的注释（说明）。

SAP ECC（原始数据、CDC 和报告）
SAP S4 HANA（原始数据、CDC 和报告）
SFDC（仅限报告）
Oracle EBS（仅用于报告）
CM360（仅限报告）
Google Ads（仅限报告）
Meta（仅限报告）
SFMC（仅限报告）
TikTok（仅限报告）
YouTube（搭配 DV360）（仅限报告）
Google Analytics 4（仅限报告）

请参阅以下示例。

注释在指定 data_mesh_types.BqAssetAnnotation 的 YAML 文件中定义。

目录标记

目录标记是已定义模板的实例，其中分配了适用于特定资产的字段值。请务必分配与关联模板中声明的字段类型相匹配的值。

TIMESTAMP 值应采用以下格式之一：

  "%Y-%m-%d %H:%M:%S%z"
  "%Y-%m-%d %H:%M:%S"
  "%Y-%m-%d"

请参阅以下示例。

请参阅 data_mesh_types.CatalogTag 中的规范定义。

指定访问政策读取者和主账号

使用访问权限政策控制对 Cortex Framework 中 BigQuery 数据的访问权限。这些政策定义了哪些正文可以访问特定数据资产、资产中的行，甚至单个列。主账号必须遵循 IAM 政策绑定成员定义的特定格式。

素材资源级访问权限

您可以授予对整个 BigQuery 资产的访问权限，并提供各种权限：

READER：查看资产中的数据。
WRITER：修改资产中的数据并向资产添加数据。
OWNER：对资产拥有完全控制权，包括管理访问权限。

这些权限相当于 SQL 中的 GRANT DCL 语句。

与大多数资源和注释的行为不同，覆盖标志不会移除具有 OWNERS 角色的现有主账号。添加新所有者时，如果启用了覆盖，新所有者只会附加到现有所有者。这是一项安全措施，可防止意外失去访问权限。如需移除资产所有者，请使用控制台。覆盖会移除具有 READER 或 WRITER 角色的现有主账号。

请参阅以下示例。

请参阅 data_mesh_types.BqAssetPolicy 中的规范定义。

行级访问权限

您可以根据某些列值过滤器授予对一组行的访问权限。指定行访问权限政策时，所提供的过滤条件字符串将插入到 CREATE DDL statement 中。如果启用了 overwrite 标志，系统会在应用新的行级访问权限政策之前舍弃所有现有的行级访问权限政策。

请考虑以下有关行级访问权限的信息：

添加任何行访问权限政策意味着，未在这些政策中指定的所有用户都无法访问任何行。
行级政策仅适用于表，不适用于视图。
避免在行访问权限政策过滤条件中使用分区列。如需了解资源类型和分区列，请参阅关联的报告设置 YAML 文件。

如需详细了解行级访问权限政策，请参阅行级安全性最佳实践。

请参阅以下示例。

请参阅 data_mesh_types.BqRowPolicy 中的规范定义。

列级访问权限

如需启用列级访问权限，请使用由政策标记名称和分类名称标识的政策标记来注释各个字段。更新政策标记元数据资源以配置访问权限控制。

请参阅以下示例。

请参阅 data_mesh_types.PolicyTagId 中的规范定义。

部署数据网格

数据网格可以作为数据基础部署的一部分进行部署，也可以单独部署。无论哪种情况，它都会使用 Cortex config.json 文件来确定相关变量，例如 BigQuery 数据集名称和部署选项。默认情况下，部署数据网格不会移除或覆盖任何现有资源或注释，以防止任何意外损失。不过，当单独部署时，也可以覆盖现有资源。

部署选项

您可以根据用户的需求和支出限制，在 config.json > DataMesh 中启用或停用以下部署选项。

选项	备注
`deployDescriptions`	这是默认启用的唯一选项，它会部署包含资产和列说明的 BigQuery 注释。无需启用任何其他 API 或权限。
`deployLakes`	部署数据湖和可用区。
`deployCatalog`	在资产注释中部署目录模板资源及其关联的标记。
`deployACLs`	通过资产注释部署政策分类资源以及资产、行和列级访问权限控制政策。日志包含指示访问权限政策如何变化的讯息。

使用 Data Foundation 进行部署

默认情况下，config.json > deployDataMesh 可在每个工作负载构建步骤结束时部署数据网格资产说明。此默认配置不需要启用任何其他 API 或角色。通过启用部署选项、所需的 API 和角色，以及修改关联的资源规范，可以利用数据基础架构部署数据网格的其他功能。

独自部署

如需单独部署数据网格，用户可以使用 common/data_mesh/deploy_data_mesh.py 文件。此实用程序在构建过程中用于一次部署一个工作负载的数据网格，但如果直接调用，它也可用于一次部署多个工作负载。应在 config.json 文件中启用要部署的规范所对应的工作负载。例如，如果部署 SAP 的数据网格，请确保 deploySAP=true。

为确保您部署时使用的是所需的软件包和版本，您可以运行 Cortex 部署流程所用映像中的实用程序，方法是使用以下命令：

  # Run container interactively
  docker container run -it gcr.io/kittycorn-public/deploy-kittycorn:v2.0

  # Clone the repo
  git clone https://github.com/GoogleCloudPlatform/cortex-data-foundation

  # Navigate into the repo
  cd cortex-data-foundation

如需获取有关可用参数及其用法的帮助，请运行以下命令：

  python src/common/data_mesh/deploy_data_mesh.py -h

以下是针对 SAP ECC 的调用示例：

  python src/common/data_mesh/deploy_data_mesh.py \
    --config-file config/config.json \
    --lake-directories \
        src/SAP/SAP_REPORTING/config/ecc/lakes \
    --tag-template-directories \
        src/SAP/SAP_REPORTING/config/ecc/tag_templates \
    --policy-directories \
        src/SAP/SAP_REPORTING/config/ecc/policy_taxonomies \
    --annotation-directories \
        src/SAP/SAP_REPORTING/config/ecc/annotations

如需了解目录位置，请参阅数据网格目录部分。

覆盖

默认情况下，部署 Data Mesh 不会覆盖任何现有资源或注释。不过，单独部署 Data Mesh 时可以启用 --overwrite 标志，以通过以下方式更改部署。

覆盖湖泊、目录标记模板和政策标记等元数据资源会删除任何同名的现有资源，但不会修改名称不同的现有资源。这意味着，如果从 YAML 文件中完全移除某个资源规范，然后重新部署 Data Mesh 并启用覆盖，则该资源规范不会被删除，因为不会发生名称冲突。这样一来，Cortex Data Mesh 部署就不会影响可能正在使用的现有资源。

对于湖和区等嵌套资源，覆盖资源会移除其所有子资源。例如，覆盖数据湖也会移除其现有的区域和资产引用。对于被覆盖的目录标记模板和政策标记，系统也会从资产中移除现有的关联注解引用。覆盖资源注解中的目录标记只会覆盖共享同一模板的现有目录标记实例。

只有在提供与现有说明冲突的有效非空新说明时，资产和字段说明覆盖才会生效。

另一方面，ACL 的行为有所不同。覆盖 ACL 会移除所有现有主账号（素材资源级所有者除外）。这是因为从访问政策中省略的主账号与被授予访问权限的主账号同等重要。

探索数据网格

部署数据网格后，用户可以使用 Data Catalog 搜索和查看数据资产。这包括根据已应用的目录标记值发现资产的功能。用户还可以根据需要手动创建和应用目录词汇表术语。

您可以在 BigQuery“架构”页面上查看已部署的访问权限政策，了解在每个级别上应用于特定资产的政策。

数据沿袭

用户可能会发现，启用和直观呈现 BigQuery 资产之间的沿袭关系非常有用。还可以通过 API 以编程方式访问谱系。数据沿袭仅支持资产级沿袭。数据沿袭与 Cortex Data Mesh 并非紧密相关，但未来可能会推出利用沿袭的新功能。

如有任何 Cortex Data Mesh 或 Cortex Framework 请求，请前往支持部分。