Control de acceso a la API Conversational Analytics con IAM

Este producto o función está sujeto a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Los productos y las funciones previos a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

La API Conversational Analytics usa Gestió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, gestionarlos e interactuar con ellos. En esta página se describen los roles de gestión de identidades y accesos predefinidos que puedes asignar a entidades (como usuarios, grupos y cuentas de servicio) para conceder estos permisos.

Antes de empezar

Para obtener los permisos que necesitas para asignar roles de gestión de identidades y accesos de la API Conversational Analytics, pide a tu administrador que te conceda el rol de gestión de identidades y accesos de proyecto (roles/resourcemanager.projectIamAdmin) en el proyecto en el que esté habilitada la API Conversational Analytics. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Nota: Los roles básicos de gestión de identidades y accesos también pueden incluir permisos para asignar roles de gestión de identidades y accesos de la API Conversational Analytics. No debes conceder roles básicos en un entorno de producción, pero sí puedes hacerlo en un entorno de desarrollo o de pruebas.

Descripción general de los roles de gestión de identidades y accesos de la API Conversational Analytics

Los roles de gestión de identidades y accesos predefinidos de la API Conversational Analytics ofrecen un control granular sobre quién puede crear, gestionar e interactuar con agentes de datos. En esta sección se explica cómo compartir agentes de datos asignando roles de gestión de identidades y accesos, así como los roles de gestión de identidades y accesos necesarios para otras tareas habituales de los usuarios.

Cómo funciona la función para compartir con agentes

Puedes asignar roles a nivel de proyecto para proporcionar permisos a todos los agentes de un proyecto. Para controlar el acceso a un agente específico, el propietario del agente (una entidad con el rol Propietario del agente de datos de Gemini Data Analytics) puede modificar la política de gestión de identidades y accesos de ese agente mediante programación.

Importante: Los roles de gestión de identidades y accesos de la API 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) mediante las credenciales de ese usuario. Por lo tanto, para chatear correctamente con un agente, un usuario debe tener los siguientes permisos:

• Un rol de gestión de identidades y accesos de la API 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 están consultando

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

En este caso, un analista de datos sénior con el rol Creador de agentes de datos de analíticas de datos de Gemini crea un agente. Cuando un usuario crea un agente, se le asigna automáticamente el rol Propietario del agente de datos de Gemini Data Analytics para ese agente. Como propietario del agente, el analista de datos sénior gestiona el acceso al agente definiendo su política de gestión de identidades y accesos y asignando los siguientes roles a los miembros del equipo:

• Editor del agente de datos de Gemini Data Analytics: el propietario del agente asigna este rol a los analistas de datos júnior. Este rol permite a los analistas junior editar la configuración del agente y chatear con él.
• Usuario del agente de datos de Gemini Data Analytics: el propietario del agente asigna este rol a los miembros del equipo que no necesitan poder editar la configuración del agente. Este rol permite a los miembros del equipo chatear con el agente.

Roles necesarios para las tareas de usuario habituales

Para ayudarte a decidir qué roles asignar, ten en cuenta las siguientes tareas habituales de los usuarios:

Crear nuevos agentes de datos

Asigna el rol Creador de agentes de datos de Gemini Data Analytics a los usuarios responsables de crear agentes de datos en un proyecto.

Compartir agentes

Asigna el rol Propietario del agente de datos de Gemini Data Analytics a los usuarios que necesiten compartir agentes con otras entidades gestionando los permisos de los agentes.

Gestionar permisos de agentes

Asigna el rol Propietario del agente de datos de Gemini Data Analytics a los usuarios que necesiten compartir agentes con otros usuarios gestionando los permisos de los agentes o que necesiten el máximo nivel de control sobre un agente, incluida la capacidad de eliminar agentes. Cuando un usuario crea un agente, el sistema le asigna automáticamente este rol para ese agente concreto.

Editar configuraciones del agente

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

Chatear con agentes

Asigna el rol Usuario agente de datos de analíticas de datos de Gemini a los usuarios o las aplicaciones que interactúen principalmente con los agentes haciendo preguntas y recibiendo respuestas.

Ver configuraciones de agentes

Asigna el rol Lector de datos del agente de analíticas de datos de Gemini a los usuarios que necesiten acceso de solo lectura para ver las configuraciones de los agentes.

Chatear usando el contexto insertado

Asigna el rol Usuario de chat sin estado de Gemini Data Analytics a los usuarios o las aplicaciones que interactúen 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 de la API Conversational Analytics

Nota: Si das acceso a un usuario a un agente de datos, no podrá ver las conversaciones que hayan iniciado otros usuarios. Por ejemplo, al enumerar las conversaciones de un agente, solo se devuelven las conversaciones creadas por el usuario actual.

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

Rol	Permisos
Creador de agentes de datos de analíticas de datos de Gemini (roles/geminidataanalytics.dataAgentCreator) Concede a un principal permiso para crear recursos de agente de datos en un proyecto específico. Cuando un centro crea un agente, el sistema le asigna automáticamente el rol dataAgentOwner a ese centro para el agente específico.	geminidataanalytics.dataAgents.create
Propietario del agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) Otorga a un principal control total sobre el ciclo de vida de cualquier agente del proyecto, lo que incluye compartir y eliminar agentes. Este rol es para las entidades de confianza que pueden gestionar el uso compartido de agentes. Este rol hereda todos los permisos de los roles dataAgentEditor, dataAgentUser y dataAgentViewer. Una cuenta con este rol puede compartir y eliminar agentes.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.update geminidataanalytics.dataAgents.delete geminidataanalytics.dataAgents.getIamPolicy geminidataanalytics.dataAgents.setIamPolicy
Editor de agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor) Concede permiso para modificar y gestionar las configuraciones de agentes. 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 de agente de datos de analíticas de datos de Gemini (roles/geminidataanalytics.dataAgentUser) Concede permiso para chatear con los agentes específicos a los que se ha concedido acceso a la entidad principal. Este rol hereda todos los permisos del rol dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat
Visor de datos de Gemini Data Analytics Data Agent (roles/geminidataanalytics.dataAgentViewer) Concede a una entidad 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 analíticas de datos de Gemini (roles/geminidataanalytics.dataAgentStatelessUser) Concede a un principal permiso para llamar a la API Chat en modo sin estado. En el chat sin estado, el contexto se proporciona directamente en la solicitud en lugar de guardarse explícitamente en la configuración del agente durante la creación.	geminidataanalytics.chat

Otorgar roles de gestión de identidades y accesos

Puedes conceder roles de gestión de identidades y accesos de la API Conversational Analytics a nivel de proyecto o para un agente específico. Si se asigna un rol a nivel de proyecto, se conceden los mismos permisos a una entidad principal para todos los agentes de ese proyecto. En cambio, si se define la política en un agente específico, se obtiene un control más granular.

Los roles de gestión de identidades y accesos predefinidos de la API 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 filtrando por el servicio Gemini Data Analytics.

Otorgar roles a todos los agentes de un proyecto

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

consola

Para conceder un rol a una entidad en la consola de Google Cloud , sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Gestión de identidades y accesos.

   Ir a IAM

2. Haz clic en Conceder acceso.

3. En el campo Principales nuevos, introduce la dirección de correo 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 gestión de identidades y accesos disponibles para la API Conversational Analytics.

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

6. Haz clic en Guardar.

gcloud

Para asignar roles mediante gcloud CLI, sigue estos pasos:

1. Inicia sesión en Google Cloud y configura tu proyecto:

gcloud auth login
gcloud config set project project_id

1. Si quieres enumerar los roles de IAM de la API Conversational Analytics que puedes conceder a 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. Asigna un rol a una cuenta principal mediante el comando gcloud projects add-iam-policy-binding.

• Para asignar 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, sustituye los valores de ejemplo de la siguiente manera:

• project_id: tu ID de proyecto Google Cloud .
• user_email: la dirección de correo del usuario, como [e-mail].
• service_account_email: la dirección de correo de la cuenta de servicio, como [e-mail].
• gda_grantable_role: el rol de gestión de identidades y accesos de la API Conversational Analytics específico que quiere conceder, como geminidataanalytics.dataAgentCreator.

Asignar roles a un agente específico

Para gestionar el acceso de un agente de datos específico, debes modificar de forma programática su política de permiso. Este proceso sigue un patrón de lectura, modificación y escritura estándar, en el que se lee la política actual, se modifica y, a continuación, se vuelve a escribir.

Importante: El método setIamPolicy anula cualquier política que ya tenga el agente. Para conservar los permisos al asignar nuevos roles, primero debes llamar a getIAMPolicy para obtener la política, modificarla y, a continuación, pasar el objeto de política actualizado en la llamada a setIamPolicy.

En los siguientes ejemplos se muestran los cuerpos de las solicitudes para obtener y definir políticas de IAM de un agente de datos.

HTTP

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

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

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

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

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto Google Cloud .
• AGENT_ID: ID del agente de datos para el que se va a obtener o definir la política.
• ROLE: el rol que se va a asignar, como roles/geminidataanalytics.dataAgentUser.
• EMAIL: la dirección de correo del usuario, como [e-mail].

Para ver ejemplos completos, consulta Obtener la política de gestión de identidades y accesos de un agente de datos y Definir la política de gestión de identidades y accesos de un agente de datos.

SDK de Python

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

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

Para definir 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
)

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto Google Cloud .
• AGENT_ID: ID del agente de datos para el que se va a obtener o definir la política.
• ROLE: el rol que se va a asignar, como roles/geminidataanalytics.dataAgentUser.
• EMAIL: la dirección de correo del usuario, como [e-mail].

Para ver ejemplos completos, consulta Obtener la política de gestión de identidades y accesos de un agente de datos y Definir la política de gestión de identidades y accesos de un agente de datos.