Autenticare l'identità dell'utente e connettersi a un'origine dati

Questa pagina descrive come eseguire l'autenticazione con l'API Analisi conversazionale. Spiega inoltre come configurare le connessioni ai dati in Looker, BigQuery, Data Studio e nei database (AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL) utilizzando richieste HTTP dirette o l'SDK. L'API Analisi conversazionale utilizza i metodi di autenticazioneGoogle Cloud standard.

Prima di iniziare

Prima di poter eseguire l'autenticazione con l'API Analisi conversazionale e configurare le connessioni ai tuoi dati, devi completare i prerequisiti e abilitare le API richieste per il tuo progetto Google Cloud , come descritto in Abilita l'API Analisi conversazionale.

Se prevedi di utilizzare le chiavi di crittografia gestite dal cliente (CMEK) per proteggere le risorse dell'API Analisi conversazionale, devi concedere al account di servizio dell'API l'autorizzazione per utilizzare la chiave di Cloud Key Management Service. Per maggiori dettagli, consulta la sezione Prima di iniziare della documentazione sulle CMEK.

Autenticati con l'API Analisi conversazionale

Questa sezione descrive come eseguire l'autenticazione con l'API Analisi conversazionale utilizzando i metodi HTTP e Python per ottenere i token di autorizzazione necessari. Gli esempi seguenti utilizzano la logica degli endpoint regionali in base alla località della risorsa. Per saperne di più sugli endpoint regionali, consulta Residenza dei dati.

curl HTTP

Il seguente comando curl di esempio ha come target un metodo endpoint API per dimostrare come inviare una richiesta autenticata utilizzando il token di identità generato da Google Cloud CLI:

curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://ENDPOINT_URL/v1/projects/PROJECT_ID/locations/LOCATION/METHOD

Sostituisci i valori di esempio come segue:

  • ENDPOINT_URL: l'URL dell'endpoint di servizio corrispondente alla tua località, ad esempio geminidataanalytics.googleapis.com per la località predefinita global o geminidataanalytics.us.rep.googleapis.com per la località multiregionale us.
  • PROJECT_ID: l'ID del progetto Google Cloud in cui hai abilitato le API richieste.
  • LOCATION: la località in cui sono archiviate le risorse (ad esempio global o us-east4).

  • METHOD: il metodo dell'endpoint di destinazione o il percorso della risorsa (ad esempio, dataAgents per creare un agente o dataAgents/AGENT_ID per ottenere un agente specifico).

HTTP utilizzando Python

Il seguente codice Python di esempio ha come target un metodo di endpoint API per mostrare come ottenere un token di accesso e inviare una richiesta HTTP autenticata. Il codice crea dinamicamente l'URL dell'endpoint in base al tipo di località specificato.

billing_project = 'PROJECT_ID'
location = 'LOCATION'
access_token = !gcloud auth application-default print-access-token

# Set the base URL based on location.
if not location or location == "global":
  base_url = "https://geminidataanalytics.googleapis.com"
elif "-" in location:
  # Regional endpoints
  base_url = f"https://geminidataanalytics-{location}.googleapis.com"
else:
  # Multi-regional endpoints
  base_url = f"https://geminidataanalytics.{location}.rep.googleapis.com"

url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/METHOD"
headers = {"Authorization": f'Bearer {access_token[0]}'}

Sostituisci i valori di esempio come segue:

  • PROJECT_ID: l'ID del progetto Google Cloud in cui hai abilitato le API richieste.
  • LOCATION: la località in cui sono archiviate le risorse (ad esempio global o us-east4).

  • METHOD: il metodo dell'endpoint di destinazione o il percorso della risorsa. Ad esempio:

    • Per creare un agente per i dati, utilizza il metodo POST e specifica dataAgents.
    • Per elencare gli agenti per i dati esistenti, utilizza il metodo GET e specifica dataAgents.

SDK Python

Il seguente esempio di codice Python mostra come autenticare il tuo Account Google per accedere all'API Analisi conversazionale in Colaboratory:

from google.colab import auth
auth.authenticate_user()

Connettiti a Looker con l'API Analisi conversazionale

Per i ruoli e le autorizzazioni richiesti, le opzioni di autorizzazione e il codice campione per la connessione alle esplorazioni di Looker, consulta Connettiti a Looker. Per le istanze che utilizzano solo connessioni private, consulta Connettiti a un'istanza di Looker (Google Cloud core) che utilizza connessioni private.

Connettiti a BigQuery con l'API Analisi conversazionale

Questa sezione descrive come configurare l'API Analisi conversazionale per connettersi a BigQuery utilizzando richieste HTTP dirette o un SDK. L'API Analisi conversazionale supporta le connessioni alle tabelle BigQuery e ai grafici con BigQuery Graph.

Con l'API Analisi conversazionale, non esistono limiti rigidi al numero di tabelle BigQuery a cui puoi connetterti. Tuttavia, la connessione a un numero elevato di tabelle può ridurre l'accuratezza o causare il superamento del limite di token di input di Gemini. Anche le query che richiedono join complessi tra più tabelle potrebbero generare risposte meno accurate.

Connettiti alle tabelle

Per connetterti a una o più tabelle BigQuery, fornisci l'ID progetto, l'ID set di dati e l'ID tabella per ogni tabella.

I seguenti esempi mostrano come connettersi a una o più tabelle BigQuery utilizzando richieste HTTP o l'SDK Python.

HTTP utilizzando Python

Il seguente codice campione definisce una connessione a più tabelle BigQuery:

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID"
        },
        {
          "projectId": "PROJECT_ID_2",
          "datasetId": "DATASET_ID_2",
          "tableId": "TABLE_ID_2"
        },
        {
          "projectId": "PROJECT_ID_3",
          "datasetId": "DATASET_ID_3",
          "tableId": "TABLE_ID_3"
        },
      ]
    }
}

Sostituisci i valori di esempio come segue:

  • PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: l'ID del progetto Google Cloud che contiene il set di dati e la tabella BigQuery a cui vuoi connetterti. Per connetterti a un set di dati pubblico, specifica bigquery-public-data.
  • DATASET_ID, DATASET_ID_2, DATASET_ID_3: l'ID del set di dati BigQuery (o catalog.namespace per le tabelle del catalogo di runtime di Lakehouse).
  • TABLE_ID, TABLE_ID_2, TABLE_ID_3: l'ID della tabella BigQuery (o il nome della tabella per le tabelle del catalogo di runtime Lakehouse).

SDK Python

Puoi utilizzare l'SDK auth di Colaboratory per eseguire l'autenticazione utilizzando le credenziali del tuo Account Google e autorizzare il client Colab ad accedere a BigQuery utilizzando le tue credenziali.

Il seguente codice Python di esempio definisce una connessione a più tabelle BigQuery e mostra come eseguire l'autenticazione utilizzando le credenziali del tuo Account Google all'interno di Colaboratory per autorizzare le richieste.

from google.colab import auth
auth.authenticate_user()

# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = "PROJECT_ID"
bigquery_table_reference.dataset_id = "DATASET_ID"
bigquery_table_reference.table_id = "TABLE_ID"

bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "PROJECT_ID_2"
bigquery_table_reference_2.dataset_id = "DATASET_ID_2"
bigquery_table_reference_2.table_id = "TABLE_ID_2"

bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "PROJECT_ID_3"
bigquery_table_reference_3.dataset_id = "DATASET_ID_3"
bigquery_table_reference_3.table_id = "TABLE_ID_3"

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference, bigquery_table_reference_2, bigquery_table_reference_3]

Sostituisci i valori di esempio come segue:

  • PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: l'ID del progetto Google Cloud che contiene il set di dati e la tabella BigQuery a cui vuoi connetterti. Per connetterti a un set di dati pubblico, specifica bigquery-public-data.
  • DATASET_ID, DATASET_ID_2, DATASET_ID_3: l'ID del set di dati BigQuery (o catalog.namespace per le tabelle del catalogo di runtime di Lakehouse). Ad esempio, san_francisco.
  • TABLE_ID, TABLE_ID_2, TABLE_ID_3: l'ID della tabella BigQuery (o il nome della tabella per le tabelle del catalogo di runtime Lakehouse). Ad esempio: street_trees.

Connettiti a BigQuery Graph

I seguenti esempi mostrano come connettersi a uno o più grafi con BigQuery Graph utilizzando richieste HTTP o l'SDK Python.

Per informazioni sui requisiti delle versioni di BigQuery e sulle limitazioni delle query sui grafi, consulta Connettiti a BigQuery Graph.

HTTP utilizzando Python

Il seguente codice campione definisce una connessione a un grafo BigQuery:

bigquery_data_sources = {
    "bq": {
      "propertyGraphReferences": [
        {
          "projectId": "GRAPH_PROJECT_ID",
          "datasetId": "GRAPH_DATASET_ID",
          "propertyGraphId": "GRAPH_ID"
        }
      ]
    }
}

Sostituisci i valori di esempio come segue:

  • GRAPH_PROJECT_ID: l'ID del progetto Google Cloud che contiene il grafo BigQuery.
  • GRAPH_DATASET_ID: l'ID del set di dati BigQuery che contiene il grafo.
  • GRAPH_ID: l'ID del grafo BigQuery.

SDK Python

Puoi utilizzare l'SDK auth di Colaboratory per autenticarti in BigQuery utilizzando le credenziali del tuo utente autenticato in Colaboratory.

Il seguente codice Python di esempio definisce una connessione a un grafo BigQuery:

from google.colab import auth
auth.authenticate_user()

# BigQuery graph reference
graph_reference = geminidataanalytics.BigQueryPropertyGraphReference()
graph_reference.project_id = "GRAPH_PROJECT_ID"
graph_reference.dataset_id = "GRAPH_DATASET_ID"
graph_reference.property_graph_id = "GRAPH_ID"

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.property_graph_references = [graph_reference]

Sostituisci i valori di esempio come segue:

  • GRAPH_PROJECT_ID: l'ID del progetto Google Cloud che contiene il grafo BigQuery.
  • GRAPH_DATASET_ID: l'ID del set di dati BigQuery che contiene il grafo.
  • GRAPH_ID: l'ID del grafo BigQuery.

Connettiti a Data Studio con l'API Analisi conversazionale

Per connetterti a Data Studio con l'API Conversational Analytics, devi prima attivare l'API Data Studio. Questa sezione descrive come configurare l'API Analisi conversazionale per connettersi a Data Studio utilizzando richieste HTTP dirette o un SDK.

Per utilizzare l'API Analisi conversazionale con Data Studio Pro, l'abbonamento Pro deve essere al di fuori di un perimetro VPC-SC.

Abilita l'API Data Studio

Per abilitare l'API Data Studio, segui le istruzioni riportate in Abilita l'API.

Autenticati in Data Studio

Per connetterti a Data Studio con l'API Analisi conversazionale, devi assicurarti che l'utente o il account di servizio autenticato sia autorizzato ad accedere all'origine dati di Data Studio, quindi fornire l'ID dell'origine dati.

HTTP utilizzando Python

Dopo aver attivato l'API Data Studio, puoi connetterti a Data Studio inviando richieste HTTP curl con Python. Il seguente codice campione mostra come specificare i dettagli dell'origine dati di Data Studio nel corpo della richiesta HTTP.

Puoi connetterti a Data Studio inviando richieste HTTP dirette. Nel blocco di codice seguente è mostrata una chiamata HTTP di esempio.

looker_studio_data_source = {
    "studio":{
        "studio_references":
        [
            {
              "datasource_id": "DATASOURCE_ID"
            }
        ]
    }
}

Sostituisci your_studio_datasource_id con l'ID origine dati effettivo dell'origine dati di Data Studio che vuoi utilizzare.

SDK Python

Dopo aver attivato l'API Data Studio, puoi connetterti a Data Studio utilizzando un SDK. Il seguente codice Python di esempio mostra come specificare i dettagli dell'origine dati di Data Studio.


datasource_id = "DATASOURCE_ID"

# Looker Studio
studio_references = geminidataanalytics.StudioDatasourceReference()
studio_references.datasource_id = studio_datasource_id

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.studio.studio_references = [studio_references]

Sostituisci STUDIO-DATASOURCE-ID con l'ID origine dati effettivo dell'origine dati di Data Studio che vuoi utilizzare.

Connettiti ai database con l'API Analisi conversazionale

Per connetterti ai database con l'API Analisi conversazionale, devi disporre delle autorizzazioni IAM necessarie per l'istanza del database. Facoltativamente, se utilizzi i set di contesto (anteprima) con l'origine dati del database, per creare, caricare o gestire i set di contesto, devi anche abilitare l'API Knowledge Catalog e concedere il ruolo Dataplex Catalog Editor (roles/dataplex.catalogEditor) o Dataplex Catalog Admin (roles/dataplex.catalogAdmin) nel progetto. Per saperne di più, consulta Autorizzazioni per i set di contesti.

Connettiti ad AlloyDB per PostgreSQL

L'account utente o di servizio deve avere il ruolo alloydb.databaseUser. Per saperne di più, consulta AlloyDB, autenticazione database IAM.

HTTP utilizzando Python

Il seguente codice campione mostra come specificare i dettagli dell'origine dati AlloyDB nel corpo della richiesta HTTP.

alloydb_data_sources = {
  "alloydb": {
      "database_reference": {
          "project_id": alloydb_project_id,
          "region": location,
          "cluster_id": alloydb_cluster_id,
          "instance_id": alloydb_instance_id,
          "database_id": alloydb_database_id,
          "table_ids":["table1", "table2", "table3"]
      },
      # Optional: Include this if you have pre-authored context for the agent
      # "agent_context_reference": {
      #     "context_set_id": f"projects/alloydb_project_id/locations/{location}/contextSets/your_context_set_id"
      # }
  }
}

Sostituisci i valori di esempio come segue:

  • your_table_id: l'elenco separato da virgole degli ID tabella. Se non viene impostato, vengono prese in considerazione tutte le tabelle del database.
  • your_context_set_id: (Facoltativo) l'ID completo del set di contesti da recuperare. Per saperne di più su come trovare l'ID set di contesto, consulta la documentazione di AlloyDB.

SDK Python

Il seguente codice Python di esempio mostra come definire i dettagli dell'origine dati AlloyDB utilizzando l'SDK Python.

# AlloyDB data source
alloydb_table_ids = ["your_table_id_1", "your_table_id_2"]
alloydb_context_set_id = "your_context_set_id"

alloydb_reference = geminidataanalytics.AlloyDbReference()
alloydb_reference.database_reference.table_id = alloydb_table_ids
alloydb_reference_database_reference.project_id = billing_project
alloydb_reference_database_reference.region = "us-central1" # Example region
alloydb_reference_database_reference.cluster_id = alloydb_cluster_id
alloydb_reference_database_reference.instance_id = alloydb_instance_id
alloydb_reference_database_reference.database_id = alloydb_database_id
# optional set agent context reference
# alloydb_ref_1.agent_context_reference.context_set_id = f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"

alloydb_reference.agent_context_reference.context_set_id = alloydb_context_set_id

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.alloydb.alloydb_reference = alloydb_reference

Sostituisci i valori di esempio come segue:

  • your_table_id_1: l'ID della prima tabella nell'istanza AlloyDB.
  • your_table_id_2: l'ID della seconda tabella nell'istanza AlloyDB.
  • your_context_set_id: l'ID completo del set di contesti da recuperare. Per saperne di più su come trovare l'ID set di contesto, consulta la documentazione di AlloyDB.

Connettiti a GoogleSQL per Spanner

L'account utente o di servizio deve avere il ruolo spanner.databaseReader. Per saperne di più, consulta Applica i ruoli IAM.

HTTP utilizzando Python

Il seguente codice campione mostra come specificare i dettagli dell'origine dati GoogleSQL per Spanner nel corpo della richiesta HTTP.

spanner_data_sources = {
    "spanner_reference": {
        "database_reference": {
            "project_id": spanner_project_id,
            "region": location,
            "engine": engine,
            "instance_id": spanner_instance_id,
            "database_id": spanner_database_id,
        },
        # Optional: Include this if you have pre-authored context for the agent
        # "agent_context_reference": {
        #     "context_set_id": f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
        # }
    }
}

Sostituisci i valori di esempio come segue:

  • your_table_id_1: l'ID della prima tabella nell'istanza GoogleSQL per Spanner.
  • your_table_id_2: l'ID della seconda tabella nell'istanza GoogleSQL per Spanner.
  • your_context_set_id: l'ID completo del set di contesti da recuperare. Per saperne di più su come trovare l'ID del set di contesto, consulta la documentazione di Spanner.

SDK Python

Il seguente codice Python di esempio mostra come definire i dettagli dell'origine dati GoogleSQL per Spanner utilizzando l'SDK Python.

# Spanner data source
spanner_table_ids = ["your_table_id_1", "your_table_id_2"]
spanner_context_set_id = "your_context_set_id"

spanner_reference = geminidataanalytics.SpannerReference()
spanner_reference.database_reference.table_id = spanner_table_ids
spanner_reference.agent_context_reference.context_set_id = spanner_context_set_id

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.spanner.spanner_reference = spanner_reference

Sostituisci i valori di esempio come segue:

  • your_table_id_1: l'ID della prima tabella nell'istanza GoogleSQL per Spanner.
  • your_table_id_2: l'ID della seconda tabella nell'istanza GoogleSQL per Spanner.
  • your_context_set_id: l'ID completo del set di contesti da recuperare. Per saperne di più su come trovare l'ID del set di contesto, consulta la documentazione di Spanner.

Connettiti a Cloud SQL per MySQL e Cloud SQL per PostgreSQL

Le sezioni seguenti forniscono istruzioni per la connessione sia a Cloud SQL per MySQL sia a Cloud SQL per PostgreSQL. L'account utente o il service account deve disporre dei ruoli cloudsql.studioUser e cloudsql.instanceUser. Per saperne di più, consulta Gestisci gli utenti con l'autenticazione del database IAM per Cloud SQL per MySQL e Gestisci gli utenti con l'autenticazione del database IAM per Cloud SQL per PostgreSQL.

HTTP utilizzando Python

Il seguente codice campione mostra come specificare i dettagli dell'origine dati Cloud SQL per MySQL e Cloud SQL per PostgreSQL nel corpo della richiesta HTTP.

cloudsql_data_source = {
    "cloudSqlReference": {
        "databaseReference": {
            "engine": MYSQL,
            "project_id": cloud-db-nl2sql,
            "region": us-central1,
            "instance_id": nl2sql-birdsql-mysql,
            "database_id": financial
        },
        # Optional: Include this if you have pre-authored context for the agent
        # "agent_context_reference": {
        #     "context_set_id": f"projects/cloud-db-nl2sql/locations/us-central1/contextSets/bdf_pg_all_templates\"
        # }
    }
}

Sostituisci i valori di esempio come segue:

  • your_table_id_1: l'ID della prima tabella nell'istanza Cloud SQL per MySQL e Cloud SQL per PostgreSQL.
  • your_table_id_2: l'ID della seconda tabella nell'istanza Cloud SQL per MySQL e Cloud SQL per PostgreSQL.
  • your_context_set_id: l'ID completo del set di contesti da recuperare. Per saperne di più su come trovare l'ID del set di contesto, consulta la documentazione di Cloud SQL per MySQL e Cloud SQL per PostgreSQL.

SDK Python

Il seguente codice Python di esempio mostra come definire i dettagli dell'origine dati Cloud SQL per MySQL e Cloud SQL per PostgreSQL utilizzando l'SDK Python.

# Cloud SQL data source
cloudsql_table_ids = ["your_table_id_1", "your_table_id_2"]
cloudsql_context_set_id = "your_context_set_id"

cloudsql_reference = geminidataanalytics.CloudSqlReference()
cloudsql_reference.database_reference.table_id = cloudsql_table_ids
cloudsql_reference.agent_context_reference.context_set_id = cloudsql_context_set_id

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.cloudsql.cloudsql_reference = cloudsql_reference

Sostituisci i valori di esempio come segue:

  • your_table_id_1: l'ID della prima tabella nell'istanza Cloud SQL per MySQL e Cloud SQL per PostgreSQL.
  • your_table_id_2: l'ID della seconda tabella nell'istanza Cloud SQL per MySQL e Cloud SQL per PostgreSQL.
  • your_context_set_id: l'ID completo del set di contesti da recuperare. Per saperne di più su come trovare l'ID del set di contesto, consulta la documentazione di Cloud SQL per MySQL e Cloud SQL per PostgreSQL.