Utilizzare i domini di dati

I domini di dati in Knowledge Catalog (precedentemente Dataplex Universal Catalog) ti consentono di restringere i risultati di ricerca a contesti aziendali specifici e di scoprire i metadati entro confini definiti. In qualità di utente di un dominio di dati, puoi sfogliare la gerarchia del dominio, cercare le risorse del dominio e recuperare il contesto del dominio per eseguire il grounding degli agenti AI.

Prima di iniziare

Prima di eseguire una ricerca per dominio, assicurati di disporre dei ruoli richiesti e di aver abilitato le API necessarie.

Abilita API

Abilita l'API Dataplex, se non è già abilitata.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per cercare e scoprire i metadati utilizzando i domini di dati, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto o sul dominio di dati:

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

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Sfoglia la gerarchia dei domini

Per saperne di più su come sfogliare la gerarchia dei domini, consulta Visualizza i domini e i sottodomini di dati in una località.

Trova risorse all'interno di un dominio di dati

Puoi eseguire ricerche all'interno di un dominio di dati per trovare risorse come set di dati, tabelle e prodotti di dati BigQuery e visualizzarne i metadati. Per cercare risorse all'interno di un dominio, segui questi passaggi:

Console

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

    Vai alla Ricerca

  2. Fai clic su Prova la ricerca naturale per attivare la funzionalità di ricerca naturale.

  3. Fai clic su Filtri.

  4. Nel campo Ambito, seleziona Dominio dall'elenco.

  5. Nel campo Seleziona dominio, seleziona il dominio per cui vuoi restringere i risultati. Se necessario, aggiungi altri filtri.

In alternativa, puoi utilizzare l'opzione di menu Cerca nel dominio per trovare le risorse nel dominio:

  1. Nella console Google Cloud , vai alla pagina Domini di dati.

    Vai a Domini di dati

  2. Seleziona Cerca nel dominio dal menu . Questa azione apre automaticamente una finestra di ricerca con il filtro domain applicato.

  3. Utilizza il campo di ricerca per trovare le risorse nel dominio.

REST

Per cercare voci con ambito limitato a un dominio di dati, utilizza il metodo projects.locations.searchEntries e fornisci il percorso del dominio nel parametro contexts.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud .
  • LOCATION_ID: la regione per la richiesta di ricerca (o global).
  • QUERY: la stringa della query di ricerca.
  • DOMAIN_ID: l'identificatore univoco del dominio di dati che definisce il contesto dell'ambito di ricerca.

Metodo HTTP e URL: 

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchEntries

Corpo JSON della richiesta: 

{
  "query": "QUERY",
  "contexts": [ "projects/PROJECT_ID/locations/LOCATION_ID/dataDomains/DOMAIN_ID" ],
  "semantic_search": true,
  "page_size": 100
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.

Recupera il contesto per i domini di dati

Puoi utilizzare il metodo lookupContext per basare gli agenti AI sul contesto aziendale acquisito dai tuoi domini di dati. Il metodo lookupContext supporta i domini di dati nei seguenti modi:

  • Contesto per un dominio di dati. Puoi passare la voce che rappresenta un dominio di dati nell'elenco resources. La risposta contiene i metadati del dominio di dati, ad esempio la descrizione e i domini di dati principali nella gerarchia dei domini.
  • Appartenenza al dominio di dati degli asset di dati. Quando recuperi il contesto per un asset di dati incluso in uno o più domini di dati, la risposta contiene un campo dataDomains che elenca i domini di dati a cui appartiene l'asset, a partire dal dominio più specifico fino al dominio di primo livello.

Per recuperare il contesto di un dominio di dati, invia la seguente richiesta:

curl --request POST \
  'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H 'Content-Type: application/json' \
  -d '{
    "resources": [
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION/dataDomains/DATA_DOMAIN_ID"
    ],
    "options": {
      "format": "yaml"
    }
  }'

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto che contiene il dominio di dati.
  • PROJECT_NUMBER: il numero del progetto che contiene il dominio di dati.
  • LOCATION: la posizione del dominio di dati.
  • DATA_DOMAIN_ID: l'ID del dominio di dati.

Per saperne di più sul metodo lookupContext, consulta Recupera il contesto per gli asset di dati.

Limitazioni

Quando cerchi risorse al di fuori del contesto del dominio, ad esempio quando utilizzi una ricerca globale, le autorizzazioni di rilevabilità del dominio non vengono applicate. Vedi solo le risorse a cui hai accesso nel sistema sottostante, ad esempio BigQuery.

Supponiamo che un set di dati BigQuery sia incluso in un dominio di dati. Hai il ruolo Dataplex Data Domain Entry Reader per il dominio, ma non disponi dell'autorizzazione diretta per visualizzare il set di dati in BigQuery:

  • Ricerca all'interno del dominio:il set di dati viene visualizzato nei risultati di ricerca perché vengono applicate le autorizzazioni del dominio.
  • Ricerca all'esterno del dominio:il set di dati non viene visualizzato nei risultati di ricerca. In una ricerca generica, le autorizzazioni di dominio non si applicano e non hai accesso diretto a BigQuery.

Passaggi successivi