Ressourcen mit Knowledge Catalog verwalten

In diesem Dokument wird beschrieben, wie Sie mit Knowledge Catalog nach Spanner-Ressourcen suchen und diese verwalten.

Knowledge Catalog katalogisiert Metadaten zu Spanner-Instanzen, ‑Datenbanken, ‑Tabellen, ‑Spalten und ‑Ansichten in Google Cloud, sodass KI-Agenten und Analysetools fundierten, relevanten Kontext abrufen können.

Knowledge Catalog und Spanner

Knowledge Catalog bezeichnet die Ressourcen in Spanner und in anderen Google Cloud -Diensten als Assets. In Knowledge Catalog wird jedes Spanner-Asset, z. B. eine Instanz, Datenbank, Tabelle oder Ansicht, durch einen Katalogeintrag dargestellt, in dem technische und geschäftliche Metadaten (Aspekte) zur Ressource gespeichert sind.

Sie können Knowledge Catalog in den folgenden Workflows verwenden, um Ihre Spanner-Assets zu finden und zu verstehen:

  • Analyse: Abhängigkeiten zwischen Daten-Assets verstehen und die Eignung von Assets für bestimmte Anwendungsfälle bewerten.
  • Änderungsmanagement: Verfolgen Sie strukturelle Änderungen in Datenbanken.
  • Datenbewegung: Ursprünge und Ziele von Pipelines verfolgen.
  • Schemaentwicklung: Tabellen- und Spaltendefinitionen im Zeitverlauf überwachen.
  • Kontextbezogene KI-Fundierung: KI-Agenten ein Schema und einen Geschäftskontext bereitstellen.

Knowledge Catalog katalogisiert automatisch die folgenden Metadaten für Spanner-Ressourcen:

  • Ressourcenname und vollständig qualifizierter Name (FQN)
  • Standort (Region)
  • Zeitstempel der Erstellung und der letzten Änderung
  • Schemadefinitionen (für Tabellen und Ansichten)
  • Spaltendatentypen, Null-Zulässigkeit und Primärschlüsselindikatoren
  • Beschreibungen und Nutzerlabels

Die Metadatenerkennung von Knowledge Catalog ist ein automatisierter Prozess, bei dem verbundene Datenquellen wie Spanner gescannt werden, um Daten-Assets wie Tabellen, Ansichten und Datenbanken zu identifizieren. Anschließend extrahiert Knowledge Catalog technische Metadaten aus den Assets, z. B. Schemas, Beschreibungen und Speicherorte.

Spanner synchronisiert Metadaten in regelmäßigen Abständen mit Knowledge Catalog, in der Regel alle sechs Stunden. Es kann also etwa sechs Stunden dauern, bis Metadatenänderungen an Spanner-Assets übernommen werden.

Hinweis

Führen Sie die folgenden Einrichtungsschritte aus, bevor Sie Knowledge Catalog mit Spanner verwenden:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Aktivieren Sie die Dataplex API für das Projekt.

    Dataplex API aktivieren

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Verwalten von Spanner-Assets in Knowledge Catalog benötigen:

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

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Verwalten von Spanner-Assets in Knowledge Catalog erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Spanner-Assets in Knowledge Catalog zu verwalten:

  • Aspekttyp erstellen: dataplex.aspectTypes.create
  • Suchen Sie nach Spanner-Instanzen:
    • dataplex.projects.search
    • spanner.instances.get
  • Nach Spanner-Datenbanken, -Tabellen und -Ansichten suchen:
    • dataplex.projects.search
    • spanner.databases.get
  • Aspekte von Spanner-Instanzen ansehen:
    • dataplex.aspectTypes.get
    • spanner.instances.get
  • Aspekte von Spanner-Datenbanken, -Tabellen und -Ansichten ansehen:
    • dataplex.aspectTypes.get
    • spanner.databases.get
  • Aspekt mithilfe eines Aspekttyps an eine Spanner-Ressource anhängen:
    • dataplex.aspectTypes.use
    • dataplex.entries.update

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

Knowledge Catalog unterstützt die semantische Suche, mit der Sie Ressourcen in natürlicher Sprache finden können. Eine komplexe Suchsyntax ist nicht erforderlich. Geben Sie beispielsweise eine Abfrage wie List all Spanner tables related to sales ein.

Wenn Sie möchten, können Sie nach Ressourcen mit bestimmten Suchbegriffen, Filtern und einer prädikatbasierten Suchsyntax suchen.

So suchen Sie in Knowledge Catalog nach Spanner-Assets:

  1. Rufen Sie in der Google Cloud Console die Seite Suchen im Knowledge Catalog auf:

    Zur Suche

  2. Wählen Sie im Bereich Filter unter Systeme die Option Spanner aus.

    Knowledge Catalog zeigt alle Spanner-Assets an, auf die Sie in Ihren Google Cloud -Projekten Zugriff haben.

  3. Geben Sie im Suchfeld eine Abfrage in natürlicher Sprache ein, z. B. List all Spanner tables related to sales.

  4. Optional: Verwenden Sie die gefilterte Suche auf der Seite Suchen. Wählen Sie Filter unter Typ, Projekte, Standorte und Aspekttypen aus.

  5. Optional: Fügen Sie im Suchfeld einen Suchparameter nach system=spanner an. Trennen Sie mehrere Parameter durch Leerzeichen oder verwenden Sie Klammern und die logischen Operatoren AND, OR und NOT.

    Wenn Sie beispielsweise nur Datenbanken anzeigen möchten, geben Sie die folgende Abfrage ein:

    system=spanner type=database

    Sie können auch type=service verwenden, um nach Instanzen zu suchen, oder instance_config=CONFIGURATION_NAME, um nach einer Instanzkonfiguration zu suchen.

    Weitere Abfrageoptionen finden Sie unter Suchsyntax für Knowledge Catalog.

  6. Klicken Sie in der Liste der Suchergebnisse auf den Namen eines Assets, um die Detailseite des Eintrags in Knowledge Catalog zu öffnen.

Auf der Detailseite des Eintrags können Sie Folgendes tun:

  • Wenn Sie Asset-Zusammenfassungen aufrufen und eine Beschreibung hinzufügen möchten, rufen Sie den Tab Details auf und klicken Sie dann im Abschnitt Übersicht auf Hinzufügen.
  • Wenn Sie geschäftliche und operative Metadaten ansehen oder anhängen möchten, rufen Sie den Tab Details auf und klicken Sie im Abschnitt Aspekte neben Optionale Aspekte auf Hinzufügen.
  • Wenn Sie die Mitgliedsdatenbanken für eine Instanz aufrufen möchten, klicken Sie auf den Tab Eintragsliste und dann auf Alle untergeordneten Einträge in der Suche anzeigen.
  • Wenn Sie die Datentypen, Schlüssel und Definitionen der Spalten einer Tabelle prüfen möchten, klicken Sie auf den Tab Schema.

Anwendungsfall: Von der Instanz zu den Spalten aufschlüsseln

In diesem Anwendungsfall suchen Sie nach einer Spanner-Instanz und rufen dann eine der in der Instanz aufgeführten Datenbanken auf, um die zugehörigen Tabellen und Spalten anzusehen.

  1. Rufen Sie in der Google Cloud Console die Seite Suchen im Knowledge Catalog auf:

    Zur Suche

  2. Wählen Sie im Bereich Filter unter Systeme die Option Spanner aus.

  3. Wenn Sie alle Spanner-Instanzen in Knowledge Catalog aufrufen möchten, geben Sie im Suchfeld eine Abfrage in natürlicher Sprache ein, z. B. List all Spanner instances, und drücken Sie die Enter.

  4. Wählen Sie einen Instanznamen aus.

  5. Klicken Sie auf der Seite Spanner-Details auf den Tab Eintragsliste und dann auf Alle untergeordneten Einträge in der Suche anzeigen.

    Knowledge Catalog zeigt die Datenbanken in der Instanz an. Wenn der Tab Eintragsliste nicht angezeigt wird, kehren Sie zur Seite Suche zurück und wählen Sie eine andere Instanz aus.

  6. Wählen Sie einen Datenbanknamen aus. Klicken Sie auf der Seite Spanner-Datenbankdetails auf den Tab Eintragsliste und dann auf Alle untergeordneten Einträge in der Suche anzeigen.

    Knowledge Catalog zeigt die Tabellen in der Datenbank an.

  7. Wählen Sie einen Tabellennamen aus und klicken Sie dann auf der Seite Spanner-Tabellendetails auf Schema, um die Tabellenspalten aufzurufen.

  8. Optional: Wenn Sie einer Spalte einen Aspekt hinzufügen möchten, wählen Sie die Spalte aus und klicken Sie auf Aspekt hinzufügen.

Metadaten mit Aspekten anreichern

Wenn Sie Metadaten anreichern und nach Assets anhand eines benutzerdefinierten Kontexts suchen möchten, können Sie Aspekte basierend auf Aspekttypen (wiederverwendbare Vorlagen) erstellen und an Ihre Spanner-Assets anhängen. Mit Aspekten können Sie strukturierte geschäftliche Metadaten wie Dateneigentum, Governance-Klassifizierungen oder Aufbewahrungsrichtlinien hinzufügen.

Sie können beispielsweise den folgenden Aspekt an eine Spalte anhängen, die eine Sozialversicherungsnummer enthält, also eine personenidentifizierbare Information:

pii:true
pii_type:SSN

So hängen Sie einen Aspekt an ein Spanner-Asset an:

  1. Klicken Sie auf der Seite Suchen im Knowledge Catalog auf das Asset, das Sie anreichern möchten.
  2. Wechseln Sie auf der Seite mit den Eintragsdetails auf dem Tab Details zum Abschnitt Aspekte.
  3. Klicken Sie neben Optionale Aspekte auf Hinzufügen.
  4. Suchen Sie nach dem Aspekttyp, den Sie hinzufügen möchten, und wählen Sie ihn aus, z. B. ein benutzerdefiniertes Schema für Data Governance oder Datenschutz.
  5. Geben Sie im Fenster Aspekt hinzufügen die erforderlichen Aspektfelder an.
  6. Klicken Sie auf Speichern.

Eine ausführliche Anleitung zum Erstellen von Aspekttypen und Verwalten von Aspekten finden Sie unter Aspekte verwalten und Metadaten anreichern.

Aspekte exportieren und importieren

Wenn Sie eine Cloud Spanner-Instanz in eine andere Instanzkonfiguration verschieben, werden die Einträge und Aspekte, die mit der Quellinstanzkonfiguration in Knowledge Catalog verknüpft sind, gelöscht. Wenn Sie Ihre benutzerdefinierten Aspekte beibehalten möchten, müssen Sie Folgendes tun:

  1. Exportieren Sie die Aspekte, die den Einträgen in der Konfiguration der Quellinstanz zugeordnet sind.
  2. Verschieben Sie die Instanz in die Zielinstanzkonfiguration.
  3. Importieren Sie die Aspekte in die Konfiguration der Zielinstanz.

Aspekte aus der Quellinstanzkonfiguration exportieren

Bevor Sie Ihre Instanz verschieben, rufen Sie die Aspekte für Ihre Spanner-Einträge in der Quellinstanzkonfiguration mithilfe der Google Cloud CLI, der Dataplex API oder eines Metadatenexportjobs ab:

gcloud

Verwenden Sie den Befehl gcloud dataplex entries lookup, um die Aspekte für einen Spanner-Eintrag in der Systemeintragsgruppe @spanner abzurufen:

gcloud dataplex entries lookup SOURCE_ENTRY_ID \
  --entry-group=@spanner \
  --location=LOCATION \
  --project=PROJECT_ID \
  --view=all

Ersetzen Sie Folgendes:

  • SOURCE_ENTRY_ID: die Eintrags-ID der Spanner-Ressource in der Quellinstanzkonfiguration.

    Eintrags-ID finden

    Verwenden Sie den Befehl gcloud dataplex entries search, um den Eintragsnamen zu finden oder einen voll qualifizierten Namen (FQN) wie spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID zu übersetzen.

  • LOCATION: die Region der Cloud Spanner-Instanzkonfiguration, z. B. us-central1.

  • PROJECT_ID: die ID des Google Cloud -Projekts, das die Spanner-Instanz enthält.

REST API

Wenn Sie die Aspekte für einen Spanner-Eintrag in der Systemeintragsgruppe @spanner abrufen möchten, senden Sie eine GET-Anfrage an den Endpunkt projects.locations.lookupEntry.

curl -X GET \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntry?entry=projects/PROJECT_ID/locations/LOCATION/entryGroups/@spanner/entries/SOURCE_ENTRY_ID&view=ALL"

Ersetzen Sie Folgendes:

  • ACCESS_TOKEN: das Zugriffstoken, das Ihre Anwendung zur Authentifizierung beim Dienst verwendet. Verwenden Sie zum Beispiel $(gcloud auth print-access-token).

  • PROJECT_ID: die ID des Google Cloud -Projekts, das die Cloud Spanner-Instanz enthält.

  • LOCATION: die Region der Spanner-Instanzkonfiguration, z. B. us-central1.

  • SOURCE_ENTRY_ID: die Eintrags-ID der Spanner-Ressource in der Quellinstanzkonfiguration.

    Eintrags-ID finden

    Verwenden Sie den Befehl gcloud dataplex entries search, um den Eintragsnamen zu finden oder einen voll qualifizierten Namen (FQN) wie spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID zu übersetzen.

Export job

Wenn Sie Metadaten für mehrere Einträge in einem Batch nach Cloud Storage exportieren möchten, führen Sie einen Metadatenexportjob aus.

Instanz in die Zielinstanzkonfiguration verschieben

Bevor Sie Aspekte in die Zielinstanzkonfiguration importieren, müssen Sie Folgendes tun:

  1. Verschieben Sie die Spanner-Instanz in die Zielinstanzkonfiguration. Warten Sie, bis die Spanner-Metadaten für die verschobene Instanz mit Knowledge Catalog synchronisiert wurden. Das kann etwa sechs Stunden dauern.

  2. So prüfen Sie, ob die Synchronisierung abgeschlossen ist: Suchen Sie mit einer der folgenden Methoden nach der verschobenen Instanz:

    • Geben Sie auf der Seite Suchen im Knowledge Catalog die folgende Abfrage ein:

      system=spanner instance_config=DESTINATION_CONFIG_NAME

    • Zum Abrufen der aktuellen Richtlinie führen Sie den Befehl gcloud dataplex entries search aus:

      gcloud dataplex entries search "fqn=spanner:PROJECT_ID.DESTINATION_CONFIG_ID.INSTANCE_ID" \
    --project=PROJECT_ID

    Wenn der Befehl den Eintrag für die Zielinstanzkonfiguration zurückgibt, ist die Synchronisierung abgeschlossen.

Aspekte in die Zielinstanzkonfiguration importieren

Nachdem die Metadaten synchronisiert wurden, hängen Sie die kopierten Aspekte an die Einträge in der Zielinstanzkonfiguration an:

gcloud

Verwenden Sie den Befehl gcloud dataplex entries update-aspects, um die kopierten Aspekte an den Eintrag in der Konfiguration der Zielinstanz anzuhängen:

gcloud dataplex entries update-aspects DESTINATION_ENTRY_ID \
  --entry-group=@spanner \
  --location=DESTINATION_LOCATION \
  --project=PROJECT_ID \
  --aspects=ASPECTS_FILE

Ersetzen Sie Folgendes:

  • DESTINATION_ENTRY_ID: die Eintrags-ID der verschobenen Spanner-Ressource in der Zielinstanzkonfiguration.

  • DESTINATION_LOCATION: die Region der Ziel-Spanner-Instanzkonfiguration, z. B. us-central1.

  • PROJECT_ID: die ID des Google Cloud -Projekts, das die Spanner-Instanz enthält.

  • ASPECTS_FILE: der Pfad zu einer JSON- oder YAML-Datei, die die hinzuzufügenden oder zu aktualisierenden Aspekte enthält.

REST API

Verwenden Sie die REST API-Methode projects.locations.entryGroups.entries.patch, um die exportierten Aspekte an den Eintrag in der Zielinstanzkonfiguration anzuhängen, wie im folgenden Beispiel gezeigt:

curl -X PATCH \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"aspects":{"ASPECT_KEY":{"data":{"FIELD_NAME":"FIELD_VALUE"}}}}' \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/DESTINATION_LOCATION/entryGroups/@spanner/entries/DESTINATION_ENTRY_ID?updateMask=aspects"

Ersetzen Sie Folgendes:

  • ACCESS_TOKEN: das Zugriffstoken, das Ihre Anwendung zur Authentifizierung beim Dienst verwendet. Verwenden Sie zum Beispiel $(gcloud auth print-access-token).

  • ASPECT_KEY: der Aspektschlüssel im Format PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID für einen Aspekt auf Eintragsebene oder PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID@Schema.COLUMN_NAME für einen Aspekt auf Spaltenebene.

  • FIELD_NAME und FIELD_VALUE: Der Feldname und der Wert, die durch Ihren Aspekttyp definiert sind.

  • PROJECT_ID: die ID des Projekts, das die Cloud Spanner-Instanz enthält.

  • DESTINATION_LOCATION: die Region der Ziel-Spanner-Instanzkonfiguration, z. B. us-central1.

  • DESTINATION_ENTRY_ID: die Eintrags-ID der verschobenen Spanner-Ressource in der Zielinstanzkonfiguration.

Importjob

Wenn Sie Aspekte für mehrere Einträge im Batch aus Cloud Storage importieren möchten, führen Sie einen Metadatenimportjob aus.

Nächste Schritte