Ativar a API Conversational Analytics

Nesta página, descrevemos as etapas para ativar a API Análises de conversação (acessada por geminidataanalytics.googleapis.com) no Google Cloud projeto. A API Conversational Analytics é o primeiro recurso da API Data Analytics com Gemini no console Google Cloud .

Antes de começar

Antes de usar a API Análises de conversação, você precisa ter um Google Cloud projeto que possa acessar os dados com que quer trabalhar. Para configurar seu projeto, siga estas etapas:

Identifique os dados que quer usar com a API Análises de conversação. Você pode usar fontes de dados como tabelas do BigQuery, Explores do Looker, relatórios do Looker Studio e dados do AlloyDB para PostgreSQL, GoogleSQL para Spanner, Cloud SQL para MySQL e Cloud SQL para PostgreSQL.
No console do Google Cloud, na página do seletor de projetos, crie um Google Cloud projeto que possa acessar os dados que você quer usar com a API Análises de conversação.

Observação: no momento, não há faturamento para a API Conversational Analytics.

Acessar o seletor de projetos

Requisitos do Looker e do Looker Studio Pro

Se você usar a API Análises de conversação com o Looker, sua instância do Looker precisará atender a requisitos específicos:

Para usar a API Análises de conversação com o Looker Studio Pro, sua assinatura do Pro precisa estar fora de um perímetro do VPC-SC.

Requisitos do AlloyDB

Se você usar a API Análises de conversação com o AlloyDB, sua instância do AlloyDB precisará atender a requisitos específicos. Conclua todas as etapas em Antes de começar.

Requisitos do Cloud SQL para MySQL

Se você usar a API Análises de conversação com o Cloud SQL para MySQL, sua instância do Cloud SQL precisará atender a requisitos específicos. Conclua todas as etapas em Antes de começar.

Requisitos do Cloud SQL para PostgreSQL

Se você usar a API Análises de conversação com o Cloud SQL para PostgreSQL, sua instância do Cloud SQL precisará atender a requisitos específicos. Conclua todas as etapas em Antes de começar.

Requisitos do Spanner

Se você usar a API Análises de conversação com o Spanner, sua instância do Spanner precisará atender a requisitos específicos. Conclua todas as etapas em Antes de começar.

Ative as APIs necessárias

Para usar a API Análises de conversação, ative um conjunto de APIs necessárias no Google Cloud projeto. Se você planeja usar a API Análises de conversação em um ambiente do Colab Enterprise, também será necessário ativar outras APIs.

APIs necessárias

Console

Ative as seguintes APIs no Google Cloud console do Google Cloud projeto que você vai usar com a API Análises de conversação.

Ativar a API Gemini Data Analytics

Ativar o Gemini for Google Cloud API

Ativar a API BigQuery

gcloud

Com a Google Cloud CLI, execute os seguintes gcloud services enable comandos para ativar a API Gemini Data Analytics, o Gemini for Google Cloud API e a API BigQuery, respectivamente:

gcloud services enable geminidataanalytics.googleapis.com --project=project_id
gcloud services enable cloudaicompanion.googleapis.com --project=project_id
gcloud services enable bigquery.googleapis.com --project=project_id

Nos comandos de exemplo da CLI gcloud anteriores, substitua project_id pelo Google Cloud ID do projeto.

APIs para o Colab Enterprise

Se você planeja usar a API Análises de conversação em um ambiente do Colab Enterprise, também ative as seguintes APIs:

Ativar a API Dataform

Ativar a API Compute Engine

Ativar a API Vertex AI

Conceder os papéis necessários

Para usar a API Análises de conversação, os principais (como usuários ou contas de serviço) exigem papéis do Identity and Access Management (IAM) que forneçam acesso à API e às fontes de dados subjacentes.

Para conceder esses papéis, use o Google Cloud console:

Acessar "Papéis"

Papéis do Gemini Data Analytics

Para permitir que os principais criem agentes da API Análises de conversação e usem o método de chat com estado para conversas, conceda os seguintes papéis do IAM:

Criador de agentes de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator): necessário para começar a criar agentes somente no BigQuery, no Looker e no Looker Studio Pro.
Gemini for Google Cloud User (roles/cloudaicompanion.user): necessário para usar o método de chat com estado para conversas.

Além disso, as permissões para ações como gerenciar agentes são controladas pelos papéis do Gemini Data Analytics, conforme descrito em Controle de acesso da API Análises de conversação com o IAM.

Papéis do BigQuery

Para permitir que os principais consultem fontes de dados do BigQuery pela API Análises de conversação, conceda os seguintes papéis do IAM:

Usuário do BigQuery (roles/bigquery.user): necessário para acessar dados no BigQuery.
Usuário do BigQuery Studio (roles/bigquery.studioUser): necessário se você usar o BigQuery Studio e a tela de dados.

Papéis do Looker

Para permitir que os principais consultem fontes de dados do Looker pela API Análises de conversação, conceda os seguintes papéis do IAM:

Usuário da instância do Looker (roles/looker.instanceUser): necessário para acessar dados de uma instância do Looker (Google Cloud Core).

Para usar a API Conversational Analytics e o recurso de análise de conversação, um usuário do Looker precisa receber um papel do Looker que contenha a permissão gemini_in_looker para os modelos com que ele interage.

Papéis de banco de dados

Para permitir que os principais consultem fontes de dados do AlloyDB, do Cloud SQL para MySQL, do Cloud SQL para PostgreSQL ou do Spanner pela API Análises de conversação, conceda os seguintes papéis do IAM:

Usuário do banco de dados do AlloyDB (roles/alloydb.databaseUser): necessário para acessar dados de uma instância do AlloyDB.
Usuário do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL Studio (roles/cloudsql.studioUser): necessário para usar o Google Cloud console para visualizar e gerenciar instâncias do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL.
Usuário da instância do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL (roles/cloudsql.instanceUser): necessário para se conectar a instâncias do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL.
Leitor de banco de dados do Spanner (roles/spanner.databaseReader): necessário para ler dados de um banco de dados do GoogleSQL para Spanner.

Configuração adicional para o VPC Service Controls

A API Análises de conversação está integrada ao VPC Service Controls. Você pode adicionar a API Análises de conversação aos seus perímetros de serviço para melhorar a segurança dos seus dados e serviços e ajudar a reduzir o risco de exfiltração de dados. Quando você inclui geminidataanalytics.googleapis.com como um serviço restrito em um perímetro, o VPC Service Controls protege a API Análises de conversação.

Proteger fontes de dados

Embora o perímetro de serviço restrinja o acesso à API Análises de conversação, você também precisa incluir os serviços de fonte de dados no mesmo perímetro de serviço para proteger os dados que essas fontes contêm. As fontes de dados comuns para a API Análises de conversação incluem o BigQuery, o Looker e o Looker Studio. Verifique se os serviços correspondentes a essas fontes de dados (por exemplo, bigquery.googleapis.com) também estão restritos no perímetro de serviço.

Permissões e papéis do IAM

Os perímetros do VPC Service Controls e os papéis do Identity and Access Management (IAM) funcionam juntos. O VPC Service Controls aplica limites de segurança ao redor do serviço, enquanto o IAM governa quem pode acessar recursos dentro do perímetro.

Mesmo quando o acesso está dentro de um perímetro protegido, os usuários ou as contas de serviço ainda exigem as permissões do IAM necessárias no serviço da API Análises de conversação e nas fontes de dados subjacentes (como conjuntos de dados do BigQuery ou instâncias do Looker) para realizar ações. A combinação do VPC Service Controls com o gerenciamento adequado do IAM é essencial para a segurança robusta dos fluxos de trabalho da API Análises de conversação.