此页面由 Cloud Translation API 翻译。

通过 IAM 控制对 Conversational Analytics API 的访问权限

Conversational Analytics API 使用 Identity and Access Management (IAM) 进行访问权限控制，让您可以共享数据代理，并控制哪些人有权创建、管理数据代理以及与数据代理互动。本页面介绍了您可以分配给主账号（例如用户、群组和服务账号）的预定义 IAM 角色，以授予这些权限。

准备工作

如需获得分配 Conversational Analytics API IAM 角色所需的权限，请让您的管理员为您授予已启用 Conversational Analytics API 的项目的 Project IAM Admin (roles/resourcemanager.projectIamAdmin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

Conversational Analytics API IAM 角色概览

借助 Conversational Analytics API 的预定义 IAM 角色，您可以精细控制哪些人可以创建、管理数据代理以及与数据代理互动。本部分介绍了如何通过分配 IAM 角色来共享数据代理，并介绍了其他常见用户任务所需的 IAM 角色。

您可以在项目级层授予角色，以向项目中的所有代理提供权限。如需控制对特定代理的访问权限，代理所有者（具有 Gemini Data Analytics Data Agent Owner 角色的正文）可以以编程方式修改该代理的 IAM 政策。

下图展示了智能体所有者如何管理对特定智能体的访问权限：

代理所有者向其他用户授予 Data Agent Editor 和 Data Agent User 角色。

在此场景中，具有 Gemini Data Analytics Data Agent Creator 角色的高级数据分析师创建了一个代理。用户创建代理后，系统会自动为其授予该代理的 Gemini Data Analytics Data Agent Owner 角色。作为代理的所有者，高级数据分析师通过设置代理的 IAM 政策来管理对代理的访问权限，并向团队成员授予以下角色：

Gemini Data Analytics Data Agent Editor：代理所有者将此角色授予初级数据分析师。此角色允许初级分析师修改代理的配置并与代理聊天。
Gemini Data Analytics Data Agent User：代理所有者将此角色授予不需要能够修改代理配置的团队成员。此角色允许这些团队成员与代理对话。

常见用户任务所需的角色

为帮助您确定要分配哪些角色，请考虑以下常见用户任务：

创建新数据代理: 将 Gemini Data Analytics Data Agent Creator 角色分配给负责在项目中创建新数据代理的用户。
分享智能体: 将 Gemini Data Analytics Data Agent Owner 角色分配给需要通过管理代理权限与其他正文共享代理的用户。
管理代理权限: 将 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 Stateless Chat User 角色分配给在无状态模式下与 API 互动的应用或用户，在这种模式下，用户会在每个请求中提供对话的所有上下文。

Conversational Analytics API 的预定义角色

下表介绍了 Conversational Analytics API 的预定义角色。如果预定义角色未提供您所需的权限集，您还可以创建自己的自定义角色。

角色	权限
Gemini Data Analytics Data Agent Creator (`roles/geminidataanalytics.dataAgentCreator`) 为主账号授予在特定项目中创建新数据代理资源的权限。某个主账号创建代理时，系统会自动为该主账号授予 `dataAgentOwner` 角色以用于特定代理。	`geminidataanalytics.dataAgents.create`
Gemini Data Analytics Data Agent Owner (`roles/geminidataanalytics.dataAgentOwner`) 为主账号授予对项目内任何代理的生命周期的完全控制权，包括共享和删除代理。此角色适用于可管理代理共享的受信任主账号。此角色继承了 `dataAgentEditor`、`dataAgentUser` 和 `dataAgentViewer` 角色的所有权限。具有此角色的主账号可以共享和删除代理。	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update` `geminidataanalytics.dataAgents.delete` `geminidataanalytics.dataAgents.getIamPolicy` `geminidataanalytics.dataAgents.setIamPolicy`
Gemini Data Analytics Data Agent Editor (`roles/geminidataanalytics.dataAgentEditor`) 授予修改和管理现有代理配置的权限。此角色继承了 `dataAgentUser` 和 `dataAgentViewer` 角色的所有权限。	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update`
Gemini Data Analytics Data Agent User (`roles/geminidataanalytics.dataAgentUser`) 授予与主账号已获权访问的特定代理进行对话的权限。此角色继承了 `dataAgentViewer` 角色的所有权限。	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat`
Gemini Data Analytics Data Agent Viewer (`roles/geminidataanalytics.dataAgentViewer`) 为主账号授予列出和查看代理配置的只读权限。此角色不允许与代理进行对话。	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get`
Gemini Data Analytics Stateless Chat User (`roles/geminidataanalytics.dataAgentStatelessUser`) 为主账号授予在无状态模式下调用 Chat API 的权限。对于无状态对话，上下文直接在请求中提供，而不是在创建期间显式保存在代理配置中。	`geminidataanalytics.chat`

授予 IAM 角色

您可以在项目级或为特定代理授予 Conversational Analytics API IAM 角色。在项目级层授予角色会为主账号提供该项目中所有代理的相同权限，而在特定代理上设置政策可提供更精细的控制。

Conversational Analytics API 的预定义 IAM 角色是 geminidataanalytics 服务的一部分。这些角色的技术名称遵循 roles/geminidataanalytics.ROLE_NAME 模式。在 Google Cloud 控制台中，您可以通过针对 Gemini Data Analytics 服务进行过滤来查找这些角色。

为项目中的所有客服人员授予角色

使用 Google Cloud 控制台或 Google Cloud CLI 为整个项目授予角色。

控制台

如需在 Google Cloud 控制台中为主账号授予角色，请完成以下步骤：

在 Google Cloud 控制台中，前往 IAM 页面。

转到 IAM
点击授予访问权限。
在新的主账号字段中，输入用户、群组或服务账号的邮箱。
在选择角色菜单中，针对 Gemini Data Analytics 进行过滤，以查看 Conversational Analytics API 的可用 IAM 角色。
选择适当的角色，例如 Gemini Data Analytics Data Agent User。
点击保存。

gcloud

如需使用 gcloud CLI 授予角色，请完成以下步骤：

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。

为特定代理授予角色

如需管理特定数据智能体的访问权限，您必须以编程方式修改该智能体的允许政策。此过程遵循标准的读取-修改-写入模式，即先读取当前政策，然后对其进行修改，最后将其写回。

以下示例展示了用于获取和设置数据代理的 IAM 政策的请求正文。

HTTP

如需获取代理的现有政策，请向 :getIamPolicy 端点发送 POST 请求，并提供以下请求正文：

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

如需为代理设置政策，请向 :setIamPolicy 端点发送 POST 请求，并包含以下请求正文：

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

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
AGENT_ID：要获取或设置政策的数据智能体的 ID。
ROLE：要授予的角色，例如 roles/geminidataanalytics.dataAgentUser。
EMAIL：用户的邮箱，例如 test-user@gmail.com。

如需查看完整示例，请参阅获取数据智能体的 IAM 政策和为数据智能体设置 IAM 政策。

Python SDK

如需获取代理的现有政策，请使用 get_iam_policy 方法，如以下示例请求所示：

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

如需为代理设置政策，请使用 set_iam_policy 方法，如以下示例请求所示：

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
)