Controle de acesso da API Conversational Analytics com o IAM

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

A API Análises de conversação usa o Identity and Access Management (IAM) para controle de acesso, o que permite compartilhar agentes de dados e controlar quem tem permissão para criar, gerenciar e interagir com eles. Nesta página, descrevemos os papéis predefinidos do IAM que podem ser atribuídos a principais (como usuários, grupos e contas de serviço) para conceder essas permissões.

Antes de começar

Para receber as permissões necessárias para atribuir papéis do IAM da API Conversational Analytics, peça ao administrador para conceder a você o papel Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto em que a API Conversational Analytics está ativada. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Observação: os papéis básicos do IAM também podem conter permissões para atribuir papéis do IAM da API Conversational Analytics. Não conceda papéis básicos em um ambiente de produção, mas é possível fazer isso em um ambiente de desenvolvimento ou de teste.

Visão geral dos papéis do IAM da API Análises de conversação

Os papéis predefinidos do IAM para a API Análises de conversação oferecem controle granular sobre quem pode criar, gerenciar e interagir com agentes de dados. Esta seção explica como compartilhar agentes de dados atribuindo papéis do IAM e descreve os papéis do IAM necessários para outras tarefas comuns do usuário.

**Observação**: O papel queryDataUser é compatível com bancos de dados na nuvem (AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL).

Como funciona o compartilhamento de agentes

É possível conceder papéis no nível do projeto para fornecer permissões para todos os agentes em um projeto. Para controlar o acesso a um agente específico, um proprietário do agente (um principal com o papel Proprietário do agente de dados do Gemini Data Analytics) pode modificar a política do IAM desse agente de maneira programática.

Importante:os papéis do IAM da API Análises de conversação controlam o acesso aos agentes e às configurações deles, não às fontes de dados subjacentes. Quando um usuário interage com um agente, a API consulta a fonte de dados conectada (como o Looker ou o BigQuery) usando as credenciais desse usuário. Portanto, para conversar com um agente, o usuário precisa ter as seguintes permissões:

• Um papel do IAM da API Análises de conversação adequado para acessar o agente
• Permissões suficientes na fonte de dados (por exemplo, no Looker ou no BigQuery) para acessar os dados que estão sendo consultados

O diagrama a seguir mostra como um proprietário do agente pode gerenciar o acesso a um agente específico:

Nesse cenário, um analista de dados sênior com o papel Criador do agente de dados do Gemini Data Analytics cria um agente. Quando um usuário cria um agente, ele recebe automaticamente o papel Proprietário do agente de dados do Gemini Data Analytics para esse agente. Como proprietário do agente, o analista de dados sênior gerencia o acesso ao agente definindo a política do IAM e concede os seguintes papéis aos membros da equipe:

• Editor do agente de dados do Gemini Data Analytics: o proprietário do agente concede esse papel a analistas de dados juniores. Esse papel permite que os analistas juniores editem a configuração do agente e conversem com ele.
• Usuário do agente de dados do Gemini Data Analytics: o proprietário do agente concede esse papel aos membros da equipe que não precisam editar a configuração do agente. Esse papel permite que esses membros da equipe conversem com o agente.

Papéis necessários para tarefas comuns do usuário

Para ajudar você a decidir quais papéis atribuir, considere as seguintes tarefas comuns do usuário:

Criar novos agentes de dados

Atribua o papel Criador do agente de dados do Gemini Data Analytics aos usuários responsáveis por criar novos agentes de dados em um projeto.

Compartilhar agentes

Atribua o papel Proprietário do agente de dados do Gemini Data Analytics aos usuários que precisam compartilhar agentes com outros principais gerenciando as permissões do agente.

Gerenciar permissões de agente

Atribua o papel Proprietário do agente de dados do Gemini Data Analytics aos usuários que precisam compartilhar agentes com outros usuários gerenciando as permissões do agente ou que precisam do nível mais alto de controle sobre um agente, incluindo a capacidade de excluir agentes. Quando um usuário cria um agente, o sistema concede automaticamente esse papel a ele para o agente específico.

Editar configurações do agente

Atribua o papel Editor do agente de dados do Gemini Data Analytics aos usuários que modificam a configuração de um agente, como o contexto ou os mapeamentos de fontes de dados. Esses usuários não têm permissão para compartilhar ou excluir o agente.

Conversar com agentes

Atribua o papel Usuário do agente de dados do Gemini Data Analytics a usuários ou aplicativos que interagem principalmente com agentes fazendo perguntas e recebendo respostas.

Visualizar configurações do agente

Atribua o papel de Leitor do agente de dados do Gemini Data Analytics aos usuários que precisam de acesso somente leitura para visualizar as configurações do agente.

Conversar usando contexto inline

Atribua o papel Usuário de chat sem estado do Gemini Data Analytics a usuários ou aplicativos que interagem com a API em um modo sem estado, em que o usuário fornece todo o contexto da conversa em cada solicitação.

Consultar dados usando linguagem natural

Atribua o papel Usuário de dados de consulta do Gemini Data Analytics a usuários ou aplicativos que precisam usar linguagem natural para consultar dados e criar aplicativos de dados. Esse papel se aplica apenas a bancos de dados na nuvem, ou seja, AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL.

Papéis predefinidos para a API Análises de conversação

Observação: conceder acesso a um agente de dados não permite que o usuário veja conversas iniciadas por outras pessoas. Por exemplo, ao listar conversas de um agente, somente as conversas criadas pelo usuário atual são retornadas.

A tabela a seguir descreve os papéis predefinidos da API Conversational Analytics. Se os papéis predefinidos não fornecerem o conjunto de permissões desejado, você também poderá criar seus próprios papéis personalizados.

Papel	Permissões
Criador do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) Concede a um principal permissão para criar novos recursos de agente de dados em um projeto específico. Quando um principal cria um agente, o sistema concede automaticamente a ele o papel dataAgentOwner para o agente específico.	geminidataanalytics.dataAgents.create
Proprietário do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) Concede a um principal controle total sobre o ciclo de vida de qualquer agente no projeto, incluindo compartilhamento e exclusão de agentes. Esse papel é para principais confiáveis que podem gerenciar o compartilhamento de agentes. Esse papel herda todas as permissões das funções dataAgentEditor, dataAgentUser e dataAgentViewer. Um principal com essa função pode compartilhar e excluir agentes.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.update geminidataanalytics.dataAgents.delete geminidataanalytics.dataAgents.getIamPolicy geminidataanalytics.dataAgents.setIamPolicy
Editor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor) Concede permissão para modificar e gerenciar configurações de agentes atuais. Esse papel herda todas as permissões dos papéis dataAgentUser e dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.update
Usuário do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser) Concede permissão para conversar com os agentes específicos a que o principal tem acesso. Esse papel herda todas as permissões do papel dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat
Leitor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) Concede a um principal permissão somente leitura para listar e visualizar configurações de agente. Esse papel não permite conversar com agentes.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get
Usuário de chat sem estado do Gemini Data Analytics (roles/geminidataanalytics.dataAgentStatelessUser) Concede a um principal permissão para chamar a API Chat no modo sem estado. Com o chat sem estado, o contexto é fornecido diretamente na solicitação, em vez de ser salvo explicitamente na configuração do agente durante a criação.	geminidataanalytics.chat
Usuário de dados de consulta do Gemini Data Analytics (roles/geminidataanalytics.queryDataUser) Concede a um principal permissão para usar linguagem natural para consultar dados e criar aplicativos de dados usando a API QueryData. Esse papel se aplica apenas a bancos de dados na nuvem, ou seja, AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL.	geminidataanalytics.locations.queryData

Conceder papéis do IAM

É possível conceder papéis do IAM da API Análises de conversação no nível do projeto ou para um agente específico. A concessão de um papel no nível do projeto oferece a um principal as mesmas permissões para todos os agentes nesse projeto, enquanto a definição da política em um agente específico oferece um controle mais granular.

Os papéis predefinidos do IAM para a API Análises de conversação fazem parte do serviço geminidataanalytics. Os nomes técnicos dessas funções seguem o padrão roles/geminidataanalytics.ROLE_NAME. No Google Cloud console do, é possível encontrar essas funções filtrando o serviço Gemini Data Analytics.

Conceder papéis para todos os agentes em um projeto

Use o Google Cloud console do Google Cloud ou a Google Cloud CLI para conceder papéis para um projeto inteiro.

Console

Para conceder um papel a um principal no console do Google Cloud , siga estas etapas:

1. No console do Google Cloud , acesse a página IAM.

   Acessar IAM

2. Clique em Conceder acesso.

3. No campo Novos principais, insira o endereço de e-mail do usuário, grupo ou conta de serviço.

4. No menu Selecionar um papel, filtre por Gemini Data Analytics para visualizar os papéis do IAM disponíveis para a API Conversational Analytics.

5. Selecione o papel adequado, como Usuário do agente de dados do Gemini Data Analytics.

6. Clique em Salvar.

gcloud

Para conceder papéis usando a gcloud CLI, siga estas etapas:

1. Faça login no Google Cloud e defina seu projeto:

gcloud auth login
gcloud config set project project_id

1. Se quiser listar os papéis do IAM da API Conversational Analytics que podem ser concedidos ao seu projeto, use o comando gcloud iam list-grantable-roles da seguinte maneira:

gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/project_id --filter "geminidataanalytics"

1. Conceda um papel a um principal usando o comando gcloud projects add-iam-policy-binding.

• Para conceder um papel a um usuário, use o seguinte comando:

gcloud projects add-iam-policy-binding project_id --member='user:user_email' --role='roles/gda_grantable_role'

• Para atribuir um papel a uma conta de serviço, use o seguinte comando:

gcloud projects add-iam-policy-binding project_id --member='serviceAccount:service_account_email' --role='roles/gda_grantable_role'

Nas instruções anteriores, substitua os valores de exemplo da seguinte forma:

• project_id: o ID do projeto do Google Cloud .
• user_email: o endereço de e-mail do usuário, como [e-mail].
• service_account_email: o endereço de e-mail da conta de serviço, como [e-mail].
• gda_grantable_role: o papel do IAM da API Análises de conversação específico que você quer conceder, como geminidataanalytics.dataAgentCreator.

Conceder papéis para um agente específico

Para gerenciar o acesso a um agente de dados específico, é necessário modificar a política de permissão desse agente de maneira programática. Esse processo segue um padrão de leitura-modificação-gravação em que você lê a política atual, a modifica e a grava novamente.

Importante: o método setIamPolicy substitui qualquer política atual no agente. Para preservar as permissões atuais ao conceder novos papéis, é necessário chamar getIAMPolicy primeiro para buscar a política atual, modificar essa política e transmitir o objeto de política atualizado na chamada para setIamPolicy.

Os exemplos a seguir mostram os corpos de solicitação para receber e definir políticas do IAM para um agente de dados.

HTTP

Para receber a política atual de um agente, envie uma solicitação POST para o endpoint :getIamPolicy com o seguinte corpo da solicitação:

{
  "resource": "projects/project_id/locations/global/dataAgents/agent_id"
}

Para definir a política de um agente, envie uma solicitação POST para o endpoint :setIamPolicy com o seguinte corpo da solicitação:

{
  "policy": {
    "bindings": [
      {
        "role": "role",
        "members": [
          "user:email"
        ]
      }
    ]
  }
}

Substitua:

• project_id: o ID do projeto do Google Cloud .
• agent_id: o ID do agente de dados para o qual receber ou definir a política.
• role: o papel a ser concedido, como roles/geminidataanalytics.dataAgentUser.
• email: o endereço de e-mail do usuário, como [e-mail].

Para exemplos completos, consulte Acessar a política do IAM de um agente de dados e Definir a política do IAM de um agente de dados.

SDK do Python

Para receber a política atual de um agente, use o método get_iam_policy, como na solicitação de exemplo a seguir:

resource = "projects/project_id/locations/global/dataAgents/agent_id"
request = iam_policy_pb2.GetIamPolicyRequest(
            resource=resource,
        )

Para definir a política de um agente, use o método set_iam_policy, como na solicitação de exemplo a seguir:

resource = "projects/project_id/locations/global/dataAgents/agent_id"
policy = policy_pb2.Policy(
    bindings=[
        policy_pb2.Binding(
            role="role",
            members=["user:email"]
        )
    ]
)
request = iam_policy_pb2.SetIamPolicyRequest(
    resource=resource,
    policy=policy
)

Substitua:

• project_id: o ID do projeto do Google Cloud .
• agent_id: o ID do agente de dados para o qual receber ou definir a política.
• role: o papel a ser concedido, como roles/geminidataanalytics.dataAgentUser.
• email: o endereço de e-mail do usuário, como [e-mail].

Para exemplos completos, consulte Acessar a política do IAM de um agente de dados e Definir a política do IAM de um agente de dados.