Esta página foi traduzida pela API Cloud Translation.

Controle de acesso da API Conversational Analytics com o IAM

A API Conversational Analytics usa o Identity and Access Management (IAM) para controle de acesso, permitindo 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.

Visão geral dos papéis do IAM da API Conversational Analytics

Os papéis predefinidos do IAM para a API Conversational Analytics oferecem controle granular sobre quem pode criar, gerenciar e interagir com agentes de dados. Nesta seção, explicamos como compartilhar agentes de dados atribuindo papéis do IAM e descrevemos os papéis do IAM necessários para outras tarefas comuns do usuário.

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

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

Um proprietário do agente concede as funções de editor e usuário do agente de dados a outros usuários.

Neste cenário, um analista de dados sênior com a função Criador do agente de dados do Gemini Data Analytics cria um agente. Quando um usuário cria um agente, ele recebe automaticamente o papel de 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 a ele definindo a política do IAM e concedendo os seguintes papéis aos membros da equipe:

Editor do agente de dados do Gemini Data Analytics: o proprietário do agente concede essa função a analistas de dados juniores. Com essa função, os analistas juniores podem editar a configuração do agente e conversar com ele.
Usuário do agente de dados do Gemini Data Analytics: o proprietário do agente concede essa função aos membros da equipe que não precisam editar a configuração do agente. Esse papel permite que os 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 outras partes 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 outras pessoas gerenciando as permissões 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.

Papéis predefinidos para a API Conversational Analytics

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`

Conceder papéis do IAM

É possível conceder papéis do IAM da API Conversational Analytics no nível do projeto ou para um agente específico. Conceder um papel no nível do projeto dá a um principal as mesmas permissões para todos os agentes nesse projeto, enquanto definir a política em um agente específico oferece um controle mais granular.

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

Conceder papéis a todos os agentes em um projeto

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

Console

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

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

Acessar IAM
Clique em Conceder acesso.
No campo Novos principais, insira o endereço de e-mail do usuário, grupo ou conta de serviço.
No menu Selecionar um papel, filtre por Gemini Data Analytics para visualizar os papéis do IAM disponíveis para a API Conversational Analytics.
Selecione o papel adequado, como Usuário do agente de dados do Gemini Data Analytics.
Clique em Salvar.

gcloud

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

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

gcloud auth login
gcloud config set project project_id

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"

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 test-user@gmail.com.
service_account_email: o endereço de e-mail da conta de serviço, como test-proj@example.domain.com.
gda_grantable_role: o papel do IAM da API Conversational Analytics específico que você quer conceder, como geminidataanalytics.dataAgentCreator.

Conceder papéis a um agente específico

Para gerenciar o acesso de um agente de dados específico, modifique programaticamente a política de permissão dele. Esse processo segue um padrão de leitura-modificação-gravação padrão, em que você lê a política atual, modifica e grava de volta.

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 acessar a política atual de um agente, envie uma solicitação POST ao 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 ao 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 buscar 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 test-user@gmail.com.

Para ver 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 amostra 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 amostra 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
)