本頁面由 Cloud Translation API 翻譯而成。

使用 IAM 控管 Conversational Analytics API 存取權

Conversational Analytics API 使用身分與存取權管理 (IAM) 控管存取權，可讓您共用資料代理程式，並控管哪些使用者有權建立、管理及與代理程式互動。本頁說明可指派給主體 (例如使用者、群組和服務帳戶) 的預先定義 IAM 角色，以授予這些權限。

事前準備

如要取得指派 Conversational Analytics API IAM 角色所需的權限，請要求管理員在啟用 Conversational Analytics API 的專案中，授予您專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

對話式數據分析 API IAM 角色總覽

對話式數據分析 API 的預先定義 IAM 角色可精細控管哪些人能建立、管理及與資料代理互動。本節說明如何指派 IAM 角色來共用資料代理程式，並說明其他常見使用者工作所需的 IAM 角色。

您可以在專案層級授予角色，為專案中的所有代理程式提供權限。如要控管特定代理程式的存取權，代理程式擁有者 (具有 Gemini Data Analytics Data Agent Owner 角色的主體) 可以以程式輔助方式修改該代理程式的 IAM 政策。

下圖顯示代理程式擁有者如何管理特定代理程式的存取權：

代理程式擁有者會將「資料代理程式編輯者」和「資料代理程式使用者」角色授予其他使用者。

在這個情境中，具有 Gemini Data Analytics 資料代理建立者角色的資深資料分析師會建立代理程式。使用者建立代理程式後，系統會自動授予該代理程式的 Gemini Data Analytics 資料代理擁有者角色。身為代理程式擁有者，資深資料分析師會設定代理程式的 IAM 政策，藉此管理代理程式的存取權，並將下列角色授予團隊成員：

Gemini Data Analytics 資料代理編輯者：代理擁有者會將這個角色授予初階資料分析師。初級分析師可透過這個角色編輯代理程式設定，並與代理程式對話。
Gemini Data Analytics 資料代理程式使用者：代理程式擁有者會將這個角色授予不需要編輯代理程式設定的團隊成員。這個角色可讓團隊成員與代理程式對話。

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

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

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

對話式數據分析 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 角色

您可以在專案層級或針對特定代理程式，授予 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」(身分與存取權管理) 頁面
按一下「授予存取權」。
在「新增主體」欄位中，輸入使用者、群組或服務帳戶的電子郵件地址。
在「Select a role」(選取角色) 選單中，篩選「Gemini Data Analytics」(Gemini 資料分析)，即可查看 Conversational Analytics API 的可用 IAM 角色。
選取適當的角色，例如「Gemini Data Analytics 資料代理使用者」。
按一下 [儲存]。

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。

授予特定代理程式的角色

如要管理特定資料代理程式的存取權，您必須以程式輔助方式修改該代理程式的允許政策。這個程序遵循標準的讀取 - 修改 - 寫入模式，也就是讀取目前的政策、修改政策，然後寫回政策。

下列範例顯示取得及設定資料代理程式 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。

如需完整範例，請參閱「取得資料代理程式的身分與存取權管理政策」和「設定資料代理程式的身分與存取權管理政策」。

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
)