Autenticar e se conectar a uma fonte de dados com a API Conversational Analytics

Os desenvolvedores podem usar a API Conversational Analytics, acessada pelo geminidataanalytics.googleapis.com, para criar uma interface de chat ou um agente de dados com tecnologia de IA que responda perguntas sobre dados estruturados no BigQuery, no Looker e no Looker Studio usando linguagem natural. Ela também permite consultar dados dos bancos de dados do Google Cloud (AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL).

Nesta página, descrevemos como autenticar na API Conversational Analytics. Também explicamos como configurar conexões com seus dados no Looker, no BigQuery, no Looker Studio e nos bancos de dados do Google Cloud (AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL) usando solicitações HTTP diretas ou o SDK. A API Conversational Analytics usa métodos de autenticaçãoGoogle Cloud padrão.

Antes de começar

Antes de se autenticar na API Conversational Analytics e configurar conexões com seus dados, conclua os pré-requisitos e ative as APIs necessárias para seu projeto Google Cloud , conforme descrito em Ativar a API Conversational Analytics.

Autenticar na API Conversational Analytics

Esta seção descreve como se autenticar na API Conversational Analytics (pelo geminidataanalytics.googleapis.com) usando métodos HTTP e Python para receber os tokens de autorização necessários.

HTTP curl

O exemplo de comando curl a seguir envia uma solicitação para a API Conversational Analytics. O comando gcloud auth print-identity-token fornece um token de acesso usado para autorização. No exemplo de código, substitua pelo caminho de recurso da API adequado.

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

HTTP usando Python

O exemplo de código Python a seguir demonstra como conseguir um token de acesso para autenticação HTTP usando a CLI do Google Cloud 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]}'}

Substitua os valores de exemplo da seguinte forma:

  • YOUR_BILLING_PROJECT: o ID do seu projeto de faturamento que tem as APIs necessárias ativadas.
  • method: o caminho do recurso para o endpoint de destino. Por exemplo:
    • Para criar um agente de dados, use o método POST e o caminho do recurso /v1beta/projects/{billing_project}/locations/global/dataAgents.
    • Para listar os agentes de dados atuais, use o método GET e o caminho do recurso /v1beta/projects/{billing_project}/locations/global/dataAgents.

SDK do Python

O exemplo de código Python a seguir demonstra como autenticar sua Conta do Google para acessar a API Conversational Analytics no Colaboratory:

from google.colab import auth
auth.authenticate_user()

Conectar-se ao Looker com a API Conversational Analytics

Para se conectar ao Looker com a API Conversational Analytics, você precisa fornecer as seguintes informações:

Além disso, o usuário autenticado ou a conta de serviço precisa ter as permissões necessárias do Looker.

Escolher o método de autenticação adequado

Em seguida, escolha autenticar usando chaves de API do Looker (ID e chave secreta do cliente) ou um token de acesso. Os clientes que usam o Looker (Google Cloud Core) com apenas conexões particulares precisam fazer a autenticação com um token de acesso.

Use a tabela a seguir para escolher o método de autenticação adequado.

Tipo de usuário Método de autenticação Para o Looker (original) Para o Looker (Google Cloud Core) Para o Looker (Google Cloud Core) que usa apenas conexões particulares Descrição
Incorporar usuários Token de acesso login_user login_user login_user Respeita as permissões de linha e coluna da LookML (por exemplo, access_filters, access_grants, sql_always_where) do access_token do usuário de destino.
Usuários padrão Token de acesso

login_user

Ou

Cliente OAuth

 Cliente OAuth Cliente OAuth Respeita as permissões de linha e coluna da LookML (por exemplo, access_filters, access_grants, sql_always_where) do access_token do usuário de destino.
Conta de serviço somente da API Looker Chave de API ID e chave secreta do cliente ID e chave secreta do cliente N/A Todos os usuários compartilham o mesmo nível de acesso ao Looker.

As chaves de API usam as permissões e os níveis de acesso do usuário. As chaves de API podem ser úteis se você estiver criando um aplicativo em que todos compartilham o mesmo nível de acesso.

Um token de acesso permite usar as permissões de linha e coluna do LookML (por exemplo,access_filters, access_grants, sql_always_where) do access_token do usuário de destino. Um token de acesso é útil para um aplicativo multilocatário.

Permissões necessárias do Looker

O usuário ou a conta de serviço cujas credenciais são usadas para autenticação precisa receber um papel do Looker que inclua as seguintes permissões para os modelos que você quer consultar:

É possível configurar essas permissões na seção Administrador > Funções da sua instância do Looker.

Autenticar com chaves de API do Looker

Nesta seção, descrevemos como gerar as chaves de API e configurar a API Conversational Analytics para se conectar ao Looker usando solicitações HTTP diretas ou o SDK.

Para estabelecer uma conexão com uma instância do Looker, você precisa de chaves de API válidas do Looker, que são criadas pelo Looker e consistem em um ID e uma chave secreta do cliente. O Looker usa essas chaves para autorizar solicitações à API Looker.

Para saber mais sobre como gerar novas chaves de API Looker, consulte Configurações de admin - Usuários. Para saber mais sobre métodos de autenticação e como gerenciar chaves de API Looker, consulte Autenticação da API Looker.

HTTP usando Python

Depois de gerar as chaves de API (ID e segredo do cliente), você pode configurar a API Conversational Analytics para se conectar ao Looker fazendo solicitações HTTP diretas. O exemplo de código a seguir demonstra como especificar os detalhes da fonte de dados do Looker e as chaves de API no corpo da solicitação 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",
    }
  }
}

Substitua os valores de exemplo da seguinte forma:

  • your_looker_client_id: o ID do cliente da chave de API do Looker gerada
  • your_looker_client_secret: a chave secreta do cliente da chave de API do Looker gerada
  • https://your_company.looker.com: o URL completo da sua instância do Looker
  • your_model: o nome do modelo do LookML que você quer usar
  • your_explore: o nome da análise no modelo especificado que você quer usar

SDK do Python

Depois de gerar as chaves de API (ID e segredo do cliente), você pode configurar a API Conversational Analytics para se conectar ao Looker usando Python. O exemplo de código Python a seguir demonstra como especificar os detalhes da fonte de dados do Looker e as chaves de API para a 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]

Substitua os valores de exemplo da seguinte forma:

  • YOUR-LOOKER-CLIENT-ID: o ID do cliente da chave de API do Looker gerada
  • YOUR-LOOKER-CLIENT-SECRET: a chave secreta do cliente da chave de API do Looker gerada
  • YOUR-LOOKER-INSTANCE-URI: o URL completo da sua instância do Looker
  • YOUR-LOOKER-MODEL: o nome do modelo do Looker que você quer usar
  • YOUR-LOOKER-EXPLORE: o nome da Análise do Looker que você quer usar

Fazer a autenticação com um token de acesso

Nesta seção, descrevemos como configurar a API Conversational Analytics para se conectar ao Looker usando um token de acesso.

Para estabelecer uma conexão com uma instância do Looker, você precisa de um valor access_token OAuth2 válido, que é criado por uma solicitação bem-sucedida ao endpoint de API Looker login.

Para saber mais sobre como gerar um token de acesso, consulte Autenticação da API Looker e como apresentar credenciais do cliente para receber um token de autorização.

HTTP usando Python

O exemplo de código a seguir demonstra como especificar os detalhes da fonte de dados do Looker e o token de acesso no corpo da solicitação HTTP.

Sugerimos armazenar o token de acesso do Looker (access_token) como uma variável de ambiente para melhorar a segurança.

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",
    }
  }
}

Substitua os valores de exemplo da seguinte forma:

  • YOUR-TOKEN: o valor access_token gerado para autenticar no Looker.
  • https://your_company.looker.com: o URL completo da sua instância do Looker
  • your_model: o nome do modelo do LookML que você quer usar
  • your_explore: o nome da análise no modelo especificado que você quer usar

SDK do Python

O exemplo de código Python a seguir demonstra como definir os detalhes da fonte de dados do Looker e o token de acesso para autenticar usando o SDK do Python.

Sugerimos armazenar o token de acesso do Looker (access_token) como uma variável de ambiente para melhorar a segurança.

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]

Substitua os valores de exemplo da seguinte forma:

  • YOUR-TOKEN: o valor de access_token usado para autenticar no Looker
  • YOUR-LOOKER-INSTANCE-URI: o URL completo da sua instância do Looker
  • YOUR-LOOKER-MODEL: o nome do modelo do Looker que você quer usar
  • YOUR-LOOKER-EXPLORE: o nome da Análise do Looker que você quer usar

HTTP usando JavaScript

O exemplo de código a seguir demonstra como especificar os detalhes da fonte de dados do Looker e o token de acesso no corpo da solicitação HTTP.

Sugerimos armazenar o token de acesso do Looker (access_token) como uma variável de ambiente para melhorar a segurança.

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,
            },
          },
        },
      },
    },
  },
}

Substitua os valores de exemplo da seguinte forma:

  • YOUR-LOOKER-INSTANCE-URI: o URL completo da sua instância do Looker
  • YOUR-LOOKER-MODEL: o nome do modelo do LookML que você quer usar
  • YOUR-LOOKER-EXPLORE: o nome da análise no modelo especificado que você quer usar
  • YOUR-TOKEN: o valor access_token gerado para autenticar no Looker.

Conectar-se ao BigQuery com a API Conversational Analytics

Para se conectar a uma ou mais tabelas do BigQuery com a API Conversational Analytics, autentique o projeto relevante do BigQuery para cada tabela. Para cada tabela, forneça as seguintes informações:

  • O ID do projeto do BigQuery
  • O ID do conjunto de dados do BigQuery
  • O ID da tabela do BigQuery

Com a API Conversational Analytics, não há limites rígidos para o número de tabelas do BigQuery a que você pode se conectar. No entanto, conectar um grande número de tabelas pode reduzir a acurácia ou fazer com que você exceda o limite de tokens de entrada do Gemini. Consultas que exigem junções complexas em várias tabelas também podem resultar em respostas menos precisas.

Nesta seção, descrevemos como configurar a API Conversational Analytics para se conectar ao BigQuery usando solicitações HTTP diretas ou um SDK.

HTTP usando Python

O exemplo de código a seguir define uma conexão com várias tabelas do BigQuery.

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "my_project_id",
          "datasetId": "my_dataset_id",
          "tableId": "my_table_id"
        },
        {
          "projectId": "my_project_id_2",
          "datasetId": "my_dataset_id_2",
          "tableId": "my_table_id_2"
        },
        {
          "projectId": "my_project_id_3",
          "datasetId": "my_dataset_id_3",
          "tableId": "my_table_id_3"
        },
      ]
    }
}

Substitua os valores de exemplo da seguinte forma:

  • my_project_id: o ID do projeto do Google Cloud que contém o conjunto de dados e a tabela do BigQuery a que você quer se conectar. Para se conectar a um conjunto de dados público, especifique bigquery-public-data.
  • my_dataset_id: ID do conjunto de dados do BigQuery.
  • my_table_id: ID da tabela do BigQuery.

SDK do Python

Você pode usar o SDK auth do Colaboratory para autenticar o BigQuery com as credenciais do usuário autenticado no Colaboratory.

O exemplo de código Python a seguir define uma conexão com várias tabelas do BigQuery e demonstra como autenticar sua Conta do Google no BigQuery dentro do Colaboratory.

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"

bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "my_project_id_3"
bigquery_table_reference_3.dataset_id = "my_dataset_id_3"
bigquery_table_reference_3.table_id = "my_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]

Substitua os valores de exemplo da seguinte forma:

  • my_project_id: o ID do projeto do Google Cloud que contém o conjunto de dados e a tabela do BigQuery a que você quer se conectar. Para se conectar a um conjunto de dados público, especifique bigquery-public-data.
  • my_dataset_id: ID do conjunto de dados do BigQuery. Por exemplo, san_francisco.
  • my_table_id: ID da tabela do BigQuery. Por exemplo, street_trees.

Conectar ao Looker Studio com a API Conversational Analytics

Para se conectar ao Looker Studio com a API Conversational Analytics, primeiro ative a API Looker Studio. Nesta seção, descrevemos como configurar a API Conversational Analytics para se conectar ao Looker Studio usando solicitações HTTP diretas ou um SDK.

Ativar a API Looker Studio

Para ativar a API Looker Studio, siga as instruções em Ativar a API.

Autenticar no Looker Studio

Para se conectar ao Looker Studio com a API Conversational Analytics, você precisa fazer a autenticação no Looker Studio e fornecer o ID da fonte de dados dele.

HTTP usando Python

Depois de ativar a API Looker Studio, você pode fazer a autenticação no Looker Studio fazendo solicitações HTTP curl com Python. O exemplo de código a seguir demonstra como especificar os detalhes da fonte de dados do Looker no corpo da solicitação HTTP.

É possível fazer a autenticação no Looker Studio fazendo solicitações HTTP diretas. Um exemplo de chamada HTTP é mostrado no bloco de código a seguir.

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

Substitua your_studio_datasource_id pelo ID real da fonte de dados do Looker Studio que você quer usar.

SDK do Python

Depois de ativar a API Looker Studio, você pode fazer a autenticação no Looker Studio usando um SDK. O exemplo de código Python a seguir mostra como especificar os detalhes da fonte de dados do Looker e fazer a autenticação no 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]

Substitua STUDIO-DATASOURCE-ID pelo ID real da fonte de dados do Looker Studio que você quer usar.

Conectar-se a bancos de dados com a API Conversational Analytics

Para se conectar a bancos de dados com a API Conversational Analytics, você precisa ter as permissões necessárias do IAM para sua instância de banco de dados.

Conectar-se ao AlloyDB para PostgreSQL

O usuário ou a conta de serviço precisa ter o papel alloydb.databaseUser. Para mais informações, consulte AlloyDB, autenticação do banco de dados do IAM.

HTTP usando Python

O exemplo de código a seguir demonstra como especificar os detalhes da fonte de dados do AlloyDB no corpo da solicitação HTTP para o endpoint queryData.

alloydb_data_source = {
    "alloydbReference": {
        "databaseReference": {
            "tableId": [
                "your_table_id_1",
                "your_table_id_2"
            ]
        },
        "agentContextReference": {
            "context_set_id": "your_context_set_id"
        }
    }
}

Substitua os valores de exemplo da seguinte forma:

  • your_table_id: a lista separada por vírgulas de IDs de tabelas. Se não for definido, todas as tabelas no banco de dados serão consideradas.
  • your_context_set_id: o ID completo do conjunto de contexto a ser recuperado. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do contexto do agente no AlloyDB.

SDK do Python

O exemplo de código Python a seguir demonstra como definir os detalhes da fonte de dados do AlloyDB usando o SDK do 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.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

Substitua os valores de exemplo da seguinte forma:

  • your_table_id_1: o ID da primeira tabela na sua instância do AlloyDB.
  • your_table_id_2: o ID da segunda tabela na sua instância do AlloyDB.
  • your_context_set_id: o ID completo do conjunto de contexto a ser recuperado. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do contexto do agente no AlloyDB.

Conectar-se ao GoogleSQL para Spanner

O usuário ou a conta de serviço precisa ter o papel spanner.databaseReader. Para mais informações, consulte Aplicar papéis do IAM.

HTTP usando Python

O exemplo de código a seguir demonstra como especificar os detalhes da fonte de dados do GoogleSQL para Spanner no corpo da solicitação HTTP para o endpoint queryData.

spanner_data_source = {
    "spannerReference": {
        "databaseReference": {
            "tableId": [
                "your_table_id_1",
                "your_table_id_2"
            ]
        },
        "agentContextReference": {
            "context_set_id": "your_context_set_id"
        }
    }
}

Substitua os valores de exemplo da seguinte forma:

  • your_table_id_1: o ID da primeira tabela na sua instância do GoogleSQL para Spanner.
  • your_table_id_2: o ID da segunda tabela na sua instância do GoogleSQL para Spanner.
  • your_context_set_id: o ID completo do conjunto de contexto a ser recuperado. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do contexto do agente no GoogleSQL para Spanner.

SDK do Python

O exemplo de código Python a seguir demonstra como definir os detalhes da fonte de dados do GoogleSQL para Spanner usando o SDK do 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

Substitua os valores de exemplo da seguinte forma:

  • your_table_id_1: o ID da primeira tabela na sua instância do GoogleSQL para Spanner.
  • your_table_id_2: o ID da segunda tabela na sua instância do GoogleSQL para Spanner.
  • your_context_set_id: o ID completo do conjunto de contexto a ser recuperado. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do contexto do agente no GoogleSQL para Spanner.

Conectar-se ao Cloud SQL e ao Cloud SQL para PostgreSQL

As seções a seguir fornecem instruções para se conectar ao Cloud SQL e ao Cloud SQL para PostgreSQL. O usuário ou a conta de serviço precisa ter os papéis cloudsql.studioUser e cloudsql.instanceUser. Para mais informações, consulte Gerenciar usuários com autenticação de banco de dados do IAM para Cloud SQL e Gerenciar usuários com autenticação de banco de dados do IAM para Cloud SQL para PostgreSQL.

HTTP usando Python

O exemplo de código a seguir demonstra como especificar os detalhes da fonte de dados do Cloud SQL e do Cloud SQL para PostgreSQL no corpo da solicitação HTTP para o endpoint queryData.

cloudsql_data_source = {
    "cloudSqlReference": {
        "databaseReference": {
            "tableId": [
                "your_table_id_1",
                "your_table_id_2"
            ]
        },
        "agentContextReference": {
            "context_set_id": "your_context_set_id"
        }
    }
}

Substitua os valores de exemplo da seguinte forma:

SDK do Python

O exemplo de código Python a seguir demonstra como definir os detalhes da fonte de dados do Cloud SQL e do Cloud SQL para PostgreSQL usando o SDK do 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

Substitua os valores de exemplo da seguinte forma: