Knowledge Catalog-Einbindung

In diesem Dokument wird erläutert, wie Cortex Framework in Knowledge Catalog eingebunden wird. Knowledge Catalog dient als Governance-Ebene für Unternehmensdatenprodukte in Ihrer Organisation. Außerdem wird erläutert, wie Sie mit dem Google Cloud Cortex Framework Knowledge Catalog-Synchronisierungstool Google Cloud Cortex Framework-Datenprodukte in Knowledge Catalog registrieren und synchronisieren können, um die Auffindbarkeit und sichere Freigabe zu vereinfachen.

Wenn Sie diese Einbindung aktivieren, werden Ihre bereitgestellten Cortex Framework-Datenprodukte, einschließlich der angereicherten Geschäftsdatenbeschreibungen, Metadaten zur Inhaberschaft und der zugrunde liegenden physischen BigQuery-Datasets und ‑Tabellen, automatisch katalogisiert und in Knowledge Catalog auffindbar gemacht.

Hauptvorteile

Die Einbindung von Cortex Framework in Knowledge Catalog bietet folgende Hauptvorteile:

• Automatisierte Auffindbarkeit von Daten: Nutzer können direkt über die Knowledge Catalog-Benutzeroberfläche nach standardisierten Unternehmensdatenprodukten suchen und diese durchsuchen, ohne dass ein manueller Katalogeintrag erforderlich ist.
• Angereicherter geschäftlicher Kontext: Importiert Anzeigenamen, detaillierte Geschäftsdatenbeschreibungen und Dokumentations-URLs automatisch aus manifest.yaml Dateien in Knowledge Catalog.
• Einheitliche Asset-Verknüpfung: Verknüpft einzelne konforme Berichtsgrundtabellen direkt mit den entsprechenden Knowledge Catalog-Datenprodukten. So können Datennutzer sofort sehen, welche physischen Datenobjekte bestimmte Geschäftsbereiche unterstützen.
• Automatisierte Lebenszyklus- und Abweichungsabstimmung: Wenn sich Ihre Unternehmensdatenmodelle weiterentwickeln, werden Metadaten und Asset-Verknüpfungen automatisch mit dem Synchronisierungstool abgestimmt. Es registriert neue Tabellen, aktualisiert geänderte Definitionen und entfernt veraltete Verknüpfungen, während nicht verwaltete, von Nutzern erstellte Katalogelemente geschützt werden.
• Sicherheit der Systemverwaltung: Verwendet spezielle Systemlabels (cortex-framework-created und cortex-framework-version), um nur die von Cortex Framework erstellten Ressourcen zu identifizieren und zu verwalten. So wird verhindert, dass vorhandene vom Kunden verwaltete Knowledge Catalog-Assets versehentlich überschrieben werden.

Funktionsweise der Einbindung

Die Knowledge Catalog-Einbindung wird durch das Synchronisierungstool cortex-kc-sync (tools.dataplex.kc_sync) ermöglicht. Bei der Ausführung führt der Syncer den folgenden mehrstufigen Workflow aus:

1. Konfiguration und Manifestextraktion

Der Syncer parst die globale Konfigurationsdatei config/config.yaml, um alle aktivierten Datenproduktmodule (data.modules.products) und ihre BigQuery-Zieldatasets (data.targets) zu identifizieren.

Für jedes aktivierte Modul extrahiert der Syncer beschreibende Metadaten aus der manifest.yaml-Datei des Moduls (mit dem Workspace-Modul-Provider):

• displayName: Der für Nutzer lesbare Titel des Datenprodukts.
• description: Die geschäftliche Zusammenfassung des Moduls.
• documentation: URL, die auf die interne oder externe Moduldokumentation verweist.

Hinweis: Inhaberschaft von Datenprodukten: Metadaten zur E-Mail-Adresse des Inhabers werden nicht aus manifest.yaml extrahiert. Stattdessen wird sie während der Synchronisierung global mit dem Befehlszeilenargument --owner-email konfiguriert.

2. BigQuery-Asset-Erkennung

Anstatt eine statische Liste von Tabellendefinitionen zu überprüfen, fragt cortex-kc-sync BigQuery (list_dataset_tables) ab, um dynamisch zu ermitteln, welche Tabellen und Ansichten bereits in Ihrem Zieldataset bereitgestellt wurden.

Tabellen werden anhand bestimmter Tracking-Labels aufgelöst und gefiltert, die während der Bereitstellung angewendet wurden:

• cortex-framework-namespaced-module-type, das mit dem vollständig qualifizierten Modulpfad übereinstimmt (z.B. cortex.sap.products.sales_performance) oder
• cortex-framework-module-type, das mit dem kanonischen Namen des Modultyps übereinstimmt (z.B. sales_performance).

Nur die materialisierten Tabellen und Ansichten, die diese Labels in BigQuery enthalten, werden katalogisiert und als Assets unter dem Datenprodukt verknüpft.

3. Abstimmung und Kennzeichnung verwalteter Ressourcen

Der Syncer kommuniziert mit der dataplex_v1 API (DataProductClient), um jedes erkannte Datenprodukt am Ziel Google Cloud ort abzustimmen:

• Erstellung (NEEDS_CREATION): Wenn das Datenprodukt nicht vorhanden ist, erstellt der Syncer ein neues Knowledge Catalog-Datenprodukt, das mit den extrahierten Manifestmetadaten gefüllt ist, und verknüpft die aufgelösten BigQuery-Assets. Die Ressource wird mit zwei Systemlabels getaggt:

  • cortex-framework-created: auf "true" gesetzt
  • cortex-framework-version: auf "7-0-0" gesetzt

• Schutz nicht verwalteter Ressourcen (NOT_MANAGED): Wenn bereits ein Knowledge Catalog-Datenprodukt mit derselben ID im Katalog vorhanden ist, aber diese Systemlabels fehlen (is_managed_data_product == False), wird es vom Syncer übersprungen, um vom Nutzer erstellte oder bereits vorhandene Katalog-Assets zu schützen.

• Aktualisierungen (NEEDS_UPDATE): Wenn ein verwaltetes Datenprodukt vorhanden ist und Änderungen an den Metadaten oder der Tabellenzusammensetzung vorgenommen wurden, aktualisiert der Syncer die Knowledge Catalog-Datenproduktdefinition und stimmt die verknüpften BigQuery-Assets (BigQueryAssetLinks) ab. Für neu hinzugefügte Tabellen werden automatisch neue DataAsset-Verknüpfungen erstellt und veraltete Verknüpfungen gelöscht, während unveränderte Verknüpfungen beibehalten werden.

Einrichtung und Konfiguration

In diesem Abschnitt werden die Voraussetzungen, die Metadatenkonfiguration und die Ausführungsschritte beschrieben, die zum Einrichten und Ausführen der Synchronisierung zwischen Cortex Framework und Knowledge Catalog erforderlich sind.

Vorbereitung

Bevor Sie die Knowledge Catalog-Synchronisierung ausführen, müssen Sie die folgenden Voraussetzungen erfüllen:

Dienste aktivieren Google Cloud

In diesem Abschnitt aktivieren wir die folgenden Google Cloud Dienste in Ihrem Google Cloud Projekt:

• Cloud Dataplex API (dataplex.googleapis.com)

Aktivieren Sie diesen Google Cloud Dienst mit Cloud Shell, indem Sie den folgenden Befehl in Ihrem Terminal ausführen:

gcloud config set project PROJECT_ID

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

Rollen für das Zielprojekt

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Zielprojekt zuzuweisen, um die Berechtigung zu erhalten, die Sie zum Synchronisieren von Knowledge Catalog benötigen:

• Dataplex-Bearbeiter (roles/dataplex.editor)
• Dataplex-Datenprodukteditor (roles/dataplex.dataProductsEditor)
• Dataplex-Eintragsinhaber (roles/dataplex.entryOwner)
• BigQuery Metadata Viewer (roles/bigquery.metadataViewer)
• BigQuery-Datenbetrachter (roles/bigquery.dataViewer)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die dataplex.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.delete Berechtigung, die zum Synchronisieren von Knowledge Catalog erforderlich ist.

Sie können diese Berechtigung auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Mit dem folgenden Skript können Sie einem Nutzer die angeforderten Rollen zuweisen:

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"

Ausgeführte Dataform-Pipeline

Sie müssen zuerst cortex-build-and-deploy oder cortex-deploy wie im Bereitstellungsleitfaden beschrieben ausführen und Ihre Dataform-Pipelineaktionen ausführen , um die BigQuery-Tabellen und ‑Ansichten zu materialisieren, bevor Sie versuchen, sie mit Knowledge Catalog zu synchronisieren. Eine detaillierte Anleitung zum Ausführen von Transformationen finden Sie unter Schritte nach der Bereitstellung.

Hinweis: Wenn Sie Knowledge Catalog mit der Demobereitstellung verwenden möchten, erstellen Sie die Konfigurationsdatei config/config.yaml wie unter Bereitstellungskonfiguration beschrieben.

Hinweis: Asset-Limits: Dataplex unterstützt maximal 100 Assets (Tabellen) pro Datenprodukt. Wenn ein Datenprodukt mehr als 50 Tabellen enthält, schlägt cortex-kc-sync mit einem Fehler fehl.

Metadaten für Datenprodukte konfigurieren

Sie können die in Knowledge Catalog angezeigten Geschäftsmetadaten anpassen, indem Sie die Datei manifest.yaml ändern, die sich in jedem Datenproduktmodulverzeichnis befindet (z. B. src/data_modules/cortex/sap/products/accounts_payable/manifest.yaml).

Das folgende Beispiel zeigt, wie Sie displayName, description und documentation in einem Modulmanifest definieren:

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

Synchronisierungsbefehl ausführen

Nachdem Ihre Datenprodukte in BigQuery bereitgestellt und materialisiert wurden, führen Sie das cortex-kc-sync-CLI-Tool mit uv aus:

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

Eine vollständige Liste der verfügbaren Flags und Argumente finden Sie in der CLI-Referenz zur Knowledge Catalog-Synchronisierung (uv run cortex-kc-sync).

Knowledge Catalog-Synchronisierung überprüfen

So überprüfen Sie, ob die Synchronisierung zwischen Google Cloud Cortex Framework-Assets und Knowledge Catalog erfolgreich war:

• Öffnen Sie in der Google Cloud Console Knowledge Catalog.
• Optional: Im Suchdialog können Sie einen der Schnellfilter wie Data Products oder Tables verwenden.
• Klicken Sie im Suchfeld des Hauptbildschirms von Knowledge Catalog auf Filters.
• Wählen Sie in der Ansicht Filters im Drop-down-Menü Project das Projekt aus, mit dem Sie die Google Cloud Cortex Framework-Datenprodukte synchronisieren.
• Nach einer erfolgreichen Synchronisierung können Sie jetzt ein von Google Cloud Cortex Framework bereitgestelltes Daten-Asset auswählen oder danach suchen, einschließlich aller veröffentlichten Metadaten.

Workflow automatisieren

In Produktionsumgebungen empfehlen wir, cortex-kc-sync automatisch als Nachbearbeitungsschritt in Ihrer CI/CD-Orchestrierungspipeline oder im Knowledge Catalog-DAG (Airflow) auszuführen, unmittelbar nach der erfolgreichen Ausführung der Dataform-Pipeline:

1. Erstellen und bereitstellen: Führen Sie cortex-deploy (uv run cortex-deploy --config config/config.yaml) aus, um Konfigurationen zu kompilieren und für Dataform bereitzustellen.
2. Transformationen ausführen: Lösen Sie Dataform-Ausführungen aus, um Data Foundation-Ebenen und konforme Berichtstabellen in BigQuery zu materialisieren.
3. Katalogsynchronisierung: Führen Sie cortex-kc-sync (uv run cortex-kc-sync --config config/config.yaml) aus, um die Tabellenerstellung zu überprüfen und alle aktualisierten Datenprodukte, Beschreibungen und Lineage-Verknüpfungen direkt in Knowledge Catalog zu synchronisieren.

Nächste Schritte

• Benutzerdefinierte Datenprodukte erstellen: Im Leitfaden zur Erweiterbarkeit: Datenproduktmodul erstellen erfahren Sie, wie Sie neue Datenprodukte erstellen oder Schemas erweitern.