Autentique e estabeleça ligação a uma origem de dados com a API Conversational Analytics

Os programadores podem usar a API Conversational Analytics, acedida através do geminidataanalytics.googleapis.com, para criar uma interface de chat ou um agente de dados com tecnologia de inteligência artificial (IA) que responda a perguntas sobre dados estruturados no BigQuery, no Looker e no Looker Studio usando linguagem natural.

Esta página descreve como autenticar na API Conversational Analytics. Também explica como configurar ligações aos seus dados no Looker, no BigQuery, no Looker Studio e nas bases de dados na nuvem (AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL) através de pedidos HTTP diretos ou do SDK. A API Conversational Analytics usa Google Cloud métodos de autenticação padrão.

Antes de começar

Antes de poder autenticar-se na API Conversational Analytics e configurar ligações aos seus dados, tem de concluir os pré-requisitos e ativar as APIs necessárias para o seu Google Cloud projeto, conforme descrito no artigo Ative a API Conversational Analytics.

Autentique-se na API Conversational Analytics

Esta secção descreve como fazer a autenticação na API Conversational Analytics (através da geminidataanalytics.googleapis.com) usando métodos HTTP e Python para obter os tokens de autorização necessários.

HTTP curl

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

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

HTTP com Python

O exemplo de código Python seguinte demonstra como obter um token de acesso para autenticação HTTP através da Google Cloud CLI e do 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 faturação que tem as APIs necessárias ativadas.
  • method: o caminho do recurso para o ponto final 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 existentes, use o método GET e o caminho do recurso /v1beta/projects/{billing_project}/locations/global/dataAgents.

SDK Python

O seguinte exemplo de código Python demonstra como autenticar a sua Conta Google para aceder à API Conversational Analytics no Colaboratory:

from google.colab import auth
auth.authenticate_user()

Associe o Looker à API Conversational Analytics

Para estabelecer ligação ao Looker com a API Conversational Analytics, tem de fornecer as seguintes informações:

Além disso, o utilizador de autenticação ou a conta de serviço tem de ter as autorizações do Looker necessárias.

Escolha o método de autenticação adequado

Em seguida, pode optar por fazer a autenticação através de chaves da API Looker (ID de cliente e segredo do cliente) ou de um token de acesso. Os clientes que usam o Looker (essencial para o Google Cloud) apenas com ligações privadas têm de fazer a autenticação com um token de acesso.

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

Tipo de utilizador Método de autenticação Para o Looker (original) Para o Looker (Google Cloud Core) Para o Looker (Google Cloud Core) que usa apenas ligações privadas Descrição
Incorpore utilizadores Chave de acesso login_user login_user login_user Respeita as autorizações ao nível da linha e da coluna do LookML (por exemplo, access_filters, access_grants, sql_always_where) do access_token do utilizador de destino.
Utilizadores padrão Chave de acesso

login_user

Ou

Cliente OAuth

 Cliente OAuth Cliente OAuth Respeita as autorizações ao nível da linha e da coluna do LookML (por exemplo, access_filters, access_grants, sql_always_where) do access_token do utilizador de destino.
Conta de serviço apenas com API do Looker Chave da API ID de cliente e segredo ID de cliente e segredo N/A Todos os utilizadores partilham o mesmo nível de acesso ao Looker.

As chaves de API usam as autorizações e os níveis de acesso do utilizador. As chaves da API podem ser úteis se estiver a criar uma aplicação em que todos partilham o mesmo nível de acesso.

Um token de acesso permite-lhe usar autorizações ao nível da linha e da coluna do LookML (por exemplo,access_filters, access_grants, sql_always_where) do access_token do utilizador de destino. Um token de acesso é útil para uma aplicação multi-inquilino.

Autorizações do Looker necessárias

O utilizador ou a conta de serviço cujas credenciais são usadas para autenticação tem de ter uma função do Looker que inclua as seguintes autorizações para os modelos que quer consultar:

Pode configurar estas autorizações na secção Administração > Funções da sua instância do Looker.

Autentique com chaves da API Looker

Esta secção descreve como gerar as chaves de API e configurar a API Conversational Analytics para estabelecer ligação ao Looker através de pedidos HTTP diretos ou do SDK.

Para estabelecer uma ligação a uma instância do Looker, precisa de chaves da API Looker válidas, que são criadas pelo Looker e consistem num ID do cliente e num segredo do cliente. O Looker usa estas chaves para autorizar pedidos à API Looker.

Para saber como gerar novas chaves da API Looker, consulte o artigo Definições de administração – Utilizadores. Para saber mais sobre os métodos de autenticação e a gestão das chaves da API Looker, consulte o artigo Autenticação da API Looker.

HTTP com Python

Depois de gerar as chaves da API (ID do cliente e segredo), pode configurar a API Conversational Analytics para se ligar ao Looker através de pedidos HTTP diretos. O código de exemplo seguinte demonstra como especificar os detalhes da origem de dados do Looker e as chaves da API no corpo do seu pedido 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 de cliente da chave da API Looker gerada
  • your_looker_client_secret: o segredo do cliente da chave da API 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 quer usar
  • your_explore: o nome da funcionalidade Explorar no modelo especificado que quer usar

SDK Python

Depois de gerar as chaves da API (ID do cliente e segredo), pode configurar a API Conversational Analytics para se ligar ao Looker através do Python. O seguinte exemplo de código Python demonstra como especificar os detalhes da sua origem de dados do Looker e as suas chaves da 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 de cliente da chave da API Looker gerada
  • YOUR-LOOKER-CLIENT-SECRET: o segredo do cliente da chave da API 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 quer usar
  • YOUR-LOOKER-EXPLORE: o nome da opção Explorar do Looker que quer usar

Efetue a autenticação com um token de acesso

Esta secção descreve como configurar a API Conversational Analytics para estabelecer ligação ao Looker através de um token de acesso.

Para estabelecer uma ligação a uma instância do Looker, precisa de um valor access_token OAuth2 válido, que é criado por um pedido bem-sucedido ao ponto final da API login do Looker.

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

HTTP com Python

O seguinte código de exemplo demonstra como especificar os detalhes da origem de dados do Looker e o token de acesso no corpo do pedido HTTP.

Sugerimos que armazene 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 que gera 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 quer usar
  • your_explore: o nome da funcionalidade Explorar no modelo especificado que quer usar

SDK Python

O seguinte exemplo de código Python demonstra como definir os detalhes da sua origem de dados do Looker e o seu token de acesso para autenticação através do SDK Python.

Sugerimos que armazene 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 access_token que usa para se 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 quer usar
  • YOUR-LOOKER-EXPLORE: o nome da opção Explorar do Looker que quer usar

HTTP com JavaScript

O seguinte código de exemplo demonstra como especificar os detalhes da origem de dados do Looker e o token de acesso no corpo do pedido HTTP.

Sugerimos que armazene 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 quer usar
  • YOUR-LOOKER-EXPLORE: o nome da funcionalidade Explorar no modelo especificado que quer usar
  • YOUR-TOKEN: o valor access_token que gera para autenticar no Looker.

Associe ao BigQuery com a API Conversational Analytics

Para estabelecer ligação a uma ou mais tabelas do BigQuery com a API Conversational Analytics, tem de se autenticar no projeto do BigQuery relevante para cada tabela. Para cada tabela, faculte 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 existem limites rígidos quanto ao número de tabelas do BigQuery às quais se pode ligar. No entanto, a ligação a um grande número de tabelas pode reduzir a precisão ou fazer com que exceda o limite de tokens de entrada do Gemini. As consultas que requerem junções complexas em várias tabelas também podem resultar em respostas menos precisas.

Esta secção descreve como configurar a API Conversational Analytics para se ligar ao BigQuery através de pedidos HTTP diretos ou de um SDK.

HTTP com Python

O seguinte exemplo de código define uma associação a 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 Google Cloud projeto que contém o conjunto de dados e a tabela do BigQuery aos quais quer estabelecer ligação. Para estabelecer ligação a um conjunto de dados público, especifique bigquery-public-data.
  • my_dataset_id: o ID do conjunto de dados do BigQuery.
  • my_table_id: O ID da tabela do BigQuery.

SDK Python

Pode usar o SDK auth do Colaboratory para se autenticar no BigQuery através das credenciais do seu utilizador autenticado no Colaboratory.

O seguinte código Python de exemplo define uma ligação a várias tabelas do BigQuery e demonstra como autenticar a sua Conta Google no BigQuery no 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 Google Cloud projeto que contém o conjunto de dados e a tabela do BigQuery aos quais quer estabelecer ligação. Para estabelecer ligação a um conjunto de dados público, especifique bigquery-public-data.
  • my_dataset_id: o ID do conjunto de dados do BigQuery. Por exemplo, san_francisco.
  • my_table_id: O ID da tabela do BigQuery. Por exemplo, street_trees.

Associe o Looker Studio à API Conversational Analytics

Para estabelecer ligação ao Looker Studio com a API Conversational Analytics, primeiro tem de ativar a API Looker Studio. Esta secção descreve como configurar a API Conversational Analytics para estabelecer ligação ao Looker Studio através de pedidos HTTP diretos ou de um SDK.

Ative a API Looker Studio

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

Autentique-se no Looker Studio

Para estabelecer ligação ao Looker Studio com a API Conversational Analytics, tem de se autenticar no Looker Studio e fornecer o ID da origem de dados do Looker Studio.

HTTP com Python

Depois de ativar a API Looker Studio, pode autenticar-se no Looker Studio fazendo pedidos HTTP curl com Python. O seguinte código de exemplo demonstra como especificar os detalhes da origem de dados do Looker no corpo do seu pedido HTTP.

Pode autenticar-se no Looker Studio fazendo pedidos HTTP diretos. É apresentado um exemplo de chamada HTTP no bloco de código seguinte.

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

Substitua your_studio_datasource_id pelo ID da origem de dados real da origem de dados do Looker Studio que quer usar.

SDK Python

Depois de ativar a API Looker Studio, pode autenticar-se no Looker Studio através de um SDK. O seguinte exemplo de código Python demonstra como especificar os detalhes da origem de dados do Looker e autenticar 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 da origem de dados real da origem de dados do Looker Studio que quer usar.

Estabeleça ligação a bases de dados com a API Conversational Analytics

Para estabelecer ligação a bases de dados com a API Conversational Analytics, tem de ter as autorizações da IAM necessárias para a instância da base de dados.

Estabeleça ligação ao AlloyDB para PostgreSQL

O utilizador ou a conta de serviço tem de ter a função alloydb.databaseUser. Para mais informações, consulte o artigo AlloyDB, autenticação de base de dados da IAM.

HTTP com Python

O seguinte código de amostra demonstra como especificar os detalhes do AlloyDB e da origem de dados no corpo do seu pedido HTTP para o ponto final 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 de IDs das tabelas separada por vírgulas. Se não for definido, são consideradas todas as tabelas na base de dados.
  • your_context_set_id: o ID completo do contexto definido para obtenção. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte o artigo Encontre o ID do contexto do agente no AlloyDB.

SDK Python

O seguinte exemplo de código Python demonstra como definir os detalhes do AlloyDB e da origem de dados através do 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.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 contexto definido para obtenção. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte o artigo Encontre o ID do contexto do agente no AlloyDB.

Efetue a associação ao GoogleSQL para Spanner

O utilizador ou a conta de serviço tem de ter a função spanner.databaseReader. Para mais informações, consulte o artigo Aplique funções do IAM.

HTTP com Python

O seguinte código de exemplo demonstra como especificar os detalhes da origem de dados do GoogleSQL para Spanner no corpo do seu pedido HTTP para o ponto final 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 contexto definido para obtenção. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte o artigo Encontre o ID do contexto do agente no GoogleSQL para Spanner.

SDK Python

O seguinte código Python de exemplo demonstra como definir os detalhes da origem de dados do GoogleSQL para Spanner através do 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

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 contexto definido para obtenção. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte o artigo Encontre o ID do contexto do agente no GoogleSQL para Spanner.

Estabeleça ligação ao Cloud SQL e ao Cloud SQL para PostgreSQL

As secções seguintes fornecem instruções para estabelecer ligação ao Cloud SQL e ao Cloud SQL para PostgreSQL. O utilizador ou a conta de serviço tem de ter as funções cloudsql.studioUser e cloudsql.instanceUser. Para mais informações, consulte os artigos Faça a gestão de utilizadores com a autenticação de base de dados da IAM para o Cloud SQL e Faça a gestão de utilizadores com a autenticação de base de dados da IAM para o Cloud SQL para PostgreSQL.

HTTP com Python

O seguinte código de exemplo demonstra como especificar os detalhes da origem de dados do Cloud SQL e do Cloud SQL para PostgreSQL no corpo do seu pedido HTTP para o ponto final 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 Python

O seguinte exemplo de código Python demonstra como definir os detalhes da origem de dados do Cloud SQL e do Cloud SQL para PostgreSQL através do 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

Substitua os valores de exemplo da seguinte forma: