Gestisci le risorse utilizzando Knowledge Catalog

Questo documento spiega come cercare e gestire le risorse Spanner utilizzando Knowledge Catalog.

Knowledge Catalog cataloga i metadati relativi a istanze, database, tabelle, colonne e visualizzazioni Spanner in Google Cloud, consentendo agli agenti AI e agli strumenti di analisi di recuperare un contesto pertinente e fondato.

Informazioni su Knowledge Catalog e Spanner

Knowledge Catalog fa riferimento alle risorse in Spanner e in altri servizi Google Cloud come asset. In Knowledge Catalog, ogni asset Spanner, ad esempio un'istanza, un database, una tabella o una vista, è rappresentato da una voce del catalogo che archivia i metadati tecnici e aziendali (aspetti) relativi alla risorsa.

Puoi utilizzare Knowledge Catalog nei seguenti flussi di lavoro per scoprire e comprendere i tuoi asset Spanner:

  • Analisi: comprendi le dipendenze tra gli asset di dati e valuta l'idoneità degli asset per casi d'uso specifici.
  • Gestione delle modifiche: monitora le modifiche strutturali nei database.
  • Spostamento dei dati: traccia le origini e le destinazioni delle pipeline.
  • Evoluzione dello schema: monitora le definizioni di tabelle e colonne nel tempo.
  • Grounding dell'AI contestuale: fornisci uno schema e un contesto aziendale agli agenti AI.

Knowledge Catalog cataloga automaticamente i seguenti metadati per le risorse Spanner:

  • Nome della risorsa e nome completo (FQN)
  • Località (regione)
  • Timestamp di creazione e dell'ultima modifica
  • Definizioni di schema (per tabelle e visualizzazioni)
  • Tipi di dati delle colonne, supporto di valori null e indicatori della chiave primaria
  • Descrizioni ed etichette utente

Il rilevamento dei metadati di Knowledge Catalog è un processo automatizzato che analizza le origini dati connesse, come Spanner, per identificare gli asset di dati come tabelle, viste e database. Knowledge Catalog estrae quindi i metadati tecnici dagli asset, come schemi, descrizioni e posizioni.

Spanner sincronizza i metadati con Knowledge Catalog a intervalli regolari, in genere ogni sei ore, pertanto la propagazione delle modifiche ai metadati apportate agli asset Spanner può richiedere circa sei ore.

Prima di iniziare

Prima di utilizzare Knowledge Catalog con Spanner, completa le seguenti attività di configurazione:

  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. Abilita l'API Dataplex per il progetto.

    Abilita l'API Dataplex

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire gli asset Spanner in Knowledge Catalog, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per gestire gli asset Spanner in Knowledge Catalog. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per gestire gli asset Spanner in Knowledge Catalog sono necessarie le seguenti autorizzazioni:

  • Crea un tipo di aspetto: dataplex.aspectTypes.create
  • Cerca istanze Spanner:
    • dataplex.projects.search
    • spanner.instances.get
  • Cerca database, tabelle e viste Spanner:
    • dataplex.projects.search
    • spanner.databases.get
  • Visualizza gli aspetti sulle istanze Spanner:
    • dataplex.aspectTypes.get
    • spanner.instances.get
  • Visualizza gli aspetti su database, tabelle e viste Spanner:
    • dataplex.aspectTypes.get
    • spanner.databases.get
  • Collega un aspetto a una risorsa Spanner utilizzando un tipo di aspetto:
    • dataplex.aspectTypes.use
    • dataplex.entries.update

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Knowledge Catalog supporta la ricerca semantica, che ti aiuta a trovare le risorse utilizzando un linguaggio naturale, eliminando la necessità di una sintassi di ricerca complessa. Ad esempio, inserisci una query come List all Spanner tables related to sales.

Se preferisci, puoi cercare le risorse utilizzando parole chiave specifiche, filtri e una sintassi di ricerca basata su predicati.

Per cercare asset Spanner in Knowledge Catalog, segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Ricerca di Knowledge Catalog:

    Vai a Cerca

  2. Nel riquadro Filtri, in Sistemi, seleziona Spanner.

    Knowledge Catalog mostra tutti gli asset Spanner a cui hai accesso nei tuoi progetti Google Cloud .

  3. Utilizza il campo di ricerca per inserire una query in linguaggio naturale, ad esempio List all Spanner tables related to sales.

  4. (Facoltativo) Utilizza la ricerca con filtri nella pagina Ricerca. Seleziona i filtri in Tipo, Progetti, Località e Tipi di aspetto.

  5. (Facoltativo) Nel campo di ricerca, aggiungi un parametro di ricerca dopo system=spanner. Separa più parametri con spazi o utilizza le parentesi e gli operatori logici AND, OR e NOT.

    Ad esempio, per visualizzare solo i database, inserisci la seguente query:

    system=spanner type=database

    Puoi anche utilizzare type=service per cercare istanze o instance_config=CONFIGURATION_NAME per cercare una configurazione di istanza.

    Per altre opzioni di query, consulta Sintassi di ricerca per Knowledge Catalog.

  6. Nell'elenco dei risultati di ricerca, fai clic sul nome di un asset per aprire la relativa pagina dei dettagli della voce in Knowledge Catalog.

Nella pagina dei dettagli della voce, puoi eseguire le seguenti operazioni:

  • Per visualizzare i riepiloghi degli asset e aggiungere una descrizione, vai alla scheda Dettagli, poi nella sezione Panoramica, fai clic su Aggiungi.
  • Per visualizzare o allegare metadati aziendali e operativi, vai alla scheda Dettagli e poi, nella sezione Aspetti, fai clic su Aggiungi accanto ad Aspetti facoltativi.
  • Per visualizzare i database dei membri di un'istanza, fai clic sulla scheda Elenco voci, quindi su Mostra tutte le voci secondarie nella ricerca.
  • Per esaminare i tipi di dati, le chiavi e le definizioni delle colonne di una tabella, fai clic sulla scheda Schema.

Caso d'uso: eseguire il drill down dall'istanza alle colonne

In questo caso d'uso, cerchi un'istanza Spanner e poi esegui il drill down in uno dei database elencati nell'istanza per visualizzarne le tabelle e le colonne.

  1. Nella console Google Cloud , vai alla pagina Ricerca di Knowledge Catalog:

    Vai a Cerca

  2. Nel riquadro Filtri, in Sistemi, seleziona Spanner.

  3. Per visualizzare tutte le istanze Spanner in Knowledge Catalog, utilizza il campo di ricerca per inserire una query in linguaggio naturale, ad esempio List all Spanner instances, e premi Enter.

  4. Seleziona un nome istanza.

  5. Nella pagina Dettagli Spanner, fai clic sulla scheda Elenco voci, quindi su Mostra tutte le voci secondarie nella ricerca.

    Knowledge Catalog mostra i database nell'istanza. Se non è presente la scheda Elenco voci, torna alla pagina Ricerca e scegli un'altra istanza.

  6. Seleziona un nome per il database. Nella pagina Dettagli del database Spanner, fai clic sulla scheda Elenco voci, quindi su Mostra tutte le voci secondarie nella ricerca.

    Knowledge Catalog visualizza le tabelle nel database.

  7. Seleziona il nome di una tabella, quindi nella pagina Dettagli tabella Spanner, fai clic su Schema per visualizzare le colonne della tabella.

  8. (Facoltativo) Per aggiungere un aspetto a una colonna, seleziona la colonna e fai clic su Aggiungi aspetto.

Arricchisci i metadati con gli aspetti

Per arricchire i metadati e cercare gli asset in base al contesto personalizzato, puoi creare aspetti basati su tipi di aspetti (modelli riutilizzabili) e collegarli agli asset Spanner. Gli aspetti ti consentono di aggiungere metadati aziendali strutturati, come la proprietà dei dati, le classificazioni di governance o le policy di conservazione.

Ad esempio, puoi allegare il seguente aspetto a una colonna che contiene un numero di previdenza sociale, ovvero informazioni che consentono l'identificazione personale (PII):

pii:true
pii_type:SSN

Per collegare un aspetto a un asset Spanner, segui questi passaggi:

  1. Nella pagina Ricerca del Knowledge Catalog, fai clic sull'asset che vuoi arricchire.
  2. Nella pagina dei dettagli della voce, nella scheda Dettagli, vai alla sezione Aspetti.
  3. Accanto ad Aspetti facoltativi, fai clic su Aggiungi.
  4. Cerca e seleziona il tipo di aspetto che vuoi aggiungere, ad esempio uno schema personalizzato per la governance dei dati o la privacy.
  5. Nella finestra Aggiungi aspetto, specifica i campi obbligatori dell'aspetto.
  6. Fai clic su Salva.

Per istruzioni dettagliate sulla creazione di tipi di aspetti e sulla gestione degli aspetti, consulta Gestisci gli aspetti e arricchisci i metadati.

Esporta e importa gli aspetti

Quando sposti un'istanza Spanner in una configurazione dell'istanza diversa, il processo elimina le voci e gli aspetti associati alla configurazione dell'istanza di origine in Knowledge Catalog. Per conservare gli aspetti personalizzati, devi:

  1. Esporta gli aspetti associati alle voci nella configurazione dell'istanza di origine.
  2. Sposta l'istanza nella configurazione dell'istanza di destinazione.
  3. Importa gli aspetti nella configurazione dell'istanza di destinazione.

Esporta gli aspetti dalla configurazione dell'istanza di origine

Prima di spostare l'istanza, recupera gli aspetti delle voci Spanner nella configurazione dell'istanza di origine utilizzando Google Cloud CLI, l'API Dataplex o un job di esportazione dei metadati:

gcloud

Per recuperare gli aspetti di una voce Spanner nel gruppo di voci di sistema @spanner, utilizza il comando gcloud dataplex entries lookup:

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

Sostituisci quanto segue:

  • SOURCE_ENTRY_ID: l'ID voce della risorsa Spanner nella configurazione dell'istanza di origine.

    Come trovare l'ID voce

    Per trovare il nome della voce o tradurre un nome completo (FQN) come spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID, utilizza il comando gcloud dataplex entries search.

  • LOCATION: la regione della configurazione dell'istanza Spanner, ad esempio us-central1.

  • PROJECT_ID: l'ID del progetto Google Cloud che contiene l'istanza Spanner.

API REST

Per recuperare gli aspetti di una voce Spanner nel gruppo di voci di sistema @spanner, invia una richiesta GET all'endpoint 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"

Sostituisci quanto segue:

  • ACCESS_TOKEN: il token di accesso utilizzato dalla tua applicazione per l'autenticazione al servizio. Ad esempio, utilizza $(gcloud auth print-access-token).

  • PROJECT_ID: l'ID del progetto Google Cloud che contiene l'istanza Spanner.

  • LOCATION: la regione della configurazione dell'istanza Spanner, ad esempio us-central1.

  • SOURCE_ENTRY_ID: l'ID voce della risorsa Spanner nella configurazione dell'istanza di origine.

    Come trovare l'ID voce

    Per trovare il nome della voce o tradurre un nome completo (FQN) come spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID, utilizza il comando gcloud dataplex entries search.

Job di esportazione

Per esportare i metadati di più voci in un batch in Cloud Storage, esegui un job di esportazione dei metadati.

Sposta l'istanza nella configurazione dell'istanza di destinazione

Prima di importare gli aspetti nella configurazione dell'istanza di destinazione, segui questi passaggi:

  1. Sposta l'istanza Spanner nella configurazione dell'istanza di destinazione. Attendi la sincronizzazione dei metadati di Spanner per l'istanza spostata in Knowledge Catalog, che può richiedere circa sei ore.

  2. Per verificare che la sincronizzazione sia stata completata, cerca l'istanza spostata utilizzando uno dei seguenti metodi:

    • Nella pagina Ricerca di Knowledge Catalog, inserisci la seguente query:

      system=spanner instance_config=DESTINATION_CONFIG_NAME

    • Esegui il comando gcloud dataplex entries search:

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

    Quando il comando restituisce la voce per la configurazione dell'istanza di destinazione, la sincronizzazione è completata.

Importa gli aspetti nella configurazione dell'istanza di destinazione

Dopo la sincronizzazione dei metadati, collega gli aspetti copiati alle voci nella configurazione dell'istanza di destinazione:

gcloud

Per collegare gli aspetti copiati alla voce nella configurazione dell'istanza di destinazione, utilizza il comando gcloud dataplex entries update-aspects:

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

Sostituisci quanto segue:

  • DESTINATION_ENTRY_ID: l'ID voce della risorsa Spanner spostata nella configurazione dell'istanza di destinazione.

  • DESTINATION_LOCATION: la regione della configurazione dell'istanza Spanner di destinazione, ad esempio us-central1.

  • PROJECT_ID: l'ID del progetto Google Cloud che contiene l'istanza Spanner.

  • ASPECTS_FILE: il percorso di un file JSON o YAML che contiene gli aspetti da aggiungere o aggiornare.

API REST

Per collegare gli aspetti esportati alla voce nella configurazione dell'istanza di destinazione, utilizza il metodo dell'API REST projects.locations.entryGroups.entries.patch, come mostrato nell'esempio seguente:

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"

Sostituisci quanto segue:

  • ACCESS_TOKEN: il token di accesso utilizzato dalla tua applicazione per l'autenticazione al servizio. Ad esempio, utilizza $(gcloud auth print-access-token).

  • ASPECT_KEY: la chiave dell'aspetto nel formato PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID per un aspetto a livello di voce o PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID@Schema.COLUMN_NAME per un aspetto a livello di colonna.

  • FIELD_NAME e FIELD_VALUE: il nome e il valore del campo definiti dal tipo di aspetto.

  • PROJECT_ID: l'ID del progetto che contiene l'istanza Spanner.

  • DESTINATION_LOCATION: la regione della configurazione dell'istanza Spanner di destinazione, ad esempio us-central1.

  • DESTINATION_ENTRY_ID: l'ID voce della risorsa Spanner spostata nella configurazione dell'istanza di destinazione.

Job di importazione

Per importare in batch gli aspetti per più voci da Cloud Storage, esegui un job di importazione dei metadati.

Passaggi successivi