我們重新調整了說明文件的導覽結構，直接對應您的作業工作流程。詳情請參閱版本資訊和逐步解說影片。

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

將原始記錄匯出至自行管理的 Google Cloud Storage bucket

支援的國家/地區：

Google SecOps SIEM

透過資料匯出 API，您可以將 Google Security Operations 中的大量安全資料匯出至您控管的 Google Cloud Storage bucket。這項功能支援長期保留重要資料、進行歷史鑑識分析，以及符合嚴格的法規遵循要求 (例如 SOX 和 GDPR)。

如需詳細的 API 參考資料，請參閱「資料匯出 API (強化版)」。

資料匯出 API 提供可擴充且可靠的解決方案，可匯出特定時間點的資料，並處理最多 100 TB 的要求。

這項代管管道提供多項企業級基本功能，包括：

暫時性錯誤發生時自動重試
全面監控工作狀態
每個匯出作業的完整稽核記錄

API 會在 Google Cloud Storage bucket 中，依日期和時間邏輯分割匯出的資料。

這項功能可讓您建構大規模資料卸載工作流程。Google SecOps 會管理複雜的匯出程序，確保穩定性和效能。

主要優點

資料匯出 API 提供可稽核的彈性解決方案，可管理安全資料的生命週期，主要優點如下：

可靠性：這項服務可處理大規模資料移轉作業。系統會使用指數輪詢策略，自動重試遇到暫時性問題 (例如暫時性網路問題) 的匯出工作，因此具有復原能力。如果匯出工作因暫時性錯誤而失敗，系統會自動重試幾次。如果工作在所有重試次數用盡後仍永久失敗，系統會將狀態更新為 FINISHED_FAILURE，且該工作的 API 回應會包含詳細的錯誤訊息，說明失敗原因。
完善的稽核功能：為符合嚴格的法規和安全標準，系統會將與匯出工作相關的所有動作，記錄在不可變更的稽核追蹤記錄中。這項記錄包括每項工作的建立、啟動、成功或失敗，以及啟動動作的使用者、時間戳記和工作參數。

注意： API 沒有內建排程器，無法設定每日匯出功能以符合法規。如要設定每日定期匯出，請自行建立自動化動作。
效能和規模最佳化：API 使用強大的工作管理系統。這個系統包含佇列和優先順序機制，可確保平台穩定性，並防止任何單一租戶獨占資源。
提升資料完整性和存取權：系統會自動將資料整理到 Google Cloud Storage 值區內的邏輯目錄結構中，方便您找出及查詢特定時間範圍的資料，進行歷來分析。
安全性：這項 API 的設計完全符合客戶管理的加密金鑰 (CMEK) (零信任安全) 和資料 RBAC (最低權限存取權) 規定。匯出工作會沿用觸發要求的使用者資料可見範圍，防止未經授權的資料擷取作業。匯出管道也與 Google Cloud Key Management Service 完全整合，資料在 Google Cloud Storage 值區中仍會使用您自己的金鑰加密。

重要詞彙與概念

匯出作業：單一非同步作業，可將特定時間範圍的記錄資料匯出至 Google Cloud Storage bucket。系統會使用專屬 dataExportId 追蹤每項工作。
工作狀態：匯出工作在生命週期中的目前狀態 (例如 IN_QUEUE、PROCESSING、FINISHED_SUCCESS)。
Google Cloud Storage bucket：使用者擁有的 Google Cloud Storage bucket，做為匯出資料的目的地。
記錄類型：可匯出的特定記錄類別 (例如 NIX_SYSTEM、WINDOWS_DNS、CB_EDR)。詳情請參閱所有支援的記錄類型清單。

瞭解匯出資料的結構

工作順利完成後，系統會將資料寫入 Google Cloud Storage bucket。並使用特定分區目錄結構，簡化資料存取和查詢作業。

目錄路徑結構： gs://GCS_BUCKET_NAME/ EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/FILE_SHARD_NAME.csv

其中：

GCS_BUCKET_NAME：是指 Google Cloud Storage bucket 的名稱。
EXPORT_JOB_NAME：是指匯出工作的專屬名稱。
LOGTYPE：指匯出資料的記錄類型名稱。
EVENT_TIME_BUCKET：指匯出記錄的事件時間戳記小時範圍。格式為世界標準時間時間戳記：year/month/day/UTC-timestamp，其中 UTC-timestamp 為 hour/minute/second。例如，2025/08/25/01/00/00 是指 UTC 01:00:00 AM, August 25, 2025。
EPOCH_EXECUTION_TIME：是指 Unix 紀元時間值，表示匯出作業的開始時間。
FILE_SHARD_NAME：是指包含原始記錄的檔案名稱。每個檔案分片的大小上限為 100 MB。

效能和限制

為確保平台穩定性及資源分配公平性，這項服務設有下列具體限制：

每項工作的資料量上限：每項匯出工作最多可要求 100 TB 的資料。如果是較大的資料集，Google 建議將匯出作業拆成多個工作，並縮小時間範圍。
並行工作：每個客戶租戶最多可同時執行或排隊三項匯出工作。如果新工作建立要求超出上限，系統會拒絕。
工作完成時間：匯出資料量決定工作完成時間。單一工作最多可能需要 18 小時。
匯出格式和資料範圍：API 支援大量匯出特定時間點的資料，但有下列限制和功能：
- 僅限原始記錄：您只能匯出原始記錄 (而非 UDM 記錄、UDM 事件或偵測結果)。如要瞭解如何匯出 UDM 資料，請參閱「匯出至自行管理的 BigQuery 專案」。
- 資料壓縮：API 會以未壓縮的文字格式匯出資料。

先決條件和架構

本節將說明使用資料匯出 API 的系統架構和必要條件，並詳細介紹系統架構。請使用這項資訊確認環境設定正確無誤。

使用 Data Export API 前，請先完成下列必要步驟，設定 Google Cloud Storage 目的地並授予必要權限：

授予使用者權限。如要使用資料匯出 API，您必須在連結至 Google SecOps 租戶的 BYOP Google Cloud 專案中具備下列權限：
下列預先定義的 IAM 角色具備這些權限：
- Chronicle API 管理員：授予完整權限，可使用 API 建立、更新、取消及查看匯出作業。這個角色具有全域存取權。
- Chronicle API 檢視者：授予唯讀存取權，可使用 API 查看工作設定和記錄。如果沒有 restrictedDataAccess 角色，擁有這個角色的使用者可以查看所有資料 (請參閱「+ 新增其他角色」步驟和新增條件)。
將資料 RBAC 範圍套用至使用者。如要限制使用者只能存取特定資料存取權範圍，請按照下列步驟操作：
1. 請確認您要套用的資料 RBAC 範圍已在 Google SecOps UI 中建立，路徑為「設定」>「SIEM 設定」>「資料存取權」>「範圍」。請記下您要指派給使用者的每個範圍完整名稱。
2. 建立 Identity and Access Management (IAM) 自訂角色，用於管理資料匯出作業。由於預先定義的角色可能會授予過多存取權，或不具備特定權限組合，請按照下列步驟建立自訂角色，以便在限定範圍內管理資料匯出作業：
  1. 在 Google Cloud 控制台中，依序前往「IAM & Admin」(IAM 與管理)>「Roles」(角色)。
  2. 按一下「+ 建立角色」。
  3. 輸入標題 (例如 SecOps Scoped Data Export User)。
  4. 輸入 ID (例如 secopsScopedDataExportUser)。
  5. 按一下「+ 新增權限」。
  6. 篩選 Chronicle 權限，然後新增第一個步驟 (授予 API 使用者權限) 中列出的相關權限。
  7. 點選「建立」。
將 IAM 角色授予使用者。在「IAM」頁面中，為使用者指派必要角色：
1. 前往「IAM & Admin」(IAM 與管理員) >「IAM」(IAM)。
2. 點選「+ 授予存取權」。
3. 在「New principals」(新增主體) 中，輸入使用者的電子郵件地址。
4. 如要指派角色，請按照下列步驟操作：
  1. 新增您建立的自訂角色 (例如 SecOps Scoped Data Export User)。
  2. 點選「+ 新增其他角色」，然後新增「Chronicle API 有限資料存取權」 (restrictedDataAccess) 角色。這個角色非常重要，可將使用者標示為受資料範圍限制。
在 Chronicle API Restricted Data Access 角色繫結中新增 IAM 條件。如要將使用者連結至特定資料範圍，請按照下列步驟操作：
1. 按一下「新增 IAM 條件」。
2. 使用條件建構工具或條件編輯器定義允許的範圍，並將在第一個步驟中建立的範圍名稱做為資源名稱。舉例來說，如要使用名為 scope_test 的範圍，請設定條件 resource.name.endsWith("/dataAccessScopes/scope_test")。
如要進一步瞭解如何為 Data Export API 導入資料 RBAC，請參閱「資料 RBAC 如何套用至 Data Export API」。
建立 Google Cloud Storage bucket。在專案中，於與 Google SecOps 租戶相同的區域，建立新的 Google Cloud Storage bucket (匯出資料的目的地)。 Google Cloud設為私人，防止未經授權的存取。詳情請參閱「建立值區」一節。
將權限授予服務帳戶。請按照下列步驟，將必要的 IAM 角色授予連結至 Google SecOps 租戶的 Google SecOps 服務帳戶，以便將資料寫入值區：
1. 呼叫 FetchServiceAccountForDataExport API 端點，找出 Google SecOps 執行個體的專屬服務帳戶。API 會傳回服務帳戶電子郵件地址。
  
  要求範例：
```
{
  "parent": "projects/myproject/locations/us/instances/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}
```
  回應範例：
```
{
  "service_account_email": "service-1234@gcp-sa-chronicle.iam.gserviceaccount.com"
}
```
2. 將下列 IAM 角色授予 Google SecOps 服務帳戶主體，以便存取目的地 Google Cloud Storage bucket，讓 Google SecOps 服務將匯出的資料檔案寫入 Google Cloud Storage bucket：
  - Storage object administrator (roles/storage.objectAdmin)
  - Legacy bucket reader (roles/storage.legacyBucketReader)
  詳情請參閱「授予 Google SecOps 服務帳戶存取權」。
完成驗證。Data Export API 會驗證您的呼叫。如要設定這項驗證機制，請按照下列章節的指示操作：
1. Google Cloud 服務的驗證方式
2. 應用程式預設憑證

主要用途和核心工作流程

資料匯出 API 提供一系列端點，可建立資料匯出工作，並管理大量資料匯出的整個生命週期。您可以使用 API 呼叫執行所有互動。

以下使用案例說明如何建立、監控及管理資料匯出工作。

建立新的資料匯出工作

系統會將資料匯出工作規格儲存在父項資源 Google SecOps 執行個體中。這個執行個體是匯出工作的記錄資料來源。

如要瞭解如何找出 Google SecOps 執行個體的專屬服務帳戶，請參閱 FetchServiceAccountForDataExports。
如要開始新的匯出作業，請向 dataExports.create 端點傳送 POST 要求。詳情請參閱 CreateDataExport 端點。

監控資料匯出工作狀態

您可以查看特定匯出工作的資料匯出工作詳細資料和狀態，也可以設定篩選器來查看特定類型的工作。

如要瞭解如何查看特定匯出工作，請參閱 GetDataExport。
如要瞭解如何使用篩選器列出特定類型的資料匯出工作，請參閱 ListDataExport。

取消已排入佇列的工作

工作狀態為 IN_QUEUE 時，您可以取消工作。

如要瞭解如何取消已排入佇列的工作，請參閱 CancelDataExport。

資料 RBAC 如何套用至資料匯出 API

匯出工作會沿用建立匯出工作的使用者資料 RBAC 範圍，防止未經授權的資料擷取作業。

如果您嘗試匯出超出資料存取權範圍的資料，API 會在執行匯出作業時自動排除這類資料。已完成工作 (即狀態為 FINISHED_SUCCESS 的工作) 中繼資料的 dataRbacFiltered 欄位值，會指出資料是否已排除。如果 dataRbacFiltered 為 true，表示系統已排除部分或所有選取的匯出工作資料，因為這些資料超出適用於工作建立者的資料 RBAC 範圍。如果 dataRbacFiltered 為 false，表示匯出工作未受資料 RBAC 範圍限制影響，且工作中的所有資料都已成功匯出。

API 會套用工作建立時適用於建立者的資料 RBAC 範圍。資料 RBAC 範圍的任何變更，都不會追溯套用至已建立的工作。

如要進一步瞭解資料 RBAC，請參閱「資料 RBAC 總覽」。

疑難排解常見問題

API 會提供詳細的錯誤訊息，協助您診斷問題。

標準代碼	錯誤訊息
`INVALID_ARGUMENT`	`INVALID_REQUEST: Invalid request parameter PARAMETER_1, PARAMETER_2, ... PARAMETER_N. Please fix the request parameters and try again.`
`PERMISSION_DENIED`	`INSUFFICIENT_PERMISSIONS: Unable to validate request with the current CMEK key. Please fix the CMEK key and try again`
`NOT_FOUND`	`BUCKET_NOT_FOUND: The destination Google Cloud Storage bucket BUCKET_NAME does not exist. Please create the destination Google Cloud Storage bucket and try again.`
`NOT_FOUND`	`REQUEST_NOT_FOUND: The dataExportId:DATA_EXPORT_ID does not exist. Please add a valid dataExportId and try again.`
`FAILED_PRECONDITION`	`BUCKET_INVALID_REGION: The Google Cloud Storage bucket BUCKET_ID's region:REGION_1 is not the same region as the SecOps tenant region:REGION_2. Please create the Google Cloud Storage bucket in the same region as SecOps tenant and try again.`
`FAILED_PRECONDITION`	`INSUFFICIENT_PERMISSIONS: The Service Account P4SA does not have storage.objects.create, storage.objects.get and storage.buckets.get permissions on the destination Google Cloud Storage bucket BUCKET_NAME. Please provide the required access to the Service Account and try again.`
`FAILED_PRECONDITION`	`INVALID_CANCELLATION: The request status is in the STATUS stage and can't be cancelled. You can only cancel the request if the status is in the IN_QUEUE stage.`
`RESOURCE_EXHAUSTED`	`CONCURRENT_REQUEST_LIMIT_EXCEEDED: Maximum concurrent requests limit LIMIT reached for the request size SIZE_LIMIT. Please wait for the existing requests to complete and try again.`
`RESOURCE_EXHAUSTED`	`REQUEST_SIZE_LIMIT_EXCEEDED: The estimated export volume: ESTIMATED_VOLUME for the request is greater than maximum allowed export volume: ALLOWED_VOLUME per request. Please try again with a request within the allowed export volume limit.`
`INTERNAL`	`INTERNAL_ERROR: An Internal error occurred. Please try again.`

還有其他問題嗎？向社群成員和 Google SecOps 專業人員尋求答案。