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 相同的 Knowledge Catalog 資料產品，但缺少這些系統標籤 (is_managed_data_product == False)，同步器會略過該產品，以保護使用者建立或預先存在的目錄資產。

• 更新 (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 編輯者 (roles/dataplex.editor)
• Dataplex 資料產品編輯器 (roles/dataplex.dataProductsEditor)
• Dataplex 項目擁有者 (roles/dataplex.entryOwner)
• BigQuery 中繼資料檢視器 (roles/bigquery.metadataViewer)
• BigQuery 資料檢視者 (roles/bigquery.dataViewer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 dataplex.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.delete 權限，可同步處理 Knowledge Catalog。

您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

如要將要求的角色授予使用者，可以使用下列指令碼：

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 同步。如需執行轉換的逐步操作說明，請參閱「部署後步驟」。

注意：如要搭配 demo-deployment 使用 Knowledge Catalog，請按照「部署設定」一文的說明，建立設定檔：config/config.yaml。

注意： 資產限制：每個資料產品最多可有 100 個資產 (資料表)。如果資料產品包含超過 50 個資料表，cortex-kc-sync 會失敗並顯示錯誤。

設定資料產品中繼資料

如要自訂 Knowledge Catalog 中顯示的業務中繼資料，請修改每個資料產品模組目錄 (例如 src/data_modules/cortex/sap/products/accounts_payable/manifest.yaml) 內的 manifest.yaml 檔案。

以下範例說明如何在模組資訊清單中定義 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 公開的資料資產，包括所有已發布的中繼資料。

自動化工作流程

在正式環境中，建議您在 Dataform 管道執行成功後，立即在 CI/CD 自動化調度管理管道或 Knowledge Catalog (Airflow) DAG 中，自動執行 cortex-kc-sync 做為後續處理步驟：

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。

後續步驟

• 建立自訂資料產品：請參閱擴充性指南：建立資料產品模組，瞭解如何建立新的資料產品或擴充結構定義。