此页面由 Cloud Translation API 翻译。

数据网格用户指南

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

本页中列出的步骤专门用于配置适用于 Cortex Framework 的数据网格。在“数据网格目录”部分中，在每个工作负载专用文件夹中查找数据网格配置文件。

Cortex Framework 的数据网格架构

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

设计

Cortex 的数据网格的设计与整体数据基础架构类似，由三个阶段组成，每个阶段包含由 Cortex 或用户管理的不同子组件：

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

Cortex Framework 的数据网格设计

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

数据网格目录

在以下位置找到每个工作负载和数据源的数据网格基础配置文件。假设目录包含不同的文件结构，但所有规范都位于 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 并验证权限

修改 Data Mesh 的默认值后，您可以实现超出说明的功能。如果您需要修改 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 数据湖	Dataplex Editor	如需了解详情，请参阅创建数据湖文档。

了解基本资源规范

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

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

以下部分将引导您浏览每种规范类型的基本示例，并说明如何对其进行自定义。基本规范带有 ## 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 数据湖

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

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

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

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

目录代码模板

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

模板字段 display_name 用作字段 ID，并且必须遵循 Class 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 部署中不会启用影响访问控制的资源。

请参阅以下示例。

政策分类在指定 data_mesh_types.PolicyTaxonomies 的 YAML 文件中定义。

素材资源注释

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

资产说明
字段说明
目录代码
资产、行和列级访问权限控制

Cortex Framework Data Foundation 为以下工作负载提供了预配置的注释（说明）。

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`	通过资产注释部署政策分类资源以及资产、行和列级访问权限控制政策。日志包含消息，指明访问权限政策的更改方式。

使用数据基础架构进行部署

默认情况下，config.json > deployDataMesh 会在每个工作负载构建步骤结束时部署 Data Mesh 资产说明。此默认配置无需启用任何其他 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 不会覆盖任何现有资源或注解。不过，在仅部署数据网格时，您可以启用 --overwrite 标志，以便通过以下方式更改部署。

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

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

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

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

探索数据网格

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

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

数据沿袭

用户可以启用并直观呈现 BigQuery 资产之间的谱系。您还可以通过 API 以编程方式访问谱系。数据沿袭仅支持素材资源级沿袭。数据谱系与 Cortex Data Mesh 并无关联，但未来可能会推出利用谱系的新功能。

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