Controlo de acesso da API Conversational Analytics com o IAM

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 acesso (IAM) para o controlo de acesso, o que lhe permite partilhar agentes de dados e controlar quem tem autorização para os criar, gerir e interagir com eles. Esta página descreve as funções de IAM predefinidas que pode atribuir a principais (como utilizadores, grupos e contas de serviço) para conceder estas autorizações.

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 do IAM da API Conversational Analytics

As funções predefinidas da IAM para a API Conversational Analytics oferecem um controlo detalhado sobre quem pode criar, gerir e interagir com agentes de dados. Esta secção explica como partilhar agentes de dados através da atribuição de funções da IAM e descreve as funções da IAM necessárias para outras tarefas comuns do utilizador.

Como funciona a partilha de agentes

Pode conceder funções ao nível do projeto para fornecer autorizações a todos os agentes num projeto. Em alternativa, para controlar o acesso a um agente específico, um proprietário do agente (um principal com a função Gemini Data Analytics Data Agent Owner) pode modificar a política de IAM desse agente através de programação.

Importante: as funções IAM da API Conversational Analytics controlam o acesso aos agentes e às respetivas configurações, e não às origens de dados subjacentes. Quando um utilizador interage com um agente, a API consulta a origem de dados associada (como o Looker ou o BigQuery) através das credenciais desse utilizador. Por conseguinte, para conversar com um agente com êxito, um utilizador tem de ter as seguintes autorizações:

• Uma função IAM da API Conversational Analytics adequada para aceder ao agente
• Autorizações suficientes na origem de dados (por exemplo, no Looker ou no BigQuery) para aceder aos dados que estão a ser consultados

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

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 utilizador cria um agente, recebe automaticamente a função Proprietário do agente de dados do Gemini Data Analytics para esse agente. Enquanto proprietário do agente, o analista de dados sénior gere o acesso ao agente definindo a respetiva política de IAM e concede as seguintes funções aos membros da equipa:

• Editor do agente de dados do Gemini Data Analytics: o proprietário do agente atribui esta função a analistas de dados juniores. Esta função permite que os analistas juniores editem a configuração do agente e conversem com o agente.
• Utilizador do agente de dados do Gemini Data Analytics: o proprietário do agente atribui esta função aos membros da equipa que não precisam de poder editar a configuração do agente. Esta função permite que esses membros da equipa conversem com o agente.

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

Para ajudar a decidir que funções atribuir, considere as seguintes tarefas comuns dos utilizadores:

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.

Partilhe agentes

Atribua a função Proprietário do agente de dados do Gemini Data Analytics aos utilizadores que precisam de partilhar agentes com outros responsáveis através da gestão das autorizações dos agentes.

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 de partilhar agentes com outros utilizadores através da gestão das autorizações dos agentes ou que precisam do nível de controlo mais elevado sobre um agente, incluindo a capacidade de 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.

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 da IAM da API Conversational Analytics ao nível do projeto ou para um agente específico. A concessão de uma função ao nível do projeto dá a um principal as mesmas autorizações para todos os agentes nesse projeto, enquanto a definição da política num agente específico oferece um controlo mais detalhado.

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.

Conceda funções a todos os agentes num projeto

Use a Google Cloud consola ou a Google Cloud CLI para conceder funções a um projeto inteiro.

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.

   Aceder 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.

Conceda funções a um agente específico

Para gerir o acesso de um agente de dados específico, tem de modificar programaticamente a política de autorização desse agente. Este processo segue um padrão de leitura-modificação-escrita padrão, em que lê a política atual, modifica-a e, em seguida, volta a escrevê-la.

Importante: o método setIamPolicy substitui qualquer política existente no agente. Para preservar as autorizações existentes quando concede novas funções, tem de chamar primeiro getIAMPolicy para obter a política existente, modificar essa política e, em seguida, transmitir o objeto de política atualizado na chamada para setIamPolicy.

Os exemplos seguintes mostram os corpos dos pedidos para obter e definir políticas de IAM para um agente de dados.

HTTP

Para obter a política existente de um agente, envie um pedido POST para o ponto final :getIamPolicy com o seguinte corpo do pedido:

{
  "resource": "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
}

Para definir a política de um agente, envie um pedido POST para o ponto final :setIamPolicy com o seguinte corpo do pedido:

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

Substitua o seguinte:

• PROJECT_ID: o ID do seu Google Cloud projeto.
• AGENT_ID: o ID do agente de dados para o qual obter ou definir a política.
• ROLE: a função a conceder, como roles/geminidataanalytics.dataAgentUser.
• EMAIL: o endereço de email do utilizador, como [e-mail].

Para ver exemplos completos, consulte os artigos Obtenha a política IAM para um agente de dados e Defina a política IAM para um agente de dados.

SDK Python

Para obter a política existente de um agente, use o método get_iam_policy, como no seguinte pedido de exemplo:

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 no seguinte pedido de exemplo:

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 o seguinte:

• PROJECT_ID: o ID do seu Google Cloud projeto.
• AGENT_ID: o ID do agente de dados para o qual obter ou definir a política.
• ROLE: a função a conceder, como roles/geminidataanalytics.dataAgentUser.
• EMAIL: o endereço de email do utilizador, como [e-mail].

Para ver exemplos completos, consulte os artigos Obtenha a política IAM para um agente de dados e Defina a política IAM para um agente de dados.