Eseguire l'autenticazione e connettersi a un'origine dati con l'API Conversational Analytics

Gli sviluppatori possono utilizzare l'API Conversational Analytics, a cui si accede tramite geminidataanalytics.googleapis.com, per creare un'interfaccia di chat o un agente di dati basato sull'intelligenza artificiale (AI) che risponde a domande sui dati strutturati in BigQuery, Looker e Looker Studio utilizzando il linguaggio naturale.

Questa pagina descrive come autenticarsi all'API Conversational Analytics e configurare le connessioni ai dati in Looker, BigQuery e Looker Studio utilizzando richieste HTTP dirette o l'SDK. L'API Conversational Analytics utilizza metodi di autenticazione standardGoogle Cloud .

Prima di iniziare

Prima di poter eseguire l'autenticazione all'API Conversational Analytics 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 Abilitare l'API Conversational Analytics.

Autenticazione nell'API Conversational Analytics

Questa sezione descrive come autenticarsi all'API Conversational Analytics (tramite geminidataanalytics.googleapis.com) utilizzando i metodi HTTP e Python per ottenere i token di autorizzazione necessari.

HTTP curl

Il seguente comando curl di esempio invia una richiesta all'API Conversational Analytics. Il comando gcloud auth print-identity-token fornisce un token di accesso utilizzato per l'autorizzazione. Nell'esempio di codice, sostituisci con il percorso della risorsa API appropriato.

curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://geminidataanalytics.googleapis.com/

HTTP con Python

Il seguente codice Python di esempio mostra come ottenere un token di accesso per l'autenticazione HTTP utilizzando Google Cloud CLI e Python.

  billing_project = 'YOUR_BILLING_PROJECT'
  access_token = !gcloud auth application-default print-access-token
  url = f"https://geminidataanalytics.googleapis.com/v1beta/projects/{billing_project}:method"
  headers = {"Authorization": f'Bearer {access_token[0]}'}

Sostituisci i valori di esempio come segue:

  • YOUR_BILLING_PROJECT: l'ID del tuo progetto di fatturazione in cui sono abilitate le API richieste.
  • method: il percorso della risorsa per l'endpoint di destinazione. Ad esempio:
    • Per creare un agente dati, utilizza il metodo POST e il percorso della risorsa /v1beta/projects/{billing_project}/locations/global/dataAgents.
    • Per elencare gli agenti dati esistenti, utilizza il metodo GET e il percorso della risorsa /v1beta/projects/{billing_project}/locations/global/dataAgents.

SDK Python

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

from google.colab import auth
auth.authenticate_user()

Connettersi a Looker con l'API Conversational Analytics

Per connetterti a Looker con l'API Conversational Analytics, devi fornire le seguenti informazioni:

Puoi quindi scegliere di autenticarti utilizzando le chiavi API di Looker (ID client e client secret) o un token di accesso. I clienti che utilizzano l'opzione IP privato di Looker (Google Cloud core) devono autenticarsi con un token di accesso.

Con l'API Conversational Analytics puoi connetterti a una sola esplorazione di Looker alla volta.

Autenticazione con le chiavi API Looker

Questa sezione descrive come generare le chiavi API e configurare l'API Conversational Analytics per connettersi a Looker utilizzando richieste HTTP dirette o l'SDK. I clienti che utilizzano l'opzione IP privato di Looker (Google Cloud core) non possono utilizzare questo metodo e devono autenticarsi con un token di accesso.

Per stabilire una connessione con un'istanza di Looker, devi disporre di chiavi API di Looker valide, create da Looker e costituite da un ID client e un client secret. Looker utilizza queste chiavi per autorizzare le richieste all'API Looker.

Per saperne di più sulla generazione di nuove chiavi API di Looker, consulta Impostazioni di amministrazione - Utenti. Per scoprire di più sui metodi di autenticazione e sulla gestione delle chiavi API di Looker, consulta Autenticazione API di Looker.

HTTP con Python

Dopo aver generato le chiavi API (ID client e secret), puoi configurare l'API Conversational Analytics per connettersi a Looker effettuando richieste HTTP dirette. Il seguente codice campione mostra come specificare i dettagli dell'origine dati Looker e le chiavi API nel corpo della richiesta HTTP.


looker_credentials = {
  "oauth": {
      "secret": {
        "client_id": "your_looker_client_id",
        "client_secret": "your_looker_client_secret",
      }
  }
}

looker_data_source = {
  "looker": {
    "explore_references": {
        "looker_instance_uri": "https://your_company.looker.com",
        "lookml_model": "your_model",
        "explore": "your_explore",
    }
  }
}

Sostituisci i valori di esempio come segue:

  • your_looker_client_id: l'ID client della chiave API Looker generata
  • your_looker_client_secret: il client secret della chiave API Looker generata
  • https://your_company.looker.com: L'URL completo dell'istanza di Looker
  • your_model: il nome del modello LookML che vuoi utilizzare
  • your_explore: Il nome dell'esplorazione all'interno del modello specificato che vuoi utilizzare

SDK Python

Dopo aver generato le chiavi API (ID client e secret), puoi configurare l'API Conversational Analytics per connetterti a Looker utilizzando Python. Il seguente codice Python di esempio mostra come specificare i dettagli dell'origine dati di Looker e le chiavi API per l'API Conversational Analytics.

looker_client_id = "YOUR-LOOKER-CLIENT-ID" # @param {type:"string"}
looker_client_secret = "YOUR-LOOKER-CLIENT-SECRET" # @param {type:"string"}
looker_instance_uri = "YOUR-LOOKER-INSTANCE-URI" # @param {type:"string"}
lookml_model = "YOUR-LOOKER-MODEL" # @param {type:"string"}
explore = "YOUR-LOOKER-EXPLORE" # @param {type:"string"}

# Looker data source
looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.secret.client_id = looker_client_id
credentials.oauth.secret.client_secret = looker_client_secret

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

Sostituisci i valori di esempio come segue:

  • YOUR-LOOKER-CLIENT-ID: l'ID client della chiave API Looker generata
  • YOUR-LOOKER-CLIENT-SECRET: il client secret della chiave API Looker generata
  • YOUR-LOOKER-INSTANCE-URI: L'URL completo dell'istanza di Looker
  • YOUR-LOOKER-MODEL: Il nome del modello Looker che vuoi utilizzare
  • YOUR-LOOKER-EXPLORE: Il nome dell'esplorazione Looker che vuoi utilizzare

Autenticazione con un token di accesso

Questa sezione descrive come configurare l'API Conversational Analytics per connettersi a Looker utilizzando un token di accesso.

Per stabilire una connessione con un'istanza di Looker, è necessario un valore access_token OAuth2 valido, creato da una richiesta riuscita all'endpoint API Looker login.

Per scoprire di più sulla generazione di un token di accesso, vedi Autenticazione API Looker e come presentare le credenziali client per ottenere un token di autorizzazione.

HTTP con Python

Il seguente codice campione mostra come specificare i dettagli dell'origine dati Looker e il token di accesso nel corpo della richiesta HTTP.

Per una maggiore sicurezza, ti consigliamo di archiviare il token di accesso di Looker (access_token) come variabile di ambiente.

looker_credentials = {
  "oauth": {
    "token": {
      "access_token": "YOUR-TOKEN",
    }
  }
}

looker_data_source = {
  "looker": {
    "explore_references": {
        "looker_instance_uri": "https://your_company.looker.com",
        "lookml_model": "your_model",
        "explore": "your_explore",
    }
  }
}

Sostituisci i valori di esempio come segue:

  • YOUR-TOKEN: il valore access_token che generi per l'autenticazione in Looker.
  • https://your_company.looker.com: L'URL completo dell'istanza di Looker
  • your_model: il nome del modello LookML che vuoi utilizzare
  • your_explore: Il nome dell'esplorazione all'interno del modello specificato che vuoi utilizzare

SDK Python

Il seguente codice Python di esempio mostra come definire i dettagli dell'origine dati di Looker e il token di accesso per l'autenticazione utilizzando l'SDK Python.

Per una maggiore sicurezza, ti consigliamo di archiviare il token di accesso di Looker (access_token) come variabile di ambiente.

looker_access_token = "YOUR-TOKEN"
looker_instance_uri = "YOUR-LOOKER-INSTANCE-URI"
lookml_model = "YOUR-LOOKER-MODEL"
explore = "YOUR-LOOKER-EXPLORE"

# Looker data source
looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.token.access_token = looker_access_token

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

Sostituisci i valori di esempio come segue:

  • YOUR-TOKEN: il valore access_token che utilizzi per l'autenticazione in Looker
  • YOUR-LOOKER-INSTANCE-URI: L'URL completo dell'istanza di Looker
  • YOUR-LOOKER-MODEL: Il nome del modello Looker che vuoi utilizzare
  • YOUR-LOOKER-EXPLORE: Il nome dell'esplorazione Looker che vuoi utilizzare

HTTP utilizzando JavaScript

Il seguente codice campione mostra come specificare i dettagli dell'origine dati Looker e il token di accesso nel corpo della richiesta HTTP.

Per una maggiore sicurezza, ti consigliamo di archiviare il token di accesso di Looker (access_token) come variabile di ambiente.

const requestBody = {
  project: GCP_PROJECT,
  messages: [
    {
      user_message: {
        text: inputWithPreviousMessages,
      },
    },
  ],
  context: {
    system_instruction: agentConfig.system_instructions,
    datasource_references: {
      looker: {
        explore_references: [
          {
            looker_instance_uri: YOUR-LOOKER-INSTANCE-URI,
            lookml_model: YOUR-LOOKER-MODEL,
            explore: YOUR-LOOKER-EXPLORE,
          },
        ],
        credentials: {
          oauth: {
            token: {
              access_token: YOUR-TOKEN,
            },
          },
        },
      },
    },
  },
}

Sostituisci i valori di esempio come segue:

  • YOUR-LOOKER-INSTANCE-URI: L'URL completo dell'istanza di Looker
  • YOUR-LOOKER-MODEL: il nome del modello LookML che vuoi utilizzare
  • YOUR-LOOKER-EXPLORE: Il nome dell'esplorazione all'interno del modello specificato che vuoi utilizzare
  • YOUR-TOKEN: il valore access_token che generi per l'autenticazione in Looker.

Connettiti a BigQuery con l'API Conversational Analytics

Per connetterti a BigQuery con l'API Conversational Analytics, devi autenticarti al tuo progetto BigQuery e fornire le seguenti informazioni:

  • L'ID progetto BigQuery
  • L'ID set di dati BigQuery
  • L'ID tabella BigQuery

Con l'API Conversational Analytics, puoi connetterti ed eseguire query su un massimo di 10 tabelle BigQuery alla volta.

Questa sezione descrive come configurare l'API Conversational Analytics per connettersi a BigQuery utilizzando richieste HTTP dirette o un SDK.

HTTP con Python

Dopo l'autenticazione al progetto BigQuery, puoi configurare l'API Conversational Analytics per accedere ai dati in BigQuery effettuando richieste HTTP dirette. Il seguente codice campione mostra come specificare i dettagli dell'origine dati BigQuery e all'interno del corpo della richiesta HTTP.

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "my_project_id",
          "datasetId": "my_dataset_id",
          "tableId": "my_table_id"
        },
        {
          "projectId": "my_project_id_2",
          "datasetId": "amy_dataset_id_2",
          "tableId": "my_table_id_2"
        },
        # Up to 10 total tables may be included
      ]
    }
}

Sostituisci i valori di esempio come segue:

  • my_project_id: 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 pubblici, specifica bigquery-public-data.
  • my_dataset_id: l'ID del set di dati BigQuery.
  • my_table_id: l'ID della tabella BigQuery.

SDK Python

Puoi utilizzare l'SDK auth di Colaboratory per autenticarti su BigQuery utilizzando le credenziali dell'utente autenticato su Colaboratory.

Il seguente codice Python di esempio mostra come autenticare il tuo Account Google in BigQuery all'interno di Colaboratory e configurare l'API Conversational Analytics per accedere a un'origine dati BigQuery.

from google.colab import auth
auth.authenticate_user()

# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = "my_project_id"
bigquery_table_reference.dataset_id = "my_dataset_id"
bigquery_table_reference.table_id = "my_table_id"

bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "my_project_id_2"
bigquery_table_reference_2.dataset_id = "my_dataset_id_2"
bigquery_table_reference_2.table_id = "my_table_id_2"

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

Sostituisci i valori di esempio come segue:

  • my_project_id: 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 pubblici, specifica bigquery-public-data.
  • my_dataset_id: l'ID del set di dati BigQuery. Ad esempio, san_francisco.
  • my_table_id: l'ID della tabella BigQuery. Ad esempio, street_trees.

Connettersi a Looker Studio con l'API Conversational Analytics

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

Abilitare l'API Looker Studio

Per abilitare l'API Looker Studio, segui le istruzioni riportate in Abilitare l'API.

Autenticarsi in Looker Studio

Per connetterti a Looker Studio con l'API Conversational Analytics, devi autenticarti in Looker Studio e fornire l'ID origine dati di Looker Studio.

HTTP con Python

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

Puoi autenticarti in Looker Studio effettuando richieste HTTP dirette. Una chiamata HTTP di esempio è mostrata nel seguente blocco di codice.

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

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

SDK Python

Dopo aver attivato l'API Looker Studio, puoi eseguire l'autenticazione a Looker Studio utilizzando un SDK. Il seguente codice Python di esempio mostra come specificare i dettagli dell'origine dati di Looker e autenticarsi in Looker Studio.


datasource_id = "STUDIO-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 effettivo dell'origine dati di Looker Studio che vuoi utilizzare.