Control de acceso a la API de Conversational Analytics con IAM

Este producto o función está sujeto a las "Condiciones de la Oferta de la Fase Previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles "sin modificaciones" y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

La API de Conversational Analytics usa Identity and Access Management (IAM) para el control de acceso, lo que te permite compartir agentes de datos y controlar quién tiene permiso para crearlos, administrarlos e interactuar con ellos. En esta página, se describen los roles de IAM predefinidos que puedes asignar a las principales (como usuarios, grupos y cuentas de servicio) para otorgar estos permisos.

Antes de comenzar

Para obtener los permisos que necesitas para asignar roles de IAM de la API de Conversational Analytics, pídele a tu administrador que te otorgue el rol de IAM de Administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin) en el proyecto en el que está habilitada la API de Conversational Analytics. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Nota: Los roles básicos de IAM también pueden contener permisos para asignar roles de IAM de la API de Conversational Analytics. No deberías otorgar roles básicos en un entorno de producción, pero puedes otorgarlos en un entorno de desarrollo o de prueba.

Descripción general de los roles de IAM de la API de Conversational Analytics

Los roles de IAM predefinidos para la API de Conversational Analytics proporcionan un control detallado sobre quién puede crear, administrar y usar agentes de datos. En esta sección, se explica cómo compartir agentes de datos asignando roles de IAM y se describen los roles de IAM que se requieren para otras tareas comunes del usuario.

Cómo funciona el uso compartido de agentes

Puedes otorgar roles a nivel del proyecto para proporcionar permisos a todos los agentes dentro de un proyecto. Para controlar el acceso a un agente específico, el propietario del agente (un principal con el rol de Propietario del agente de datos de Gemini Data Analytics) puede modificar la política de IAM de ese agente de forma programática.

Importante: Los roles de IAM de la API de Conversational Analytics controlan el acceso a los agentes y sus configuraciones, no a las fuentes de datos subyacentes. Cuando un usuario interactúa con un agente, la API consulta la fuente de datos conectada (como Looker o BigQuery) con las credenciales de ese usuario. Por lo tanto, para chatear con un agente, el usuario debe tener los siguientes permisos:

• Un rol de IAM de la API de Conversational Analytics adecuado para acceder al agente
• Permisos suficientes en la fuente de datos (por ejemplo, en Looker o BigQuery) para acceder a los datos sobre los que se realiza la consulta

En el siguiente diagrama, se muestra cómo el propietario de un agente puede administrar el acceso a un agente específico:

En este caso, un analista de datos sénior con el rol de Creador de agentes de datos de análisis de datos de Gemini crea un agente. Cuando un usuario crea un agente, se le otorga automáticamente el rol de Propietario del agente de datos de Gemini Data Analytics para ese agente. Como propietario del agente, el analista de datos sénior administra el acceso al agente configurando su política de IAM y otorga los siguientes roles a los miembros del equipo:

• Editor de agentes de análisis de datos de Gemini: El propietario del agente otorga este rol a los analistas de datos junior. Este rol permite que los analistas junior editen la configuración del agente y chateen con él.
• Usuario del agente de datos de análisis de datos de Gemini: El propietario del agente otorga este rol a los miembros del equipo que no necesitan poder editar la configuración del agente. Este rol permite que los miembros del equipo chateen con el agente.

Roles obligatorios para las tareas comunes del usuario

Para ayudarte a decidir qué roles asignar, considera las siguientes tareas comunes de los usuarios:

Crea agentes de datos nuevos

Asigna el rol de creador de agentes de datos de Gemini Data Analytics a los usuarios responsables de crear nuevos agentes de datos dentro de un proyecto.

Compartir agentes

Asigna el rol de Propietario del agente de datos de Gemini Data Analytics a los usuarios que necesiten compartir agentes con otros principales administrando los permisos de los agentes.

Administra los permisos de los agentes

Asigna el rol de Propietario del agente de datos de Gemini Data Analytics a los usuarios que necesiten compartir agentes con otros usuarios administrando los permisos de los agentes o que necesiten el nivel más alto de control sobre un agente, incluida la capacidad de borrar agentes. Cuando un usuario crea un agente, el sistema le otorga automáticamente este rol para el agente específico.

Edita la configuración del agente

Asigna el rol de Editor del agente de datos de Gemini Data Analytics a los usuarios que modifican la configuración de un agente, como su contexto o las asignaciones de fuentes de datos. Estos usuarios no tienen permiso para compartir o borrar el agente.

Chatea con agentes

Asigna el rol de Usuario del agente de datos de Gemini Data Analytics a los usuarios o las aplicaciones que interactúan principalmente con los agentes haciendo preguntas y recibiendo respuestas.

Cómo ver la configuración del agente

Asigna el rol de Visualizador del agente de datos de Gemini Data Analytics a los usuarios que necesiten acceso de solo lectura para ver la configuración del agente.

Chatea con contexto intercalado

Asigna el rol Gemini Data Analytics Stateless Chat User a los usuarios o las aplicaciones que interactúan con la API en modo sin estado, en el que el usuario proporciona todo el contexto de la conversación en cada solicitud.

Roles predefinidos para la API de Conversational Analytics

Nota: Otorgar acceso a un usuario a un agente de datos no le permite ver las conversaciones que iniciaron otros usuarios. Por ejemplo, si se enumeran las conversaciones de un agente, solo se mostrarán las que creó el usuario actual.

En la siguiente tabla, se describen los roles predefinidos para la API de Conversational Analytics. Si las funciones predefinidas no proporcionan el conjunto de permisos que deseas, también puedes crear tus propias funciones personalizadas.

Rol	Permisos
Creador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) Otorga a un principal permiso para crear recursos de agentes de datos nuevos en un proyecto específico. Cuando una principal crea un agente, el sistema le otorga automáticamente el rol de dataAgentOwner para ese agente específico.	geminidataanalytics.dataAgents.create
Propietario del agente de datos de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentOwner) Otorga a un principal control total sobre el ciclo de vida de cualquier agente dentro del proyecto, lo que incluye compartir y borrar agentes. Este rol es para las principales de confianza que pueden administrar el uso compartido de agentes. Este rol hereda todos los permisos de los roles dataAgentEditor, dataAgentUser y dataAgentViewer. Una principal con este rol puede compartir y borrar agentes.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.update geminidataanalytics.dataAgents.delete geminidataanalytics.dataAgents.getIamPolicy geminidataanalytics.dataAgents.setIamPolicy
Editor de agentes de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentEditor) Otorga permiso para modificar y administrar la configuración de agentes existentes. Este rol hereda todos los permisos de los roles dataAgentUser y dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.update
Usuario del agente de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentUser) Otorga permiso para chatear con los agentes específicos a los que se les otorgó acceso a la principal. Este rol hereda todos los permisos del rol dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat
Visualizador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) Otorga a un principal permiso de solo lectura para enumerar y ver la configuración del agente. Este rol no permite chatear con agentes.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get
Usuario de chat sin estado de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentStatelessUser) Otorga permiso a un principal para llamar a la API de Chat en modo sin estado. Con el chat sin estado, el contexto se proporciona directamente en la solicitud en lugar de guardarse de forma explícita en la configuración del agente durante la creación.	geminidataanalytics.chat

Asigna roles de IAM

Puedes otorgar roles de IAM de la API de Conversational Analytics a nivel del proyecto o para un agente específico. Otorgar un rol a nivel del proyecto le brinda a un principal los mismos permisos para todos los agentes de ese proyecto, mientras que establecer la política en un agente específico proporciona un control más detallado.

Los roles de IAM predefinidos para la API de Conversational Analytics forman parte del servicio geminidataanalytics. Los nombres técnicos de estos roles siguen el patrón roles/geminidataanalytics.ROLE_NAME. En la Google Cloud consola, puedes encontrar estos roles si filtras por el servicio Gemini Data Analytics.

Otorga roles para todos los agentes de un proyecto

Usa la consola de Google Cloud o Google Cloud CLI para otorgar roles para todo un proyecto.

Console

Para otorgar un rol a una principal en la consola de Google Cloud , completa los siguientes pasos:

1. En la consola de Google Cloud , ve a la página IAM.

   Ir a IAM

2. Haz clic en Otorgar acceso.

3. En el campo Nuevos principales, ingresa la dirección de correo electrónico del usuario, el grupo o la cuenta de servicio.

4. En el menú Seleccionar un rol, filtra por Gemini Data Analytics para ver los roles de IAM disponibles para la API de Conversational Analytics.

5. Selecciona el rol adecuado, como Usuario del agente de datos de Gemini Data Analytics.

6. Haz clic en Guardar.

gcloud

Para otorgar roles con gcloud CLI, completa los siguientes pasos:

1. Accede a Google Cloud y configura tu proyecto:

gcloud auth login
gcloud config set project project_id

1. De manera opcional, para enumerar los roles de IAM de la API de Conversational Analytics que puedes otorgar para tu proyecto, usa el comando gcloud iam list-grantable-roles de la siguiente manera:

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

1. Otorga un rol a una principal con el comando gcloud projects add-iam-policy-binding.

• Para otorgar un rol a un usuario, usa el siguiente comando:

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

• Para asignar un rol a una cuenta de servicio, usa el siguiente comando:

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

En las instrucciones anteriores, reemplaza los valores de muestra de la siguiente manera:

• project_id: El ID de tu proyecto de Google Cloud .
• user_email: Es la dirección de correo electrónico del usuario, como [e-mail].
• service_account_email: Es la dirección de correo electrónico de la cuenta de servicio, como [e-mail].
• gda_grantable_role: Es el rol de IAM específico de la API de Conversational Analytics que deseas otorgar, como geminidataanalytics.dataAgentCreator.

Otorga roles para un agente específico

Para administrar el acceso de un agente de datos específico, debes modificar de forma programática la política de permisos de ese agente. Este proceso sigue un patrón de lectura-modificación-escritura estándar en el que lees la política actual, la modificas y, luego, la vuelves a escribir.

Importante: El método setIamPolicy anula cualquier política existente en el agente. Para conservar los permisos existentes cuando otorgues roles nuevos, primero debes llamar a getIAMPolicy para recuperar la política existente, modificarla y, luego, pasar el objeto de política actualizado en la llamada a setIamPolicy.

En los siguientes ejemplos, se muestran los cuerpos de solicitud para obtener y establecer políticas de IAM para un agente de datos.

HTTP

Para obtener la política existente de un agente, envía una solicitud POST al extremo :getIamPolicy con el siguiente cuerpo de solicitud:

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

Para establecer la política de un agente, envía una solicitud POST al extremo :setIamPolicy con el siguiente cuerpo de la solicitud:

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

Reemplaza lo siguiente:

• PROJECT_ID: El ID de tu proyecto de Google Cloud .
• AGENT_ID: Es el ID del agente de datos para el que se obtendrá o establecerá la política.
• ROLE: Es el rol que se otorgará, como roles/geminidataanalytics.dataAgentUser.
• EMAIL: Es la dirección de correo electrónico del usuario, como [e-mail].

Para ver ejemplos completos, consulta Cómo obtener la política de IAM para un agente de datos y Cómo establecer la política de IAM para un agente de datos.

Python SDK

Para obtener la política existente de un agente, usa el método get_iam_policy, como en la siguiente solicitud de muestra:

resource = "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
request = iam_policy_pb2.GetIamPolicyRequest(
            resource=resource,
        )

Para establecer la política de un agente, usa el método set_iam_policy, como en la siguiente solicitud de ejemplo:

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
)

Reemplaza lo siguiente:

• PROJECT_ID: El ID de tu proyecto de Google Cloud .
• AGENT_ID: Es el ID del agente de datos para el que se obtendrá o establecerá la política.
• ROLE: Es el rol que se otorgará, como roles/geminidataanalytics.dataAgentUser.
• EMAIL: Es la dirección de correo electrónico del usuario, como [e-mail].

Para ver ejemplos completos, consulta Cómo obtener la política de IAM para un agente de datos y Cómo establecer la política de IAM para un agente de datos.