Knowledge Catalog の統合

このドキュメントでは、Cortex Framework が Knowledge Catalog と統合される仕組みについて説明します。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 ファイルから表示名、詳細なビジネスの説明、ドキュメント URL を Knowledge Catalog に直接自動的にインポートします。
  • アセットの統合リンク: 個々の準拠したレポート作成ベーステーブルを、対応する Knowledge Catalog データ プロダクトに直接接続します。これにより、データ利用者は、特定のビジネス ドメインを強化する物理データ オブジェクトをすぐに確認できます。
  • ライフサイクルとドリフトの自動調整: エンタープライズ データモデルが進化すると、同期ツールを実行してメタデータとアセットリンクを自動的に調整します。管理対象外のユーザー作成カタログ アイテムを保護しながら、新しいテーブルを登録し、変更された定義を更新し、不要になったリンクを削除します。
  • システム管理の安全性: 専用のシステムラベル（cortex-framework-created および cortex-framework-version）を使用して、Cortex Framework によって作成されたリソースのみを識別して管理し、既存の顧客管理の Knowledge Catalog アセットが誤って上書きされるのを防ぎます。

統合の仕組み

Google Cloud Cortex Framework ソリューションの主なコンポーネント

Knowledge Catalog の統合は、cortex-kc-sync（tools.dataplex.kc_sync）同期ツールによって実現されます。実行すると、シンクは次のマルチステップ ワークフローを実行します。

Google Cloud Cortex Framework と Knowledge Catalog の同期

1. 構成とマニフェストの抽出

シンクは、グローバル config/config.yaml 構成ファイルを解析して、有効になっているすべてのデータ プロダクト モジュール（data.modules.products）とターゲット BigQuery データセット（data.targets）を特定します。

有効になっているモジュールごとに、シンクはモジュールの manifest.yaml から説明メタデータを抽出します（ワークスペース モジュール プロバイダを使用）。

  • displayName: データ プロダクトの人が読める形式のタイトル。
  • description: モジュールのビジネス概要。
  • documentation: 内部または外部のモジュール ドキュメントを指す URL。

2. BigQuery アセットの検出

cortex-kc-sync は、テーブル定義の静的リストを確認するのではなく、BigQuery（list_dataset_tables）にクエリを実行して、ターゲット データセットにすでにデプロイされているテーブルとビューを動的に検出します。

デプロイ時に適用された特定のトラッキング ラベルを探して、テーブルを解決してフィルタします。

  • 完全修飾モジュール パス（cortex.sap.products.sales_performance など）に一致する cortex-framework-namespaced-module-type、または
  • 正規のモジュール タイプ名（sales_performance など）に一致する cortex-framework-module-type。

BigQuery でこれらのラベルが付いているマテリアライズド テーブルとビューのみがカタログ化され、データ プロダクトのアセットとしてリンクされます。

3. マネージド リソースの調整とラベル付け

シンクは dataplex_v1 API（DataProductClient）と通信して、ターゲット Google Cloud ロケーションで検出された各データ プロダクトを調整します。

  • 作成（NEEDS_CREATION）: データ プロダクトが存在しない場合、シンクは抽出されたマニフェスト メタデータが入力された新しい Knowledge Catalog データ プロダクトを作成し、解決された BigQuery アセットをリンクします。リソースに次の 2 つのシステムラベルをタグ付けします。

    • 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.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.deleteKnowledge 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 パイプラインを実行した

Knowledge Catalog との同期を試みる前に、デプロイガイドの説明に従って cortex-build-and-deploy または cortex-deploy を実行し、Dataform パイプライン アクションを実行 して BigQuery テーブルとビューをマテリアライズする必要があります。変換の実行手順については、デプロイ後の手順をご覧ください。

データ プロダクトのメタデータを構成する

各データ プロダクト モジュール ディレクトリ（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 間の同期が成功したことを確認する手順は次のとおりです。

  • コンソールで Knowledge Catalog を開きます。 Google Cloud
  • （省略可）検索ダイアログで、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 に直接同期します。

次のステップ