授予 Conversational Analytics API 身分與存取權管理角色和權限

Conversational Analytics API 使用身分與存取權管理 (IAM)，控管建立、管理及與資料代理程式互動的存取權。透過 IAM，您可以將角色指派給主體 (例如使用者、群組和服務帳戶)，藉此授予主體權限。每個角色具有一或多項權限，可決定主體可執行的動作。

本頁面說明 Conversational Analytics API 的預先定義 IAM 角色。您可以在啟用 Conversational Analytics API 的專案中，透過 Google Cloud 控制台指派這些 IAM 角色。如需詳細操作說明，請參閱「使用 Google Cloud 控制台授予角色」一文。您也可以使用 Google Cloud CLI 授予角色，詳情請參閱「授予 IAM 角色」。

事前準備

如要取得指派 Conversational Analytics API IAM 角色所需的權限，請要求管理員在啟用 Conversational Analytics API 的專案中，授予您專案 IAM 管理員 (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 角色。

常見使用者工作所需的角色

如要決定要將哪些角色指派給主體，請考量下列常見的使用者工作。

建立新的資料代理程式
將 Gemini Data Analytics 資料代理程式建立者角色指派給負責在專案中建立新資料代理程式的使用者。
管理代理程式權限
將「Gemini Data Analytics 資料代理程式擁有者」角色指派給需要最高層級代理程式控制權的使用者，包括管理權限、共用或刪除代理程式。使用者建立代理程式時，系統會自動將這個角色授予該使用者，適用於特定代理程式。
編輯代理程式設定
將「Gemini Data Analytics Data Agent Editor」角色指派給修改代理程式設定的使用者，例如代理程式的環境或資料來源對應。這些使用者沒有共用或刪除代理程式的權限。
與服務專員即時通訊
將「Gemini Data Analytics Data Agent User」角色指派給主要與代理程式互動的使用者或應用程式，例如提問及接收回覆。
查看代理程式設定
將「Gemini Data Analytics 資料代理程式檢視者」角色指派給需要唯讀存取權的使用者，讓他們查看代理程式設定。
使用內嵌脈絡對話
將「Gemini Data Analytics Stateless Chat User」角色指派給以無狀態模式與 API 互動的使用者或應用程式，讓使用者在每個要求中提供對話的所有脈絡。

如需預先定義角色及其包含的權限清單，請參閱「Conversational Analytics API 的預先定義角色」。

Conversational Analytics API 的預先定義角色

下表說明 Conversational Analytics API 的預先定義角色。如果預先定義的角色未提供您需要的權限集，您也可以建立自己的自訂角色。

角色 權限

Gemini Data Analytics 資料代理建立者 (roles/geminidataanalytics.dataAgentCreator)

授予主體在特定專案中建立新資料代理程式資源的權限。主體建立代理程式時，系統會自動授予該主體特定代理程式的 dataAgentOwner 角色。

 geminidataanalytics.dataAgents.create

Gemini Data Analytics 資料代理擁有者 (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 資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)

授予修改及管理現有代理程式設定的權限。這個角色會繼承「dataAgentUser」和「dataAgentViewer」角色的所有權限。
  • geminidataanalytics.dataAgents.list
  • geminidataanalytics.dataAgents.get
  • geminidataanalytics.dataAgents.chat
  • geminidataanalytics.dataAgents.update

Gemini Data Analytics 資料代理使用者 (roles/geminidataanalytics.dataAgentUser)

授予與特定代理交談的權限，主體必須已獲授權存取這些代理。這個角色會繼承 dataAgentViewer 角色的所有權限。
  • geminidataanalytics.dataAgents.list
  • geminidataanalytics.dataAgents.get
  • geminidataanalytics.dataAgents.chat

Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)

授予主體唯讀權限，可列出及查看代理程式設定。這個角色無法與服務專員即時通訊。
  • geminidataanalytics.dataAgents.list
  • geminidataanalytics.dataAgents.get

Gemini Data Analytics 無狀態對話使用者 (roles/geminidataanalytics.dataAgentStatelessUser)

授予主體在無狀態模式下呼叫 Chat API 的權限。使用無狀態對話時，系統會直接在要求中提供背景資訊，而不是在建立期間明確儲存在代理程式設定中。

 geminidataanalytics.chat

授予 IAM 角色

您可以使用 Google Cloud 控制台或 Google Cloud CLI，將 Conversational Analytics API IAM 角色授予主體。

主控台

如要在 Google Cloud 控制台中將角色授予主體，請完成下列步驟：

  1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

    前往「IAM」(身分與存取權管理) 頁面

  2. 按一下「授予存取權」。

  3. 在「新增主體」欄位中，輸入使用者、群組或服務帳戶的電子郵件地址。

  4. 在「Select a role」(選取角色) 選單中，篩選「Gemini Data Analytics」(Gemini 資料分析)，即可查看 Conversational Analytics API 的可用 IAM 角色。

  5. 選取適當的角色，例如「Gemini Data Analytics 資料代理使用者」。

  6. 按一下 [儲存]。

gcloud

如要使用 gcloud CLI 授予角色，請完成下列步驟：

  1. 登入 Google Cloud 並設定專案：
gcloud auth login
gcloud config set project project_id
  1. 如要列出可為專案授予的 Conversational Analytics API IAM 角色，請使用 gcloud iam list-grantable-roles 指令，如下所示：
gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/project_id --filter "geminidataanalytics"
  1. 使用 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。