Conversational Analytics API 使用 Identity and Access Management (IAM) 来控制用于创建、管理数据代理以及与数据代理互动的访问权限。借助 IAM，您可以通过为主账号（例如用户、群组和服务账号）分配角色来向其授予权限。每个角色都是一个或多个权限的集合，用于确定主账号可以执行哪些操作。
本页面介绍了 Conversational Analytics API 的预定义 IAM 角色。您可以在 Google Cloud 控制台中为启用了 Conversational Analytics API 的项目分配这些 IAM 角色。如需了解详细说明，请参阅使用 Google Cloud 控制台授予角色。您还可以按照授予 IAM 角色中所述，使用 Google Cloud CLI 授予角色。
准备工作
如需获得分配 Conversational Analytics API IAM 角色所需的权限，请让您的管理员为您授予已启用 Conversational Analytics API 的项目的 Project IAM Admin (roles/resourcemanager.projectIamAdmin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
Conversational Analytics API IAM 角色概览
Conversational Analytics API 提供了一组预定义 IAM 角色。借助这些角色，您可以授予执行各种任务的权限，例如创建和修改代理、共享和管理代理、查看代理和与代理对话，以及在无状态对话模式下使用 API。
Conversational Analytics API 的预定义 IAM 角色是 geminidataanalytics 服务的一部分。这些角色的技术名称遵循 roles/geminidataanalytics.ROLE_NAME 模式。在 Google Cloud 控制台中，您可以通过针对 Gemini Data Analytics 服务进行过滤来查找这些角色。
您可以在项目级分配 Conversational Analytics API IAM 角色。
常见用户任务所需的角色
如需确定要向主账号分配哪些角色，请考虑以下常见用户任务。
- 创建新数据代理
- 将 Data Agent Creator 角色分配给负责在项目中创建新数据代理的用户。
- 管理代理权限
- 将 Data Agent Owner 角色分配给需要对代理拥有最高级别控制权（包括能够管理权限以及共享或删除代理）的用户。用户创建代理时，系统会自动为该用户授予此角色以用于特定代理。
- 修改代理配置
- 将 Data Agent Editor 角色分配给修改代理配置（例如上下文或数据源映射）的用户。这些用户没有共享或删除代理的权限。
- 与代理对话
- 将 Data Agent User 角色分配给主要通过提问和接收回答与代理互动的用户或应用。
- 查看代理配置
- 将 Data Agent Viewer 角色分配给需要只读权限以查看代理配置的用户。
- 使用内嵌上下文进行对话
- 将 Data Agent Stateless User 角色分配给在无状态模式下与 API 互动的应用或用户，在这种模式下，用户会在每个请求中提供对话的所有上下文。
如需查看预定义角色及其所含权限的列表，请参阅 Conversational Analytics API 的预定义角色。
Conversational Analytics API 的预定义角色
下表介绍了 Conversational Analytics API 的预定义角色。如果预定义角色未提供您所需的权限集，您还可以创建自己的自定义角色。
| 角色 | 权限 |
|---|---|
|
Gemini Data Analytics Data Agent Creator ( 为主账号授予在特定项目中创建新数据代理资源的权限。某个主账号创建代理时，系统会自动为该主账号授予 |
geminidataanalytics.dataAgents.create
|
|
Gemini Data Analytics Data Agent Owner ( 为主账号授予对项目内任何代理的生命周期的完全控制权，包括共享和删除代理。此角色适用于可管理代理共享的受信任主账号。此角色继承了 具有此角色的主账号可以共享和删除代理。 |
|
|
Gemini Data Analytics Data Agent Editor ( 授予修改和管理现有代理配置的权限。此角色继承了 |
|
|
Gemini Data Analytics Data Agent User ( 授予与主账号已获权访问的特定代理进行对话的权限。此角色继承了 |
|
|
Gemini Data Analytics Data Agent Viewer ( 为主账号授予列出和查看代理配置的只读权限。此角色不允许与代理进行对话。 |
|
|
Gemini Data Analytics Data Agent Stateless User ( 为主账号授予在无状态模式下调用 Chat API 的权限。对于无状态对话，上下文直接在请求中提供，而不是在创建期间显式保存在代理配置中。 |
geminidataanalytics.chat
|
授予 IAM 角色
您可以使用 Google Cloud 控制台或 Google Cloud CLI 为主账号授予 Conversational Analytics API IAM 角色。
控制台
如需在 Google Cloud 控制台中为主账号授予角色，请完成以下步骤：
在 Google Cloud 控制台中，前往 IAM 页面。
点击授予访问权限。
在新的主账号字段中，输入用户、群组或服务账号的邮箱。
在选择角色菜单中，针对 Gemini Data Analytics 进行过滤，以查看 Conversational Analytics API 的可用 IAM 角色。
选择适当的角色，例如 Gemini Data Analytics Data Agent User。
点击保存。
gcloud
如需使用 gcloud CLI 授予角色，请完成以下步骤：
- 登录 Google Cloud 并设置项目：
gcloud auth login gcloud config set project project_id
- （可选）如需列出您可以为项目授予的 Conversational Analytics API IAM 角色，请按如下方式使用
gcloud iam list-grantable-roles命令：
gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/project_id --filter "geminidataanalytics"
- 使用
gcloud projects add-iam-policy-binding命令为主账号授予角色。
- 如需为用户授予角色，请使用以下命令：
gcloud projects add-iam-policy-binding project_id --member='user:user_email' --role='roles/gda_grantable_role'
- 如需向服务账号分配角色，请使用以下命令：
gcloud projects add-iam-policy-binding project_id --member='serviceAccount:service_account_email' --role='roles/gda_grantable_role'
在上述说明中，按如下所示替换示例值：
project_id：您的 Google Cloud 项目 ID。user_email：用户的邮箱，例如test-user@gmail.com。service_account_email：服务账号的邮箱，例如test-proj@example.domain.com。gda_grantable_role：您要授予的特定 Conversational Analytics API IAM 角色，例如geminidataanalytics.dataAgentCreator。