Conceda funções e autorizações de IAM da API Conversational Analytics

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

A API Conversational Analytics usa a gestão de identidade e de acesso (IAM) para controlar o acesso à criação, gestão e interação com agentes de dados. Com o IAM, concede autorizações a principais (como utilizadores, grupos e contas de serviço) atribuindo funções aos principais. Cada função é uma coleção de uma ou mais autorizações que determinam as ações que um principal pode realizar.

Esta página descreve as funções de IAM predefinidas para a API Conversational Analytics. Pode atribuir estas funções de IAM na Google Cloud consola do projeto no qual a API Conversational Analytics está ativada. Para obter instruções detalhadas, consulte o artigo Conceder funções através da Google Cloud consola. Também pode usar a CLI do Google Cloud para conceder funções, conforme descrito em Conceda funções de IAM.

Antes de começar

Para receber as autorizações de que precisa para atribuir funções IAM da API Conversational Analytics, peça ao seu administrador para lhe conceder a função IAM de administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto em que a API Conversational Analytics está ativada. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Nota: as funções básicas da IAM também podem conter autorizações para atribuir funções da IAM da API Conversational Analytics. Não deve conceder funções básicas num ambiente de produção, mas pode concedê-las num ambiente de desenvolvimento ou de teste.

Vista geral das funções da IAM da API Conversational Analytics

A API Conversational Analytics fornece um conjunto de funções da IAM predefinidas. Estas funções permitem-lhe conceder autorizações para tarefas como criar e editar agentes, partilhar e gerir agentes, ver e conversar com agentes, e usar a API num modo de chat sem estado.

Nota: as funções de IAM da API Conversational Analytics controlam o acesso aos agentes e às respetivas configurações, e não aos dados subjacentes propriamente ditos.

As funções predefinidas do IAM para a API Conversational Analytics fazem parte do serviço geminidataanalytics. Os nomes técnicos destas funções seguem o padrão roles/geminidataanalytics.ROLE_NAME. Na Google Cloud consola, pode encontrar estas funções filtrando o serviço Gemini Data Analytics.

Pode atribuir funções do IAM da API Conversational Analytics ao nível do projeto.

Funções necessárias para tarefas comuns do utilizador

Para decidir que funções atribuir a um principal, considere as seguintes tarefas comuns do utilizador.

Crie novos agentes de dados

Atribua a função Criador de agentes de dados do Gemini Data Analytics aos utilizadores responsáveis pela criação de novos agentes de dados num projeto.

Faça a gestão das autorizações de agentes

Atribua a função Proprietário do agente de dados do Gemini Data Analytics aos utilizadores que precisam do nível de controlo mais elevado sobre um agente, incluindo a capacidade de gerir autorizações e partilhar ou eliminar agentes. Quando um utilizador cria um agente, o sistema concede automaticamente esta função a esse utilizador para o agente específico.

Edite as configurações do agente

Atribua a função Gemini Data Analytics Data Agent Editor aos utilizadores que modificam a configuração de um agente, como o respetivo contexto ou mapeamentos de origens de dados. Estes utilizadores não têm autorizações para partilhar nem eliminar o agente.

Converse no chat com agentes

Atribua a função Gemini Data Analytics Data Agent User a utilizadores ou aplicações que interagem principalmente com agentes fazendo perguntas e recebendo respostas.

Veja as configurações do agente

Atribua a função Leitor do agente de dados do Gemini Data Analytics aos utilizadores que precisam de acesso só de leitura para ver as configurações do agente.

Converse através do contexto inline

Atribua a função Utilizador de chat sem estado do Gemini Data Analytics a utilizadores ou aplicações que interagem com a API num modo sem estado, em que o utilizador fornece todo o contexto para a conversa em cada pedido.

Para ver uma lista de funções predefinidas e as autorizações que incluem, consulte o artigo Funções predefinidas para a API Conversational Analytics.

Funções predefinidas para a API Conversational Analytics

Nota: conceder a um utilizador acesso a um agente de dados não lhe permite ver conversas iniciadas por outros utilizadores. Por exemplo, a listagem de conversas para um agente só devolve conversas que foram criadas pelo utilizador atual.

A tabela seguinte descreve as funções predefinidas para a API Conversational Analytics. Se as funções predefinidas não oferecerem o conjunto de autorizações que quer, também pode criar as suas próprias funções personalizadas.

Função	Autorizações
Criador do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) Concede a um principal autorização para criar novos recursos de agente de dados num projeto específico. Quando um principal cria um agente, o sistema concede automaticamente a esse principal a função 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 controlo total sobre o ciclo de vida de qualquer agente no projeto, incluindo a partilha e a eliminação de agentes. Esta função destina-se a entidades fidedignas que podem gerir a partilha de agentes. Esta função herda todas as autorizações das funções dataAgentEditor, dataAgentUser e dataAgentViewer. Um principal com esta função pode partilhar e eliminar 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 autorização para modificar e gerir configurações de agentes existentes. Esta função herda todas as autorizações das funções dataAgentUser e dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.update
Utilizador do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser) Concede autorização para conversar com os agentes específicos aos quais o principal recebeu acesso. Esta função herda todas as autorizações da função dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat
Visualizador do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) Concede a um principal autorização só de leitura para listar e ver configurações de agentes. Esta função não permite conversar com agentes.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get
Utilizador do chat sem estado do Gemini Data Analytics (roles/geminidataanalytics.dataAgentStatelessUser) Concede a uma autorização principal para chamar a API Chat no modo sem estado. Com o chat sem estado, o contexto é fornecido diretamente no pedido, em vez de ser guardado explicitamente na configuração do agente durante a criação.	geminidataanalytics.chat

Conceda funções de IAM

Pode conceder funções de IAM da API Conversational Analytics a responsáveis através da Google Cloud consola ou da CLI Google Cloud.

consola

Para conceder uma função a um principal na Google Cloud consola, conclua os seguintes passos:

1. Na Google Cloud consola, aceda à página IAM.

   Aceda ao IAM

2. Clique em Conceder acesso.

3. No campo Novos membros, introduza o endereço de email do utilizador, do grupo ou da conta de serviço.

4. No menu Selecionar uma função, filtre por Gemini Data Analytics para ver as funções de IAM disponíveis para a API Conversational Analytics.

5. Selecione a função adequada, como Utilizador do agente de dados do Gemini Data Analytics.

6. Clique em Guardar.

gcloud

Para conceder funções através da CLI gcloud, conclua os seguintes passos:

1. Inicie sessão no Google Cloud e defina o seu projeto:

gcloud auth login
gcloud config set project project_id

1. Opcionalmente, para listar as funções de IAM da API Conversational Analytics que pode conceder para o seu projeto, use o comando gcloud iam list-grantable-roles da seguinte forma:

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

1. Conceda uma função a um principal através do comando gcloud projects add-iam-policy-binding.

• Para conceder uma função a um utilizador, use o seguinte comando:

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

• Para atribuir uma função 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 seu Google Cloud projeto.
• user_email: o endereço de email do utilizador, como [e-mail].
• service_account_email: o endereço de email da conta de serviço, como [e-mail].
• gda_grantable_role: a função do IAM da API Conversational Analytics específica que quer conceder, como geminidataanalytics.dataAgentCreator.