Conceder permissões e papéis do IAM da API Conversational Analytics

Prévia particular

Este produto ou recurso está sujeito aos Termos das Soluções 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. Você encontra mais detalhes nas descrições das fases de lançamento.

A API Conversational Analytics usa o Identity and Access Management (IAM) para controlar o acesso à criação, ao gerenciamento e à interação com agentes de dados. Com o IAM, você concede permissões a principais (como usuários, grupos e contas de serviço) ao atribuir papéis a eles. Cada função é um conjunto de uma ou mais permissões que determinam quais ações um principal pode realizar.

Nesta página, descrevemos os papéis predefinidos do IAM para a API Conversational Analytics. Você pode atribuir esses papéis do IAM no console do Google Cloud para o projeto em que a API Conversational Analytics está ativada. Para instruções detalhadas, consulte Conceder papéis usando o console do Google Cloud . Também é possível usar a CLI do Google Cloud para conceder papéis, conforme descrito em Conceder papéis do IAM.

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 Conversational Analytics

A API Conversational Analytics oferece um conjunto de papéis predefinidos do IAM. Com esses papéis, é possível conceder permissões para tarefas como criar e editar agentes, compartilhar e gerenciar agentes, visualizar e conversar com agentes e usar a API em um modo de chat sem estado.

Observação: os papéis do IAM da API Conversational Analytics controlam o acesso aos agentes e às configurações deles, não aos dados subjacentes.

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.

É possível atribuir papéis do IAM da API Conversational Analytics no nível do projeto.

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

Para decidir quais papéis atribuir a um principal, considere as seguintes tarefas comuns do usuário.

Criar novos agentes de dados

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

Gerenciar permissões de agente

Atribua a função Proprietário do agente de dados aos usuários que precisam do nível mais alto de controle sobre um agente, incluindo a capacidade de gerenciar permissões e compartilhar ou excluir agentes. Quando um usuário cria um agente, o sistema concede automaticamente essa função a ele para o agente específico.

Editar configurações do agente

Atribua a função Editor do agente de dados 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 a função Usuário do agente de dados 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 aos usuários que precisam de acesso somente leitura para visualizar as configurações do agente.

Conversar usando contexto inline

Atribua a função Usuário sem estado do agente de dados a aplicativos ou usuários 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.

Para uma lista de papéis predefinidos e as permissões que eles incluem, consulte Papéis predefinidos para a API Conversational Analytics.

Papéis predefinidos para a API Conversational Analytics

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 sem estado do agente de dados 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 a principais usando o console do Google Cloud ou a CLI do Google Cloud.

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 Conversational Analytics específico que você quer conceder, como geminidataanalytics.dataAgentCreator.