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 e configurar ligações aos seus dados no Looker, BigQuery e Looker Studio 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 do 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 N/A 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 com 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 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 estabelecer ligação 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 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 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 de 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 exemplo de código seguinte 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 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 exemplo de código seguinte 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 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.

Faça a associação ao Looker Studio com a 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.