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

Os desenvolvedores podem usar a Conversational Analytics API, acessada pelo geminidataanalytics.googleapis.com, para criar uma interface de chat ou um agente de dados com tecnologia de IA que responda a perguntas sobre dados estruturados no BigQuery, no Looker e no Looker Studio usando linguagem natural.

Nesta página, descrevemos como fazer a autenticação na API Conversational Analytics e configurar conexões com seus dados no Looker, no BigQuery e no Looker Studio 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/v1alpha/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 /v1alpha/projects/{billing_project}/locations/global/dataAgents.
    • Para listar os agentes de dados atuais, use o método GET e o caminho do recurso /v1alpha/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:

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 a opção IP particular do Looker (Google Cloud Core) precisam fazer a autenticação com um token de acesso.

Só é possível se conectar a uma análise do Looker por vez com a API Conversational Analytics

Autenticação 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. Os clientes que usam a opção IP privado do Looker (Google Cloud Core) não podem usar esse método e precisam se autenticar com um token de acesso.

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 administrador - 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

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 ao BigQuery com a API Conversational Analytics, autentique seu projeto do BigQuery e 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, é possível se conectar e consultar até 10 tabelas do BigQuery por vez.

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

Depois de autenticar seu projeto do BigQuery, você pode configurar a API Conversational Analytics para acessar dados no BigQuery fazendo solicitações HTTP diretas. O exemplo de código a seguir demonstra como especificar os detalhes da fonte de dados do BigQuery no corpo da solicitação HTTP.

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "bigquery-public-data",
          "datasetId": "san_francisco",
          "tableId": "street_trees"
        }
      ]
    }
}

Substitua os valores de exemplo da seguinte forma:

  • bigquery-public-data: ID do seu projeto do BigQuery
  • san_francisco: ID do conjunto de dados do BigQuery
  • street_trees: 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 demonstra como autenticar sua Conta do Google no BigQuery dentro do Colaboratory e configurar a API Conversational Analytics para acessar uma fonte de dados do BigQuery.

from google.colab import auth
auth.authenticate_user()

bq_project_id = "YOUR-PROJECT-ID" # @param {type:"string"}
bq_dataset_id = "YOUR-DATASET-ID" # @param {type:"string"}
bq_table_id = "YOUR-TABLE-ID" # @param {type:"string"}

# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = bq_project_id
bigquery_table_reference.dataset_id = bq_dataset_id
bigquery_table_reference.table_id = bq_table_id

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference]

Substitua os valores de exemplo da seguinte forma:

  • YOUR-PROJECT-ID: ID do seu projeto do BigQuery
  • YOUR-DATASET-ID: o ID do conjunto de dados do BigQuery.
  • YOUR-TABLE-ID: o ID da sua tabela do BigQuery

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.