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

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

支援的服務：

Google SecOps SIEM

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

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

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

這項代管管道服務提供重要的企業級功能，包括：

發生暫時性錯誤時自動重試
全方位監控工作狀態
每項匯出工作的完整稽核追蹤記錄

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

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

主要優點

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

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

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

重要詞彙與概念

匯出工作：單一非同步作業，可將特定日期範圍的記錄資料匯出至 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：包含原始記錄的分區檔案名稱。每個檔案 shard 的大小上限為 100 MB。

效能和限制

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

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

必要條件和架構

本節概述使用 Data Export API 的系統架構和必要需求，並詳細說明系統架構。請使用這項資訊，確認環境設定正確無誤。

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

將權限授予使用者。如要使用 Data Export API，您必須在連結至 Google SecOps 租戶的 BYOP Google Cloud 專案中，具備下列權限：
這些權限是下列預先定義 IAM 角色的一部分：
- Chronicle API 管理員：授予完整權限，可使用 API 建立、更新、取消及查看匯出工作。這個角色會授予全域存取權。
- Chronicle API 檢視者：授予唯讀存取權，可使用 API 查看工作設定和記錄。如果沒有 restrictedDataAccess 角色，具備這個角色的使用者可以查看所有資料 (請參閱「+ 新增其他角色步驟」和「新增條件」)。
將資料 RBAC 範圍套用至使用者。如要限制使用者只能存取特定資料，請按照下列步驟操作：
1. 請確認您要套用的資料 RBAC 範圍，已在 Google SecOps 使用者介面中建立，路徑為「設定」>「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」。
2. 點選「+ 授予存取權」。
3. 在「新增主體」部分，輸入使用者的電子郵件地址。
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 Cloud專案中，建立新的 Google Cloud Storage bucket (匯出資料的目的地)，區域須與 Google SecOps 租戶相同。將其設為私人，防止未經授權的存取。詳情請參閱「建立 bucket」。
將權限授予服務帳戶。請按照下列步驟操作，將必要的 IAM 角色授予連結至 Google SecOps 租戶的 Google SecOps 服務帳戶，以便將資料寫入 bucket：
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. 將目的地 Google Cloud Storage bucket 的下列 IAM 角色授予 Google SecOps 服務帳戶主體，讓 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. 應用程式預設憑證

主要用途和核心工作流程

Data Export API 提供一組端點，可用於建立資料匯出工作，以及管理大量資料匯出的整個生命週期。所有互動都是透過 API 呼叫執行。

下列用途說明如何建立、監控及管理資料匯出工作。

建立新的資料匯出工作

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

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

監控資料匯出工作狀態

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

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

取消已排入佇列的工作

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

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

資料 RBAC 如何套用至 Data Export 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 專業人員尋求解答。