Conversational Analytics API 使用 Identity and Access Management (IAM) 控管存取權，可讓您共用資料代理程式，並控管哪些使用者有權建立、管理及與這些代理程式互動。本頁面說明可指派給主體 (例如使用者、群組和服務帳戶) 的預先定義 IAM 角色，以授予這些權限。
除了 IAM 之外，您也可以使用機構政策，對 Conversational Analytics API 資源設定限制，控管機構、資料夾或專案層級的使用方式。
事前準備
如要取得指派 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 管理員角色指派給需要專案中所有資料代理程式和位置完整存取權的管理員。
- 查看所有 Gemini Data Analytics 資源和對話
- 將 Gemini Data Analytics 檢視者角色指派給需要專案中所有代理程式設定唯讀存取權，以及與代理程式對話的使用者。
- 建立新的資料代理
- 將 Gemini Data Analytics 資料代理程式建立者角色指派給負責在專案中建立新資料代理程式的使用者。
- 分享代理程式
- 將 Gemini Data Analytics 資料代理擁有者角色指派給需要與其他主體共用代理的使用者，方法是管理代理權限。
- 管理代理商權限
- 將「Gemini 資料分析資料代理擁有者」角色指派給需要管理代理權限，以便與其他使用者共用代理的使用者，或是需要對代理擁有最高控管權限 (包括刪除代理) 的使用者。使用者建立代理程式時，系統會自動授予該使用者特定代理程式的此角色。
- 編輯代理程式設定
- 將「Gemini Data Analytics 資料代理編輯者」角色指派給會修改代理程式設定 (例如內容或資料來源對應) 的使用者。這些使用者沒有共用或刪除代理程式的權限。
- 與服務專員即時通訊
- 將「Gemini Data Analytics 資料代理使用者」角色指派給主要與代理互動的使用者或應用程式，例如提出問題及接收回覆。
- 查看代理程式設定
- 將「Gemini Data Analytics 資料代理程式檢視者」角色指派給需要唯讀存取權的使用者，讓他們查看代理程式設定。
- 使用內嵌脈絡對話
- 將「Gemini Data Analytics 無狀態對話使用者」角色指派給以無狀態模式與 API 互動的使用者或應用程式，使用者會在每個要求中提供對話的所有背景資訊。
- 使用自然語言查詢資料
- 使用
QueryData方法查詢資料庫資料來源 (AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL) 時，請將 Gemini Data Analytics 查詢資料使用者角色指派給使用者或應用程式。如要改為與資料代理人即時通訊，請指派資料代理人角色。
Conversational Analytics API 的預先定義角色
下表說明 Conversational Analytics API 的預先定義角色，以及這些角色的典型授權層級 (專案層級或特定資料代理程式)。如果預先定義的角色未提供您需要的權限集，您也可以建立自己的自訂角色。
在代理程式資源層級授予 dataAgentOwner、dataAgentEditor、dataAgentUser 和 dataAgentViewer 角色。為避免授予過於廣泛的權限，請僅限管理員在專案層級授予這些角色，因為專案層級的存取權會授予專案內所有代理程式權限。
預先定義的角色包含下列類別的權限：
geminidataanalytics.dataAgents.*：控管資料代理程式資源的存取權，包括建立、查看、更新、刪除及與資料代理程式對話，以及管理代理程式 IAM 政策。geminidataanalytics.operations.*：控管檢查、列出、取消或刪除長時間執行的背景作業的存取權。geminidataanalytics.locations.*：控管檢視及列出可用 Google Cloud 位置的存取權，並叫用位置層級功能，例如無狀態的即時通訊和資料工程代理程式。
| 角色 | 一般授予層級 | 權限 |
|---|---|---|
|
Gemini Data Analytics 管理員 ( 具備專案中所有 Gemini Data Analytics 資源的完整管理員權限。讓主體建立、編輯、共用及刪除資料代理程式、與代理程式對話，以及管理背景作業。 |
專案 |
|
|
Gemini Data Analytics 檢視者 ( 可授予權限，查看專案中的代理程式設定，並與任何代理程式對話。無法建立、編輯、共用或刪除代理。 |
專案 |
|
|
Gemini Data Analytics 資料代理建立者 ( 授予主體權限，在特定專案中建立新的資料代理程式資源。主體建立代理程式時，系統會自動授予該主體特定代理程式的 |
專案 |
|
|
Gemini Data Analytics 資料代理擁有者 ( 授予主體專案中任何代理程式生命週期的完整控制權，包括共用及刪除代理程式。這個角色適用於可管理代理程式共用的受信任主體。這個角色會繼承「 具備這個角色的主體可以共用及刪除代理。 |
代理或專案 |
|
|
Gemini Data Analytics 資料代理編輯者 ( 授予修改及管理現有代理程式設定的權限。這個角色會繼承「 |
代理商或專案 |
|
|
Gemini Data Analytics 資料代理使用者 ( 授予與主體獲准存取的特定代理對話的權限。這個角色會繼承「 |
代理商或專案 |
|
|
Gemini Data Analytics 資料代理檢視者 ( 授予主體唯讀權限，可列出及查看代理程式設定。這個角色無法與服務專員對話。 |
代理商或專案 |
|
|
Gemini Data Analytics 無狀態對話使用者 ( 授予主體在無狀態模式下呼叫 Chat API 的權限。無狀態對話會直接在要求中提供背景資訊，而不是在建立期間明確儲存在代理程式設定中。 |
專案 |
|
|
Gemini Data Analytics 查詢資料使用者 ( 授予主體權限，允許主體使用 |
專案 |
geminidataanalytics.locations.queryData
|
授予 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」(身分與存取權管理) 頁面。
按一下「授予存取權」。
在「新增主體」欄位中，輸入使用者、群組或服務帳戶的電子郵件地址。
在「選取角色」選單中，篩選「Gemini Data Analytics」，即可查看 Conversational Analytics API 的可用 IAM 角色。
按一下 [儲存]。
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@example.com。SERVICE_ACCOUNT_EMAIL：服務帳戶的電子郵件地址，例如test-sa@example.com。GDA_GRANTABLE_ROLE：要授予的特定 Conversational Analytics API IAM 角色，例如geminidataanalytics.dataAgentCreator。
授予特定代理的角色
如要管理特定資料代理的存取權，您必須以程式輔助方式修改該代理的允許政策。這個程序遵循標準的讀取-修改-寫入模式，也就是讀取目前的政策、修改政策，然後寫回政策。
下列範例顯示取得及設定資料代理程式 IAM 政策的要求主體。
HTTP
如要取得代理的現有政策，請使用下列要求主體，向 :getIamPolicy 端點傳送 POST 要求：
{
"resource": "projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID"
}
如要為代理程式設定政策，請將 POST 要求傳送至 :setIamPolicy 端點，並提供下列要求主體：
{
"policy": {
"bindings": [
{
"role": "ROLE",
"members": [
"user:EMAIL"
]
}
]
}
}
更改下列內容：
PROJECT_ID： Google Cloud 專案 ID。LOCATION：資料代理程式的儲存位置 (例如global、us或us-east4)。詳情請參閱資料落地。AGENT_ID：要取得或設定政策的資料代理程式 ID。ROLE：要授予的角色，例如roles/geminidataanalytics.dataAgentUser。EMAIL：使用者的電子郵件地址，例如test-user@example.com。
如需完整範例，請參閱「取得資料代理程式的 IAM 政策」和「設定資料代理程式的 IAM 政策」。
Python SDK
如要取得代理程式的現有政策，請使用 get_iam_policy 方法，例如下列範例要求：
resource = "projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID"
request = iam_policy_pb2.GetIamPolicyRequest(
resource=resource,
)
如要為代理程式設定政策，請使用 set_iam_policy 方法，如下列範例要求所示：
resource = "projects/PROJECT_ID/locations/LOCATION/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
)
更改下列內容：
PROJECT_ID： Google Cloud 專案 ID。LOCATION：資料代理程式的儲存位置 (例如global、us或us-east4)。詳情請參閱資料落地。AGENT_ID：要取得或設定政策的資料代理程式 ID。ROLE：要授予的角色，例如roles/geminidataanalytics.dataAgentUser。EMAIL：使用者的電子郵件地址，例如test-user@example.com。
如需完整範例，請參閱「取得資料代理程式的 IAM 政策」和「設定資料代理程式的 IAM 政策」。
後續步驟
- 進一步瞭解 Conversational Analytics API。
- 瞭解如何向資料來源和 API 進行驗證。