Control de acceso a la API de Conversational Analytics con IAM

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.

Además de IAM, puedes usar políticas de la organización para establecer restricciones en los recursos de la API de Conversational Analytics y controlar cómo se pueden usar a nivel de la organización, la carpeta o el proyecto.

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 y administrar agentes de datos, y quién puede interactuar con ellos. 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.

Nota: El rol queryDataUser es compatible con Cloud Databases (AlloyDB, GoogleSQL para Spanner, Cloud SQL y Cloud SQL para PostgreSQL).

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 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 datos de Gemini Data Analytics: 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 Gemini Data Analytics: 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, ten en cuenta las siguientes tareas comunes de los usuarios:

Administra todos los recursos de análisis de datos de Gemini

Asigna el rol de administrador de Gemini Data Analytics a los administradores que necesiten acceso completo a todos los agentes de datos y ubicaciones dentro de un proyecto.

Ver todos los recursos de análisis de datos de Gemini y chatear

Asigna el rol de Visualizador de Gemini Data Analytics a los usuarios que necesiten acceso de solo lectura a todas las configuraciones del agente en el proyecto y la capacidad de chatear con ellos.

Crear nuevos agentes de datos

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.

Cómo 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.

Editar 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 de 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.

Consulta datos con lenguaje natural

Asigna el rol de Usuario de datos de consulta de Gemini Data Analytics a los usuarios o las aplicaciones que necesiten usar lenguaje natural para consultar datos y compilar aplicaciones de datos. Este rol solo se aplica a las bases de datos en la nube, es decir, AlloyDB, GoogleSQL para Spanner, Cloud SQL y Cloud SQL para PostgreSQL.

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 y sus niveles de otorgamiento típicos, que pueden ser a nivel del proyecto o para un agente de datos específico. Si los roles predefinidos no proporcionan el conjunto de permisos que deseas, también puedes crear tus propios roles personalizados.

Otorga los roles dataAgentOwner, dataAgentEditor, dataAgentUser y dataAgentViewer a nivel del recurso del agente. Para evitar otorgar permisos demasiado amplios, restringe el otorgamiento de estos roles a nivel del proyecto solo a los administradores, ya que el acceso a nivel del proyecto otorga permisos para todos los agentes dentro del proyecto.

Los roles predefinidos incluyen permisos de las siguientes categorías:

• geminidataanalytics.dataAgents.*: Controla el acceso a los recursos de los agentes de datos, lo que incluye crear, ver, actualizar, borrar y chatear con los agentes de datos, así como administrar las políticas de IAM de los agentes.
• geminidataanalytics.operations.*: Controla el acceso para inspeccionar, enumerar, cancelar o borrar operaciones en segundo plano de larga duración.
• geminidataanalytics.locations.*: Controla el acceso para ver y enumerar las ubicaciones disponibles de Google Cloud, y para invocar capacidades a nivel de la ubicación, como los agentes de chat sin estado y de ingeniería de datos.

Rol	Nivel de concesión típico	Permisos
Administrador de Gemini Data Analytics (roles/geminidataanalytics.admin) Otorga acceso administrativo completo a todos los recursos de Gemini Data Analytics dentro de un proyecto. Permite que los directores creen, editen, compartan y borren agentes de datos, chateen con agentes y administren operaciones en segundo plano.	Proyecto	geminidataanalytics.* geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.create geminidataanalytics.dataAgents.delete geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.getIamPolicy geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.setIamPolicy geminidataanalytics.dataAgents.update geminidataanalytics.locations.chat geminidataanalytics.locations.get geminidataanalytics.locations.list geminidataanalytics.locations.useDataEngineeringAgent geminidataanalytics.operations.cancel geminidataanalytics.operations.delete geminidataanalytics.operations.get geminidataanalytics.operations.list resourcemanager.projects.get resourcemanager.projects.list
Visualizador de análisis de datos de Gemini (roles/geminidataanalytics.viewer) Otorga permiso para ver las configuraciones de los agentes y chatear con cualquier agente de un proyecto. No otorga permiso para crear, editar, compartir ni borrar agentes.	Proyecto	geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.getIamPolicy geminidataanalytics.dataAgents.list geminidataanalytics.locations.* geminidataanalytics.locations.chat geminidataanalytics.locations.get geminidataanalytics.locations.list geminidataanalytics.locations.useDataEngineeringAgent geminidataanalytics.operations.get geminidataanalytics.operations.list resourcemanager.projects.get resourcemanager.projects.list
Creador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) Otorga permiso a una principal 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.	Proyecto	geminidataanalytics.dataAgents.create geminidataanalytics.locations.chat geminidataanalytics.operations.get
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 entidades 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.	Agente o proyecto	geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.delete geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.getIamPolicy geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.setIamPolicy geminidataanalytics.dataAgents.update geminidataanalytics.locations.get geminidataanalytics.locations.list geminidataanalytics.operations.* geminidataanalytics.operations.cancel geminidataanalytics.operations.delete geminidataanalytics.operations.get geminidataanalytics.operations.list
Editor de agentes de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentEditor) Otorga permiso para modificar y administrar la configuración existente del agente. Este rol hereda todos los permisos de los roles dataAgentUser y dataAgentViewer.	Agente o proyecto	geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.update geminidataanalytics.operations.get
Usuario del agente de datos 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 al principal. Este rol hereda todos los permisos del rol dataAgentViewer.	Agente o proyecto	geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.list
Visualizador de agentes de análisis de datos de Gemini (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.	Agente o proyecto	geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.list
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.	Proyecto	geminidataanalytics.locations.chat geminidataanalytics.locations.useDataEngineeringAgent
Usuario de datos de consulta de Gemini Data Analytics (roles/geminidataanalytics.queryDataUser) Otorga permiso a un principal para usar el lenguaje natural para consultar datos y compilar aplicaciones de datos con la API de QueryData. Este rol solo se aplica a las bases de datos en la nube, es decir, AlloyDB, GoogleSQL para Spanner, Cloud SQL y Cloud SQL para PostgreSQL.	Proyecto	geminidataanalytics.locations.queryData

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 al 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 consola de Google Cloud , puedes encontrar estos roles si filtras por el servicio Análisis de datos de Gemini.

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 , dirígete 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ú Selecciona 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: Es el ID del 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/LOCATION/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: Es el ID del proyecto de Google Cloud .
• LOCATION: Es la ubicación en la que se almacena el agente de datos (por ejemplo, global, us o us-east4). Para obtener más información, consulta Residencia de datos.
• 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/LOCATION/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/LOCATION/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: Es el ID del proyecto de Google Cloud .
• LOCATION: Es la ubicación en la que se almacena el agente de datos (por ejemplo, global, us o us-east4). Para obtener más información, consulta Residencia de datos.
• 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.

¿Qué sigue?

• Obtén más información sobre la API de Conversational Analytics.
• Obtén información para autenticarte en tu fuente de datos y en la API.