Knowledge Catalog 集成

本文档介绍了 Cortex Framework 如何与 Knowledge Catalog 集成，后者充当组织内企业数据产品的治理层。本文档还介绍了 Google Cloud Cortex Framework Knowledge Catalog 同步工具 如何帮助将 Google Cloud Cortex Framework 数据产品注册并同步到 Knowledge Catalog，从而简化数据产品的发现和安全共享。

启用此集成后，您部署的 Cortex Framework 数据产品（包括其丰富的业务说明、所有权元数据以及底层物理 BigQuery 数据集和表）会自动编入目录，并在 Knowledge Catalog 中可供发现。

主要优势

将 Cortex Framework 与 Knowledge Catalog 集成可提供以下主要优势：

• 自动发现数据：用户可以直接在 Knowledge Catalog 界面中浏览和搜索标准化的企业数据产品，而无需手动输入目录。
• 丰富的业务背景信息：直接从 manifest.yaml 文件自动将显示名称、详细的业务说明和文档网址导入 Knowledge Catalog。
• 统一的资产关联：将各个一致的报告基表直接关联到其对应的 Knowledge Catalog 数据产品。这样，数据使用者就可以立即了解哪些物理数据对象为特定业务领域提供支持。
• 自动执行生命周期和偏差协调：随着企业数据模型的演变，运行同步工具会自动协调元数据和资产链接。该工具会注册新表、更新修改后的定义并移除过时的链接，同时保护不受管理的用户创建的目录商品。
• 系统管理安全性：使用专用系统标签（cortex-framework-created 和 cortex-framework-version）仅识别和管理由 Cortex Framework 创建的资源，防止意外覆盖现有客户管理的 Knowledge Catalog 资产。

集成的工作原理

Knowledge Catalog 集成由 cortex-kc-sync (tools.dataplex.kc_sync) 同步工具提供支持。执行后，同步器会执行以下多步工作流：

1. 配置和清单提取

同步器会解析全局 config/config.yaml 配置文件，以识别所有已启用的数据产品模块 (data.modules.products) 及其目标 BigQuery 数据集 (data.targets)。

对于每个已启用的模块，同步器都会从模块的 manifest.yaml 中提取描述性元数据（使用工作区模块提供程序）：

• displayName：数据产品的易读标题。
• description：模块的业务摘要。
• documentation：指向内部或外部模块文档的网址。

注意 数据产品所有权：所有权电子邮件元数据不会从 manifest.yaml 中提取。相反，它会在同步期间使用 --owner-email 命令行实参进行全局配置。

2. BigQuery 资产发现

cortex-kc-sync 不会验证静态表定义列表，而是查询 BigQuery (list_dataset_tables) 以动态发现哪些表和视图已部署在目标数据集中。

它会通过查找部署期间应用的特定跟踪标签来解析和过滤表：

• cortex-framework-namespaced-module-type 与完全限定的模块路径（例如 cortex.sap.products.sales_performance）匹配，或者
• cortex-framework-module-type 与规范模块类型名称（例如 sales_performance）匹配。

只有在 BigQuery 中带有这些标签的实体化表和视图才会编入目录，并作为数据产品下的资产进行关联。

3. 托管资源协调和加标签

同步器会与 dataplex_v1 API (DataProductClient) 通信，以协调目标 Google Cloud 位置中发现的每个数据产品：

• 创建 (NEEDS_CREATION) ：如果数据产品不存在，同步器会创建一个新的 Knowledge Catalog 数据产品，其中填充了提取的清单元数据，并关联解析后的 BigQuery 资产。它会使用两个系统标签标记资源：

  • cortex-framework-created：设置为 "true"
  • cortex-framework-version：设置为 "7-0-0"

• 不受管理的资源保护 (NOT_MANAGED) ：如果目录中已存在具有相同 ID 但缺少这些系统标签 (is_managed_data_product == False) 的 Knowledge Catalog 数据产品，同步器会跳过该数据产品，以保护用户创建的或预先存在的目录资产。

• 更新 (NEEDS_UPDATE) ：如果存在托管数据产品，并且其元数据或表组成发生更改，同步器会更新 Knowledge Catalog 数据产品定义并协调其关联的 BigQuery 资产 (BigQueryAssetLinks)。它会自动为新添加的表创建新的 DataAsset 链接，并删除过时的链接，同时保留未更改的链接。

设置和配置

本部分介绍了设置和运行 Cortex Framework 与 Knowledge Catalog 之间同步所需的前提条件、元数据配置和执行步骤。

前提条件

在运行 Knowledge Catalog 同步之前，请确保满足以下要求：

启用 Google Cloud 服务

在本部分中，我们将启用项目中的以下 Google Cloud 服务： Google Cloud

• Cloud Dataplex API (dataplex.googleapis.com)

使用 Cloud Shell 启用此 Google Cloud 服务，方法是在终端中执行以下命令：

gcloud config set project PROJECT_ID

gcloud services enable dataplex.googleapis.com \
         --project=PROJECT_ID

目标项目的角色

如需获得同步 Knowledge Catalog 所需的权限，请让您的管理员向您授予目标项目的以下 IAM 角色：

• Dataplex Editor (roles/dataplex.editor)
• Dataplex Data Product Editor (roles/dataplex.dataProductsEditor)
• Dataplex Entry Owner (roles/dataplex.entryOwner)
• BigQuery Metadata Viewer (roles/bigquery.metadataViewer)
• BigQuery Data Viewer (roles/bigquery.dataViewer)

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

此预定义角色包含同步 Knowledge Catalog 所需的 dataplex.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.delete 权限。

您也可以使用自定义角色或其他预定义角色来获取此权限。

如需向用户授予所请求的角色，您可以使用以下脚本：

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataplex.editor"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataplex.dataProductsEditor"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataplex.entryOwner"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/bigquery.metadataViewer"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/bigquery.dataViewer"

已执行的 Dataform 流水线

您必须先运行 cortex-build-and-deploy 或 cortex-deploy，如 部署指南 中所述，并执行 Dataform 流水线操作以实体化 BigQuery 表和视图，然后再尝试与 Knowledge Catalog 同步。如需了解执行转换的分步说明，请参阅部署后步骤。

注意： 如果您想将 Knowledge Catalog 与演示部署搭配使用，请按照部署配置中的说明创建配置文件：config/config.yaml。

注意： 资产限制：Dataplex 每个数据产品最多支持 100 个资产（表）。如果数据产品包含的表超过 50 个，cortex-kc-sync 将失败并显示错误。

配置数据产品元数据

您可以修改每个数据产品模块目录（例如 src/data_modules/cortex/sap/products/accounts_payable/manifest.yaml）内的 manifest.yaml 文件，自定义 Knowledge Catalog 中显示的业务元数据。

以下示例演示了如何在模块清单中定义 displayName、description 和 documentation：

displayName: "SAP Accounts Payable"
description: >
  SAP Data Product for Accounts Payable containing conformed vendor invoices, 
  payment aging schedules, and financial accounting documents.
documentation: "https://docs.cloud.google.com/cortex/docs/data-product"

category: foundational_product
type: accounts_payable
dependencies:
  sapModule:
    supportedVersions:
      - ecc
      - s4
    tables:
      ecc:
        - bsik
        - bsak
      s4:
        - acdoca
        - bseg
      common:
        - bkpf
    modulePath: cortex.sap.foundations.sap
builder: sap_product

运行同步命令

在 BigQuery 中部署和实体化数据产品后，使用 uv 运行 cortex-kc-sync CLI 工具：

uv run cortex-kc-sync --config config/config.yaml --owner-email USER_EMAIL

如需查看可用标志和实参的完整列表，请参阅 CLI KC 同步 (uv run cortex-kc-sync) 参考文档。

验证 Knowledge Catalog 同步

如需验证 Google Cloud Cortex Framework 资产与 Knowledge Catalog 之间的同步是否成功，请按照以下步骤操作：

• 在 Google Cloud 控制台中，打开 Knowledge Catalog
• 可选：在搜索对话框中，您可能需要使用 Data Products 或 Tables 等快速过滤条件。
• 在 Knowledge Catalog 主屏幕的搜索字段中，点击 Filters。
• 在打开的 Filters 视图中，从 Project 下拉列表中选择用于同步 Google Cloud Cortex Framework 数据产品的项目。
• 成功同步后，您现在可以选择或搜索 Google Cloud Cortex Framework 公开的数据资产，包括所有已发布的元数据。

自动执行工作流

在生产环境中，我们建议在 CI/CD 编排流水线或 Knowledge Catalog (Airflow) DAG 中自动运行 cortex-kc-sync，作为 Dataform 流水线成功执行后的后处理步骤：

1. 构建和部署：运行 cortex-deploy (uv run cortex-deploy --config config/config.yaml) 以将配置编译并暂存到 Dataform。
2. 执行转换：触发 Dataform 执行运行，以在 BigQuery 中实体化数据基础层和一致的报告表。
3. 目录同步：运行 cortex-kc-sync (uv run cortex-kc-sync --config config/config.yaml) 以验证表创建，并将所有更新的数据产品、说明和沿袭链接直接同步到 Knowledge Catalog。

后续步骤

• 创建自定义数据产品：如需创建新的数据产品或扩展架构，请参阅可扩展性指南：数据产品模块创建。