自 2026 年 4 月 10 日起，Dataplex Universal Catalog 將更名為 Knowledge Catalog。API、用戶端程式庫、CLI 和 IAM 名稱維持不變。詳情請參閱「隆重推出 Google Cloud Knowledge Catalog」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定充實工作的前置作業

在 Knowledge Studio 建立擴充工作前，您可能需要根據安全性架構和目標資料來源，設定多項基礎架構元件。

本指南說明如何設定客戶自行管理的服務帳戶、第三方驗證服務供應商、Cloud Storage bucket 和 Cloud Logging 檢視畫面。

下表說明必要設定和設定時機：

設定功能	設定時機
Google Cloud API	這是必要旗標，您必須啟用基礎 Google Cloud API，才能執行擴充工作流程。
客戶自行管理的服務帳戶	您想限制目標資料集的讀取和寫入權限。
使用者身分與存取權管理 (IAM) 角色	您必須授予工作流程管理員和審查者權限，才能產生及核准中繼資料。
第三方驗證供應商	您正在連結第三方知識來源 (例如 Microsoft SharePoint、Atlassian Confluence 或 GitHub)。
Cloud Storage bucket	您正在擷取非結構化業務背景資訊 (例如 PDF、Markdown 和 CSV) 和評估資料集。
評估資料集	您想提供種子查詢和基準資料集，主動追蹤代理的準確度。
用於自主學習的代理追蹤記錄	您希望擴充代理能自動分析下游 Gemini Enterprise 代理的互動。
資料剖析和資料洞察	(建議使用) 您想針對常用資料表生成統計資料剖析和基準 AI 洞察，提升擴充品質。

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

Roles required to enable APIs

Enable the APIs

必要 API 詳細資料

為設定及執行擴充工作，啟用的 API 會執行下列函式：

API 名稱	服務識別碼	資料充實工作流程中的用途
Dataplex API	`dataplex.googleapis.com`	主要控制層 API。管理 `EnrichmentTask`、`EnrichmentRun`、情境組合、變更要求和 EnrichmentChatService。
BigQuery API	`bigquery.googleapis.com`	必須具備這項權限，才能掃描資料表結構定義、擷取 SQL 執行記錄，以及查詢 BigQuery 代理分析追蹤記錄資料表。
Cloud Storage API	`storage.googleapis.com`	必須具備這項權限，才能擷取評估集及管理評估資料集樣本。
IAM Service Account Credentials API	`iamcredentials.googleapis.com`	用於安全驗證執行代理程式，並在工作期間授予短期憑證 (SLC)。

設定客戶自行管理的服務帳戶

擴充工作會使用客戶自行管理的服務帳戶執行作業。這樣一來，您就能限制目標資料集的讀取和寫入權限。

建立服務帳戶。

如要建立服務帳戶，您必須是專案擁有者 (roles/owner) 或編輯者 (roles/editor)，或具備服務帳戶管理員角色 (roles/iam.serviceAccountAdmin)。

專屬服務帳戶會隔離擴充作業，讓您只授予這些工作所需的特定讀取和寫入權限，不影響其他工作負載。

如要建立服務帳戶，請按照下列步驟操作：
Google Cloud CLI

如要建立服務帳戶，請使用 gcloud iam service-accounts create 指令：

使用下列任何指令資料前，請先替換以下項目：
- SERVICE_ACCOUNT_NAME：服務帳戶名稱
執行下列指令：
Linux、macOS 或 Cloud Shell

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" \ --display-name="Knowledge Catalog enrichment agent SA"
Windows (PowerShell)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ` --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ` --display-name="Knowledge Catalog enrichment agent SA"
Windows (cmd.exe)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ^ --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ^ --display-name="Knowledge Catalog enrichment agent SA"
REST

使用任何要求資料之前，請先修改下列項目的值：
- SERVICE_ACCOUNT_NAME：服務帳戶名稱
- TARGET_PROJECT_ID：Google Cloud 專案 ID
HTTP 方法和網址：
POST https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts
JSON 要求主體：
{ "accountId": "SERVICE_ACCOUNT_NAME", "serviceAccount": { "displayName": "Knowledge Catalog enrichment agent SA", "description": "Service Account for Dataplex Knowledge Catalog enrichment agent execution" } }
請展開以下其中一個選項，以傳送要求：
curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts"
PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts" | Select-Object -Expand Content
您應該會收到執行成功的狀態碼 (2xx) 和空白回應。
在目標範圍內，將必要的資源層級 IAM 角色授予執行服務帳戶：
- Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 和 Dataplex Catalog 檢視者 (roles/dataplex.catalogViewer)：可讓代理檢查目錄中繼資料、建立暫存工作項目，以及手動發布已核准的擴充項目。
- (選用) Dataplex 工作流程核准者 (roles/dataplex.workflowApprover)：只有在啟用工作的「自動發布」功能時，才需要這個角色。可讓代理自動核准及發布自己的中繼資料變更要求。
- BigQuery 資料檢視者 (roles/bigquery.dataViewer)：可讓代理讀取資料表結構定義、資料欄中繼資料，以及代理數據分析追蹤資料表。
注意：下列程式碼範例會在專案層級授予這些角色，以便設定。如果是正式環境系統，強烈建議您在特定目標資料集的資源層級，安全地授予這些角色。

如要授予這些標準角色，請按照下列步驟操作：

如要為專案新增 IAM 政策繫結，請使用 gcloud projects add-iam-policy-binding 指令：

使用下列任何指令資料前，請先替換以下項目：
- SERVICE_ACCOUNT_NAME：服務帳戶名稱
- TARGET_PROJECT_ID：Google Cloud 專案 ID
執行下列指令：
Linux、macOS 或 Cloud Shell

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataViewer"
```
Windows (PowerShell)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/bigquery.dataViewer"
```
Windows (cmd.exe)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/bigquery.dataViewer"
```
授予使用者「服務帳戶使用者」角色 (roles/iam.serviceAccountUser)，允許他們模擬服務帳戶：

在控制台中建立擴充工作的使用者必須具備這項權限，才能指定這個服務帳戶並附加至工作。

如要將「服務帳戶使用者」角色授予使用者，請按照下列步驟操作：

如要為服務帳戶新增 IAM 政策繫結，請使用 gcloud iam service-accounts add-iam-policy-binding 指令：

使用下列任何指令資料前，請先替換以下項目：
- SERVICE_ACCOUNT_NAME：服務帳戶名稱
- TARGET_PROJECT_ID：Google Cloud 專案 ID
- USER_EMAIL：使用者的電子郵件地址
執行下列指令：
Linux、macOS 或 Cloud Shell

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="user:USER_EMAIL@domain.com" \
    --role="roles/iam.serviceAccountUser"
```
Windows (PowerShell)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="user:USER_EMAIL@domain.com" `
    --role="roles/iam.serviceAccountUser"
```
Windows (cmd.exe)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="user:USER_EMAIL@domain.com" ^
    --role="roles/iam.serviceAccountUser"
```
授予內部 Knowledge Catalog 服務代理「服務帳戶權杖建立者」角色 (roles/iam.serviceAccountTokenCreator)，允許其模擬這個服務帳戶：

這樣一來，基礎 Knowledge Catalog 服務就能在代表您執行背景擴充作業時，假定這個專屬服務帳戶的身分和受限制權限。

如要授權代理程式擔任服務帳戶身分，請按照下列步驟操作：

如要為服務帳戶新增 IAM 政策繫結，請使用 gcloud iam service-accounts add-iam-policy-binding 指令：

使用下列任何指令資料前，請先替換以下項目：
- SERVICE_ACCOUNT_NAME：服務帳戶名稱
- TARGET_PROJECT_ID：Google Cloud 專案 ID
- TARGET_PROJECT_NUMBER：Google Cloud 專案編號
執行下列指令：
Linux、macOS 或 Cloud Shell

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"
```
Windows (PowerShell)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" `
    --role="roles/iam.serviceAccountTokenCreator"
```
Windows (cmd.exe)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" ^
    --role="roles/iam.serviceAccountTokenCreator"
```

將必要的 IAM 角色授予使用者

為確保團隊能管理擴充工作流程，並審查 AI 生成的提案，請為使用者授予適當的 IAM 角色。如要瞭解如何授予這些角色，請參閱「管理專案、資料夾和組織的存取權」。

建立、設定及監控工作的工作流程管理員 (例如資料監管者) 須具備下列角色：

Dataplex DataScan 編輯者 (roles/dataplex.dataScanEditor) 或 Dataplex 編輯者 (roles/dataplex.editor)：可建立、修改、觸發及取消擴充工作。
客戶自行管理的服務帳戶的服務帳戶使用者 (roles/iam.serviceAccountUser)：必須將服務帳戶附加為工作的執行身分。

變更審查者 (例如網域擁有者或主題專家) 負責檢查、核准及發布 AI 生成的中繼資料提案至目錄，必須具備下列角色：

Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 和 Dataplex Catalog 檢視者 (roles/dataplex.catalogViewer)：必須具備這些角色，才能開啟變更要求、並排檢查提案差異，以及直接編輯說明。
Dataplex 工作流程核准者 (roles/dataplex.workflowApprover)：必須核准變更要求，並發布至實際目錄。
Dataplex DataScan 檢視者 (roles/dataplex.dataScanViewer) 或 Dataplex 檢視者 (roles/dataplex.viewer)：必須具備這項角色，才能查看各項提案的信賴分數、測試失敗診斷和下游評估評量表。

設定第三方驗證提供者

將擴充代理連結至第三方知識來源 (例如 Microsoft SharePoint、Atlassian Confluence 或 GitHub) 時，您必須使用 Google Cloud的代理身分服務設定驗證提供者。

代理身分會做為安全憑證管理工具，在專案中加密第三方權杖，確保人類操作員在執行工作時，不必處理原始用戶端密鑰。

如需逐步說明，瞭解如何產生必要權杖，以及為特定外部平台設定驗證提供者，請參閱「設定擴充工作的外部連接器」。

設定驗證供應商的 IAM 權限

如要允許擴充代理在執行期間，安全地動態擷取驗證提供者憑證，您必須將代理身分管理員 (roles/agentidentity.admin) 角色授予代管的 Knowledge Catalog 服務代理 (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com)。您可以在驗證提供者資源層級或專案層級授予這個角色。

此外，在Google Cloud 控制台中將驗證提供者附加至工作的人類使用者，必須具備驗證提供者的 agentidentity.authProviders.get 權限 (包含在代理身分檢視者 (roles/agentidentity.viewer) 中)。

準備 Cloud Storage bucket

Cloud Storage 是知識擴充工作流程的主要檔案型暫存、內容擷取和構件匯出層。

您可以設定代理，從一或多個輸入值區擷取檔案，根據企業領域知識進行推論。支援的情境類型包括：

網域說明文件和資料字典：Markdown、純文字、PDF、HTML 或 CSV 檔案，內含資料表定義、組織詞彙、標準作業程序 (SOP)、資料管道架構或資料欄命名指南。
評估資料集：JSONL 或 CSV 檔案，用於儲存種子查詢和保留的驗證查詢集。詳情請參閱「設定評估資料集的格式」。
參考 SQL 和轉換指令碼：已儲存的 SQL 指令碼、dbt 模型定義或 ETL 轉換邏輯，可提供資料表彙整模式和業務計算的比對內容信號。

設定完成後，擴充代理程式也能將結構化套件和執行構件匯出至輸出 bucket。支援的輸出構件包括：

詳細評估報表：提供全方位的評量表，顯示各查詢的準確度差異、測試失敗診斷，以及信賴度分布指標。

為確保擴充代理程式能從 bucket 運作，請確認執行服務帳戶具備必要權限。

在輸入 bucket 授予物件檢視者角色 (roles/storage.objectViewer)，讓代理讀取階段文件和設定檔。
(選用) 如果希望代理儲存執行構件和驗證記錄，請授予輸出 bucket 的物件建立者角色 (roles/storage.objectCreator)。

如要授予服務帳戶 Cloud Storage bucket 的存取權，請按照下列步驟操作：

如要將 IAM 政策繫結新增至 Storage bucket，請使用 gcloud storage buckets add-iam-policy-binding 指令：

使用下列任何指令資料前，請先替換以下項目：

CUSTOMER_BUCKET：Cloud Storage bucket 的名稱
SERVICE_ACCOUNT_NAME：服務帳戶名稱
TARGET_PROJECT_ID：Google Cloud 專案 ID

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Windows (PowerShell)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/storage.objectViewer"

Windows (cmd.exe)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/storage.objectViewer"

設定評估資料集的格式

擴充工作流程可以自動擷取資訊，不需提供範例。不過，提供評估資料集可讓代理自行測試並提高準確度。

您可以提供兩種資料集：

精選集：使用者問題範例和預期 SQL 查詢的清單。代理會使用這份清單練習，並編寫更優質的表格摘要。
評估集：用於評估代理效能的獨立問題清單。如果代理的成效不佳，這組評估資料可避免將不佳的更新發布至目錄。

或者，您也可以提供單一整合資料集。擴充服務會自動將資料分割為精選集和評估集。

資料集結構定義規定

評估資料集必須採用 JSONL 檔案格式，並儲存在 Cloud Storage。檔案中的每一行都必須包含自然語言問題，並搭配預期的基準真相 SQL 查詢。

請確認檔案符合 Gemini Enterprise Agent Platform 規定的評估資料集結構定義。下表列出可接受的格式欄位：

欄位名稱	類型	說明
`display_name`	`STRING`	選用。評估要求的 ID 或名稱。
`evaluation_request.prompt.text`	`STRING`	自然語言問題或使用者提示。
`evaluation_request.golden_response.candidate`	`STRING`	代表黃金回覆。設為 `golden`。
`evaluation_request.golden_response.text`	`STRING`	基準真相，也就是回答問題的已驗證 SQL 查詢。評分器會對資料執行這個 SQL。

下列程式碼片段顯示有效的 .jsonl 評估檔案：

{"display_name": "revenue-2026", "evaluation_request": {"prompt": {"text": "What is total revenue for customer C100 in 2026?"}, "golden_response": {"candidate": "golden", "text": "SELECT SUM(amount) FROM `project.dataset.orders` WHERE customer_id = 'C100' AND EXTRACT(YEAR FROM order_date) = 2026;"}}}
{"display_name": "monthly-subscribers", "evaluation_request": {"prompt": {"text": "List active subscribers on monthly billing"}, "golden_response": {"candidate": "golden", "text": "SELECT user_id, email FROM `project.dataset.subscriptions` WHERE status = 'ACTIVE' AND plan_type = 'MONTHLY';"}}}

如要瞭解如何建立高品質的評估資料集，請參閱 Gemini Enterprise Agent Platform 說明文件。

設定代理追蹤記錄，以便自主學習

如要讓擴充代理自動分析下游 Gemini Enterprise 代理互動 (或自訂 Gemini Enterprise Agent Platform 應用程式)，您可以選擇提供應用程式互動追蹤記錄的讀取權限。

代理擷取這些追蹤記錄後，就能執行軌跡探勘。代理會找出下游代理因缺少情境而遇到困難的地方，將常見的使用者問題分群為高影響力的查詢類別，並自動整理出解決這些落差所需的確切資料表摘要、資料欄語意和組織詞彙。

請根據企業架構，選擇下列其中一種設定方法：

使用範圍記錄檢視直接記錄：建立僅限應用程式遙測的記錄檢視，授予最小權限讀取權。這是建議採用的設定。
BigQuery 代理數據分析：如果貴組織會將互動記錄原生轉送至 BigQuery 記錄檔接收器，請授予匯出 BigQuery 資料集的讀取權限。

使用限定範圍的記錄檢視直接記錄 (建議)

為應用程式啟用互動記錄功能後，執行記錄會直接串流至 Logging。為遵循最小權限原則，請建立專屬記錄檢視，僅限特定應用程式存取，並授予執行服務帳戶該檢視的唯讀存取權。

建立範圍記錄檢視表，隔離記錄。這可確保擴充服務只會讀取特定設定應用程式的遙測資料 (例如透過篩選 resource.type="aiplatform.googleapis.com/Agent")，防止未經授權存取更廣泛的 Cloud 記錄。
gcloud CLI

如要建立限定範圍的記錄檢視表，請使用 gcloud logging views create 指令：

使用下列任何指令資料前，請先替換以下項目：
- LOG_VIEW_NAME：記錄檔檢視表的名稱
- YOUR_GEMINI_ENTERPRISE_APP_ID：Gemini Enterprise 應用程式 ID
執行下列指令：
Linux、macOS 或 Cloud Shell

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。

gcloud logging views create LOG_VIEW_NAME \ --location=global \ --bucket=_Default \ --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'
Windows (PowerShell)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。

gcloud logging views create LOG_VIEW_NAME ` --location=global ` --bucket=_Default ` --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'
Windows (cmd.exe)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。

注意： 如果這個指令使用 ' 引用內容，請將這些單引號替換為雙引號。如果引號為巢狀結構，請使用 \" 逸出內部引號。

gcloud logging views create LOG_VIEW_NAME ^ --location=global ^ --bucket=_Default ^ --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'
REST

使用任何要求資料之前，請先修改下列項目的值：
- LOG_VIEW_NAME：記錄檔檢視表的名稱
- TARGET_PROJECT_ID：Google Cloud 專案 ID
- YOUR_GEMINI_ENTERPRISE_APP_ID：Gemini Enterprise 應用程式 ID
HTTP 方法和網址：
POST https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME
JSON 要求主體：
{ "filter": "resource.type=\"aiplatform.googleapis.com/Agent\" AND resource.labels.agent_id=\"YOUR_GEMINI_ENTERPRISE_APP_ID\"" }
請展開以下其中一個選項，以傳送要求：
curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME"
PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME" | Select-Object -Expand Content
您應該會收到執行成功的狀態碼 (2xx) 和空白回應。
建立記錄檔檢視表後，請授予執行服務帳戶對該檢視表的讀取權限。這樣一來，擴充工作就能在自我學習階段，提取所需的應用程式遙測資料。

如要將 IAM 政策繫結新增至記錄檢視，請使用 gcloud logging views add-iam-policy-binding 指令：

使用下列任何指令資料前，請先替換以下項目：
- LOG_VIEW_NAME：記錄檔檢視表的名稱
- SERVICE_ACCOUNT_NAME：服務帳戶名稱
- TARGET_PROJECT_ID：Google Cloud 專案 ID
執行下列指令：
Linux、macOS 或 Cloud Shell

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud logging views add-iam-policy-binding LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/logging.viewAccessor"
```
Windows (PowerShell)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud logging views add-iam-policy-binding LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/logging.viewAccessor"
```
Windows (cmd.exe)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，透過驗證和專案初始化 Google Cloud CLI。
```
gcloud logging views add-iam-policy-binding LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/logging.viewAccessor"
```

詳情請參閱「設定記錄檔 bucket 的記錄檔檢視表」。

BigQuery 代理分析

如果貴組織使用 Logging 記錄檔接收器，將互動記錄檔串流至 BigQuery，或直接寫入 BigQuery 代理分析資料表，則可改為授予資料集存取權。

請確認互動記錄已設為串流至指定的 BigQuery 資料集，並確認執行服務帳戶已獲派該資料集的 BigQuery 資料檢視者角色 (roles/bigquery.dataViewer)。這樣一來，代理就能直接從 BigQuery 讀取匯出的遙測資料。

如要進一步瞭解如何匯出記錄，請參閱「將記錄轉送至支援的目的地」。

啟用資料剖析和資料洞察功能

執行擴充工作前，建議您先為常用的目標資料表啟用資料剖析和 AI 資料洞察功能。資料剖析會提供統計特徵，例如常見值、資料分布和空值計數，而資料洞察則會生成基準資料表說明和範例查詢。提供這些信號有助於擴充代理生成更準確的中繼資料提案。

如要進一步瞭解如何設定資料剖析掃描，請參閱「建立及使用資料剖析掃描」。
如要進一步瞭解如何生成 AI 資料洞察，請參閱「使用結構化資料的資料洞察」。

後續步驟

瞭解如何建立擴充工作。

設定充實工作的前置作業 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要 API 詳細資料

設定客戶自行管理的服務帳戶

Google Cloud CLI

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

將必要的 IAM 角色授予使用者

設定第三方驗證提供者

設定驗證供應商的 IAM 權限

準備 Cloud Storage bucket

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

設定評估資料集的格式

資料集結構定義規定

設定代理追蹤記錄，以便自主學習

使用限定範圍的記錄檢視直接記錄 (建議)

gcloud CLI

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

BigQuery 代理分析

啟用資料剖析和資料洞察功能

後續步驟

設定充實工作的前置作業