Control de acceso a la API de Conversational Analytics con IAM

Vista previa

Este producto o esta función se encuentra sujeto a las "Condiciones de la oferta de la fase previa a la DG" en la sección Condiciones del servicio generales de las Condiciones específicas del servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” 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 la administración de identidades y accesos (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 predefinidos de IAM que puedes asignar a entidades (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 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 predefinidos de IAM para la API de Conversational Analytics proporcionan un control detallado sobre quién puede crear, administrar e interactuar con los agentes de datos. En esta sección, se explica cómo compartir agentes de datos mediante la asignación de 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 para todos los agentes dentro de un proyecto. Para controlar el acceso a un agente específico, el propietario del agente (una principal con el rol de propietario del agente de datos de análisis de datos de Gemini) 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 correctamente con un agente, un 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 que se consultan

En el siguiente diagrama, se muestra cómo un propietario del 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 análisis de datos de Gemini para ese agente. Como propietario del agente, el analista de datos sénior administra el acceso al agente mediante la configuración de 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 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 esos miembros del equipo chateen con el agente.

Roles necesarios para tareas comunes del usuario

Para ayudarte a decidir qué roles asignar, considera las siguientes tareas comunes del usuario:

Crear agentes de datos nuevos

Asigna el rol de creador de agentes de datos de análisis de datos de Gemini a los usuarios responsables de crear agentes de datos nuevos dentro de un proyecto.

Compartir agentes

Asigna el rol de propietario del agente de datos de análisis de datos de Gemini a los usuarios que necesitan compartir agentes con otras principales mediante la administración de los permisos del agente.

Administrar permisos del agente

Asigna el rol de propietario del agente de datos de análisis de datos de Gemini a los usuarios que necesitan compartir agentes con otros usuarios mediante la administración de los permisos del agente o que necesitan 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 configuraciones del agente

Asigna el rol de editor de agentes de análisis de datos de Gemini 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 permisos para compartir ni borrar el agente.

Chatear con agentes

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

Ver configuraciones del agente

Asigna el rol de visualizador de agentes de datos de análisis de datos de Gemini a los usuarios que necesitan acceso de solo lectura para ver las configuraciones del agente.

Chatear con contexto intercalado

Asigna el rol de usuario de chat sin estado de análisis de datos de Gemini 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 dentro de cada solicitud.

Consultar datos con lenguaje natural

Asigna el rol de usuario de consulta de datos de análisis de datos de Gemini a los usuarios o las aplicaciones que necesitan usar lenguaje natural para consultar datos y compilar aplicaciones de datos. Este rol solo se aplica a Cloud Databases, 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 proporciona la capacidad de ver las conversaciones que iniciaron otros usuarios. Por ejemplo, cuando se enumeran las conversaciones de un agente, solo se muestran las conversaciones creadas por el usuario actual.

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

Rol	Permisos
Creador de agentes de datos de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentCreator) Otorga a una 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 dataAgentOwner para el agente específico.	geminidataanalytics.dataAgents.create
Propietario del agente de datos de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentOwner) Otorga a una 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 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 las configuraciones 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 le 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 análisis de datos de Gemini (roles/geminidataanalytics.dataAgentViewer) Otorga a una principal permiso de solo lectura para enumerar y ver las configuraciones 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 a una principal permiso 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
Usuario de consulta de datos de análisis de datos de Gemini (roles/geminidataanalytics.queryDataUser) Otorga a una principal permiso para usar lenguaje natural para consultar datos y compilar aplicaciones de datos con la API de QueryData. Este rol solo se aplica a Cloud Databases, es decir, AlloyDB, GoogleSQL para Spanner, Cloud SQL y Cloud SQL para PostgreSQL.	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 a una 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 predefinidos de IAM 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.

Otorgar roles para todos los agentes de un proyecto

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

Console

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

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

   Ir a IAM

2. Haz clic en Otorgar acceso.

3. En el campo Principales nuevas , 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 análisis de datos de Gemini.

6. Haz clic en Guardar.

gcloud

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

1. Accede a tu cuenta 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 entidad 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 Google Cloud proyecto.
• 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.

Otorgar roles para un agente específico

Para administrar el acceso a 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 estándar de lectura-modificación-escritura 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 otorgas 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 la 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 la 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: Es el ID del Google Cloud proyecto.
• 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 obtener ejemplos completos, consulta Obtén la política de IAM para un agente de datos y Establece 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 muestra:

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: Es el ID del Google Cloud proyecto.
• 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 obtener ejemplos completos, consulta Obtén la política de IAM para un agente de datos y Establece la política de IAM para un agente de datos.