Utilizzare Dataplex Universal Catalog con MCP, Gemini e altri agenti

Questa pagina spiega come connettere l'istanza Dataplex Universal Catalog a strumenti per sviluppatori come la CLI Gemini. Il collegamento di Dataplex Universal Catalog a questi strumenti consente l'individuazione dei dati e la gestione degli asset basata sull'AI direttamente all'interno dell'IDE.

Per un'esperienza della riga di comando integrata, ti consigliamo di utilizzare l'estensione Dataplex Universal Catalog dedicata per Gemini CLI. L'estensione raggruppa il server Model Context Protocol (MCP) sottostante, che funge da intermediario tra la CLI Gemini e Dataplex Universal Catalog, eliminando la necessità di una configurazione separata del server.

In alternativa, puoi connettere altri IDE e strumenti per sviluppatori che supportano MCP utilizzando lo strumento di uso generale MCP Toolbox for Databases. Puoi quindi utilizzare gli agenti AI nel tuo IDE esistente per scoprire gli asset di dati in Dataplex Universal Catalog. Per ulteriori informazioni su MCP, consulta Introduzione al Model Context Protocol.

Questa guida illustra la procedura di connessione per i seguenti strumenti:

Informazioni sull'interfaccia a riga di comando di Gemini e sulle estensioni

Gemini CLI è un agente di AI conversazionale open source di Google che accelera i flussi di lavoro di sviluppo e aiuta con la codifica, il debug, l'esplorazione dei dati e la creazione di contenuti. Offre un'esperienza basata su agenti per interagire con i servizi Data Cloud, come Dataplex Universal Catalog, e altri database open source popolari.

Per maggiori informazioni su Gemini CLI, consulta la documentazione di Gemini CLI.

Come funzionano le estensioni

Le estensioni ampliano le funzionalità di Gemini CLI, consentendogli di connettersi e controllare servizi specifici e altri strumenti. Google Cloud Forniscono a Gemini il contesto e la comprensione dell'API, consentendo l'interazione conversazionale. Puoi caricare le estensioni della CLI Gemini da URL GitHub, directory locali o registri. Queste estensioni offrono nuovi strumenti, comandi slash e prompt. Queste sono separate dalle estensioni IDE, come Gemini Code Assist, che si integrano utilizzando MCP Toolbox.

Informazioni sull'estensione Dataplex Universal Catalog

MCP Toolbox for Databases è in versione beta (pre-v1.0) e potrebbe subire modifiche sostanziali fino alla prima release stabile (v1.0).

L'estensione Dataplex Universal Catalog per Gemini CLI integra l'AI nelle attività di governance e scoperta dei dati. Puoi interagire con Dataplex Universal Catalog utilizzando prompt in linguaggio naturale nel terminale. Ecco alcuni esempi:

Categoria Strumento Esempio di prompt in linguaggio naturale
Individuazione e governance dei dati dataplex_search_entries
  • Trova tutti i set di dati relativi alle vendite in Europa.
  • Mostrami le tabelle che contengono PII dei clienti.
  • Elenca tutti i set di dati BigQuery nel lake "marketing" in Dataplex Universal Catalog.
dataplex_lookup_entry
  • Qual è lo schema della tabella "ordini"?
  • Descrivi le regole sulla qualità dei dati applicate al database dei clienti.
  • Chi è elencato come proprietario dell'attività per la tabella `customer_details`?
dataplex_search_aspect_types
  • Mostrami i tipi di aspetto correlati alle regole sulla qualità dei dati.
  • Elenca tutti i tipi di aspetto utilizzati per la governance dei dati.
  • Esistono tipi di aspetto per contrassegnare i dati PII?

Per saperne di più sull'estensione Dataplex Universal Catalog, consulta Estensione Gemini CLI - Dataplex Universal Catalog.

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per connetterti a Dataplex Universal Catalog utilizzando MCP Toolbox o l'estensione CLI Gemini, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per connettersi a Dataplex Universal Catalog utilizzando MCP Toolbox o l'estensione della CLI Gemini. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per connettersi a Dataplex Universal Catalog utilizzando MCP Toolbox o l'estensione CLI di Gemini, sono necessarie le seguenti autorizzazioni:

  • Per abilitare le API: serviceusage.services.enable
  • Per utilizzare gli strumenti di Dataplex Universal Catalog:
    • dataplex.projects.search
    • dataplex.entries.get
    • dataplex.aspectTypes.get
    • dataplex.aspectTypes.list

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

Abilitare l'API Dataplex Universal Catalog

  1. Esamina le autorizzazioni richieste per completare le attività descritte in questa guida.

  2. In the Google Cloud console, go to the project selector page.

    Go to project selector

  3. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

  5. Enable the Dataplex API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  6. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Installare MCP Toolbox

Non è necessario installare MCP Toolbox se prevedi di utilizzare solo Gemini Code Assist o l' estensione della CLI Gemini, in quanto includono le funzionalità del server richieste. Per altri IDE e strumenti, segui i passaggi descritti in questa sezione per installare MCP Toolbox.

  1. Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona il file binario corrispondente al tuo sistema operativo e all'architettura della CPU. Devi utilizzare MCP Toolbox v0.15.0 o versioni successive.

    Linux/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox

    Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.15.0.

    macOS (Darwin)/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox

    Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.15.0.

    macOS (Darwin)/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/amd64/toolbox

    Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.15.0.

    Windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox

    Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.15.0.

  2. Rendi eseguibile il file binario:

    chmod +x toolbox

  3. Verifica l'installazione:

    ./toolbox --version

    Un'installazione riuscita restituisce il numero di versione, ad esempio 0.15.0.

Configurare client e connessioni

Questa sezione spiega come connettere Dataplex Universal Catalog ai tuoi strumenti.

Se utilizzi Gemini Code Assist o la CLI Gemini autonoma, non devi installare o configurare MCP Toolbox, in quanto questi strumenti raggruppano le funzionalità del server richieste. Per le istruzioni di configurazione, consulta le schede Estensione Gemini Code Assist o Estensione interfaccia a riga di comando di Gemini.

Per altri strumenti e IDE compatibili con MCP, devi prima installare MCP Toolbox. Il toolbox funge da server Model Context Protocol (MCP) open source che si trova tra l'IDE e Dataplex Universal Catalog, fornendo un piano di controllo sicuro ed efficiente per i tuoi strumenti di AI. Dopo l'installazione, seleziona la scheda dello strumento specifico per visualizzare le istruzioni di configurazione.

Estensione della CLI di Gemini

Questo metodo utilizza l'estensione dataplex dedicata per lo strumento a riga di comando Gemini autonomo e non utilizza MCP Toolbox.

  1. Installa l'interfaccia a riga di comando di Gemini.
  2. Installa l'estensione Dataplex Universal Catalog per la CLI Gemini dal repository GitHub: 
    gemini extensions install https://github.com/gemini-cli-extensions/dataplex
  3. Imposta la variabile di ambiente per connetterti al progetto Dataplex Universal Catalog: 
    export DATAPLEX_PROJECT="PROJECT_ID"

    Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud .

  4. Avvia l'interfaccia a riga di comando di Gemini in modalità interattiva: 
    gemini
     La CLI carica automaticamente l'estensione Dataplex Universal Catalog e i relativi strumenti, che puoi utilizzare per interagire con i tuoi asset di dati.

Gemini Code Assist

Gemini Code Assist raggruppa le funzionalità del server MCP richieste, quindi non è necessario installare MCP Toolbox separatamente.

  1. In VS Code, installa l'estensione Gemini Code Assist.
  2. Attiva la modalità Agente nella chat di Gemini Code Assist.
  3. Nella directory di lavoro, crea una cartella denominata .gemini. All'interno, crea un file settings.json.
  4. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Codice Claude

  1. Installa Claude Code.
  2. Crea il file .mcp.json nella directory principale del progetto, se non esiste.
  3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Claude desktop

  1. Apri Claude Desktop e vai a Impostazioni.
  2. Per aprire il file di configurazione, nella scheda Sviluppatore, fai clic su Modifica configurazione.
  3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
  4. Riavvia Claude desktop.
    Nella nuova schermata di chat viene visualizzata un'icona MCP con il nuovo server MCP.

Cline

  1. In VS Code, apri l'estensione Cline e poi fai clic sull'icona MCP Servers.
  2. Per aprire il file di configurazione, tocca Configura server MCP.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
    Dopo la connessione riuscita del server, viene visualizzato uno stato attivo verde.

Cursore

  1. Crea la directory .cursor nella root del progetto se non esiste.
  2. Crea il file .cursor/mcp.json se non esiste e aprilo.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
  4. Apri Cursore e vai a Impostazioni>Impostazioni cursore >MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

VS Code (Copilot)

  1. Apri VS Code e crea la directory .vscode nella radice del progetto se non esiste.
  2. Crea il file .vscode/mcp.json se non esiste e aprilo.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "servers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Windsurf

  1. Apri Windsurf e vai all'assistente Cascade.
  2. Per aprire il file di configurazione, fai clic sull'icona di MCP, quindi fai clic su Configura.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Utilizzare gli strumenti

Il tuo strumento di AI è ora connesso a Dataplex Universal Catalog. Prova a chiedere all'assistente AI di trovare alcuni asset di dati come set di dati BigQuery, istanze Cloud SQL e altri.

Sono disponibili i seguenti strumenti per il LLM:

(Facoltativo) Aggiungi istruzioni di sistema

Le istruzioni di sistema sono un modo per fornire linee guida specifiche all'LLM, aiutandolo a comprendere il contesto e a rispondere in modo più accurato. Configura le istruzioni di sistema in base al prompt di sistema consigliato.

Ad esempio, puoi aggiungere istruzioni per guidare il LLM su come utilizzare gli strumenti di Dataplex Universal Catalog:

  • Quando ti viene chiesto di trovare set di dati o tabelle, utilizza lo strumento dataplex_search_entries.
  • Se ti vengono chiesti lo schema della tabella o i dettagli dei metadati, come le regole di qualità dei dati o la proprietà, utilizza lo strumento dataplex_lookup_entry.
  • Quando ti vengono chieste regole di governance o classificazioni, inizia utilizzando dataplex_search_aspect_types per trovare tipi di aspetti pertinenti.

Per maggiori informazioni su come configurare le istruzioni, consulta Utilizzare le istruzioni per ottenere modifiche AI che seguono il tuo stile di codifica.

Passaggi successivi