Nesta página, descrevemos como fazer a autenticação na API de Análise conversacional. Ele também explica como configurar conexões com seus dados no Looker, no BigQuery, no Data Studio e em bancos de dados (AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL e Cloud SQL para PostgreSQL) usando solicitações HTTP diretas ou o SDK. A API Análise conversacional usa métodos de autenticaçãoGoogle Cloud padrão.
Antes de começar
Antes de se autenticar na API Análise conversacional 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 Análise conversacional.
Se você planeja usar chaves de criptografia gerenciadas pelo cliente (CMEK) para proteger os recursos da API Análise conversacional, conceda à conta de serviço da API permissão para usar sua chave do Cloud Key Management Service. Para mais detalhes, consulte Antes de começar na documentação de CMEK.
Autenticar na API de Análise conversacional
Esta seção descreve como se autenticar na API de Análise conversacional usando métodos HTTP e Python para receber os tokens de autorização necessários. Os exemplos a seguir usam a lógica de endpoint regional com base no local do recurso. Para mais informações sobre endpoints regionais, consulte Residência de dados.
HTTP curl
O comando curl de exemplo a seguir tem como alvo um método de endpoint de API para demonstrar como enviar uma solicitação autenticada usando o token de identidade gerado pela Google Cloud CLI:
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://ENDPOINT_URL/v1/projects/PROJECT_ID/locations/LOCATION/METHOD
Substitua os valores de exemplo da seguinte forma:
- ENDPOINT_URL: o URL do endpoint de serviço que corresponde ao seu local, por exemplo,
geminidataanalytics.googleapis.compara o local padrãoglobalougeminidataanalytics.us.rep.googleapis.compara a multirregiãous. - PROJECT_ID: o ID do projeto do Google Cloud em que você ativou as APIs necessárias.
LOCATION: o local em que os recursos estão armazenados (por exemplo,
globalouus-east4).METHOD: o método do endpoint de destino ou o caminho do recurso (por exemplo,
dataAgentspara criar um agente oudataAgents/AGENT_IDpara receber um agente específico).
HTTP usando Python
O exemplo de código Python a seguir segmenta um método de endpoint de API para demonstrar como conseguir um token de acesso e enviar uma solicitação HTTP autenticada. O código cria dinamicamente o URL do endpoint com base no tipo de local especificado.
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]}'}
Substitua os valores de exemplo da seguinte forma:
- PROJECT_ID: o ID do projeto do Google Cloud em que você ativou as APIs necessárias.
LOCATION: o local em que os recursos estão armazenados (por exemplo,
globalouus-east4).METHOD: o método do endpoint de destino ou o caminho do recurso. Exemplo:
- Para criar um agente de dados, use o método
POSTe especifiquedataAgents. - Para listar os agentes de dados atuais, use o método
GETe especifiquedataAgents.
- Para criar um agente de dados, use o método
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 saber mais sobre os papéis e as permissões necessários, as opções de autorização e o exemplo de código para se conectar às Análises do Looker, consulte Conectar ao Looker. Para instâncias que usam apenas conexões particulares, consulte Conectar-se a uma instância do Looker (Google Cloud Core) que usa conexões particulares.
Conectar-se ao BigQuery com a API Conversational Analytics
Nesta seção, descrevemos como configurar a API Conversational Analytics para se conectar ao BigQuery usando solicitações HTTP diretas ou um SDK. A API de Análise conversacional é compatível com conexões com tabelas do BigQuery e com gráficos do BigQuery Graph.
Com a API Análise conversacional, não há limites rígidos para o número de tabelas do BigQuery que podem ser conectadas. No entanto, conectar-se a um grande número de tabelas pode reduzir a precisão 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.
Conectar-se a tabelas
Para se conectar a uma ou mais tabelas do BigQuery, forneça o ID do projeto, o ID do conjunto de dados e o ID de cada tabela.
Os exemplos a seguir mostram como se conectar a uma ou mais tabelas do BigQuery usando solicitações HTTP ou o SDK do Python.
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": "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"
},
]
}
}
Substitua os valores de exemplo da seguinte forma:
- PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: 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. - DATASET_ID, DATASET_ID_2, DATASET_ID_3: o ID do conjunto de dados do BigQuery (ou
catalog.namespacepara tabelas do catálogo do ambiente de execução do Lakehouse). - TABLE_ID, TABLE_ID_2, TABLE_ID_3: o ID da tabela do BigQuery (ou o nome da tabela para tabelas do catálogo do ambiente de execução do Lakehouse).
SDK do Python
Você pode usar o SDK auth do Colaboratory para autenticar com as credenciais da sua Conta do Google e autorizar o cliente do Colab a acessar o BigQuery usando suas credenciais.
O exemplo de código Python a seguir define uma conexão com várias tabelas do BigQuery e demonstra como autenticar usando as credenciais da sua Conta do Google no Colaboratory para autorizar solicitações.
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]
Substitua os valores de exemplo da seguinte forma:
- PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: 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. - DATASET_ID, DATASET_ID_2, DATASET_ID_3: o ID do conjunto de dados do BigQuery (ou
catalog.namespacepara tabelas do catálogo do ambiente de execução do Lakehouse). Por exemplo,san_francisco. - TABLE_ID, TABLE_ID_2, TABLE_ID_3: o ID da tabela do BigQuery (ou o nome da tabela para tabelas do catálogo do ambiente de execução do Lakehouse). Por exemplo,
street_trees.
Conectar-se ao BigQuery Graph
Os exemplos a seguir mostram como se conectar a um ou mais gráficos com o BigQuery Graph usando solicitações HTTP ou o SDK do Python.
Para informações sobre os requisitos da edição do BigQuery e as limitações de consulta de gráfico, consulte Conectar ao BigQuery Graph.
HTTP usando Python
O exemplo de código a seguir define uma conexão com um gráfico do BigQuery:
bigquery_data_sources = {
"bq": {
"propertyGraphReferences": [
{
"projectId": "GRAPH_PROJECT_ID",
"datasetId": "GRAPH_DATASET_ID",
"propertyGraphId": "GRAPH_ID"
}
]
}
}
Substitua os valores de exemplo da seguinte forma:
- GRAPH_PROJECT_ID: o ID do projeto do Google Cloud que contém o gráfico do BigQuery.
- GRAPH_DATASET_ID: o ID do conjunto de dados do BigQuery que contém o gráfico.
- GRAPH_ID: o ID do gráfico 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 um gráfico do 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]
Substitua os valores de exemplo da seguinte forma:
- GRAPH_PROJECT_ID: o ID do projeto do Google Cloud que contém o gráfico do BigQuery.
- GRAPH_DATASET_ID: o ID do conjunto de dados do BigQuery que contém o gráfico.
- GRAPH_ID: o ID do gráfico do BigQuery.
Conectar ao Data Studio com a API de Análise conversacional
Para se conectar ao Data Studio com a API Conversational Analytics, primeiro ative a API Data Studio. Nesta seção, descrevemos como configurar a API Análise conversacional para se conectar ao Data Studio usando solicitações HTTP diretas ou um SDK.
Para usar a API Análise conversacional com o Data Studio Pro, sua assinatura do Pro precisa estar fora de um perímetro do VPC-SC.
Ativar a API Data Studio
Para ativar a API Data Studio, siga as instruções em Ativar a API.
Autenticar no Data Studio
Para se conectar ao Data Studio com a API Análise conversacional, verifique se o usuário ou a conta de serviço autenticada tem autorização para acessar a fonte de dados do Data Studio e forneça o ID da fonte de dados.
HTTP usando Python
Depois de ativar a API Data Studio, você pode se conectar ao Data 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 Data Studio no corpo da solicitação HTTP.
É possível se conectar ao Data 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": "DATASOURCE_ID"
}
]
}
}
Substitua your_studio_datasource_id pelo ID real da fonte de dados do Data Studio que você quer usar.
SDK do Python
Depois de ativar a API Data Studio, você pode se conectar ao Data Studio usando um SDK. O exemplo de código Python a seguir mostra como especificar os detalhes da fonte de dados do 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]
Substitua STUDIO-DATASOURCE-ID pelo ID real da fonte de dados do Data Studio que você quer usar.
Conectar-se a bancos de dados com a API Análise conversacional
Para se conectar a bancos de dados com a API Análise conversacional, você precisa ter as permissões do IAM necessárias para sua instância de banco de dados. Se você usa conjuntos de contexto (pré-lançamento) com sua fonte de dados do banco de dados, para criar, fazer upload ou gerenciar conjuntos de contexto, também é necessário ativar a API Knowledge Catalog e conceder o papel de Editor do Dataplex Catalog (roles/dataplex.catalogEditor) ou Administrador do Dataplex Catalog (roles/dataplex.catalogAdmin) no projeto. Para mais informações, consulte Permissões de conjuntos de contexto.
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 Autenticação via IAM no banco de dados do AlloyDB.
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.
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"
# }
}
}
Substitua os valores de exemplo da seguinte forma:
- your_table_id: a lista separada por vírgulas de IDs de tabela. Se não for definido, todas as tabelas no banco de dados serão consideradas.
- your_context_set_id (opcional): o ID completo do conjunto de contexto a ser recuperado. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte a documentação do 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_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
Substitua os valores de exemplo da seguinte forma:
- your_table_id_1: o ID da primeira tabela na instância do AlloyDB.
- your_table_id_2: o ID da segunda tabela na 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 a documentação do 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.
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"
# }
}
}
Substitua os valores de exemplo da seguinte forma:
- your_table_id_1: o ID da primeira tabela na instância do GoogleSQL para Spanner.
- your_table_id_2: o ID da segunda tabela na 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 a documentação do 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 instância do GoogleSQL para Spanner.
- your_table_id_2: o ID da segunda tabela na 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 a documentação do Spanner.
Conectar-se ao Cloud SQL para MySQL e ao Cloud SQL para PostgreSQL
As seções a seguir fornecem instruções para se conectar ao Cloud SQL para MySQL e ao Cloud SQL para PostgreSQL. A conta de usuário ou de serviço precisa ter os papéis cloudsql.studioUser e cloudsql.instanceUser. Para mais informações, consulte Gerenciar usuários com a autenticação de banco de dados do IAM para o Cloud SQL para MySQL e Gerenciar usuários com a autenticação de banco de dados do IAM para o 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 para MySQL e do Cloud SQL para PostgreSQL no corpo da solicitação 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\"
# }
}
}
Substitua os valores de exemplo da seguinte forma:
- your_table_id_1: o ID da primeira tabela na instância do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL.
- your_table_id_2: o ID da segunda tabela na instância do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL.
- 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 a documentação do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL.
SDK do Python
O exemplo de código Python a seguir demonstra como definir os detalhes da fonte de dados do Cloud SQL para MySQL 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:
- your_table_id_1: o ID da primeira tabela na instância do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL.
- your_table_id_2: o ID da segunda tabela na instância do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL.
- 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 a documentação do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL.