將原始記錄匯出至自行管理的 Google Cloud 儲存空間 bucket

支援的國家/地區：

Google SecOps SIEM

注意： 這項功能受《Google Security Operations 服務專屬條款》的《正式發布前產品條款》規範。正式發布前的功能或許只提供部分支援，而且這類功能的變更可能與其他正式發布前版本不相容。詳情請參閱《Google SecOps 技術支援服務指南》和《Google SecOps 服務專屬條款》。

注意： 搶先體驗 - 如要啟用 Data Export API 的強化功能，請與 Google SecOps 租戶的支援團隊聯絡。啟用這項功能後，您就能存取新的 API 方法和強化屬性。

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

重要事項：啟用新的強化版 API 後，您就無法使用 API 存取舊有工作。

如要進一步瞭解 Data Export API，請參閱「Data Export API (增強版)」

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

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

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

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

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

主要優點

資料匯出 API 提供可稽核的彈性解決方案，方便您管理安全資料的生命週期。

• 可靠性：這項服務可處理大規模資料移轉作業。系統會使用指數輪詢策略，自動重試遇到暫時性問題 (例如暫時性網路問題) 的匯出工作，因此具有彈性。如果匯出工作因暫時性錯誤而失敗，系統會自動重試多次。如果工作在所有重試次數用盡後仍永久失敗，系統會將狀態更新為 FINISHED_FAILURE，且該工作的 API 回應會包含詳細的錯誤訊息，說明失敗原因。

• 完善的稽核功能：為符合嚴格的法規和安全標準，系統會將與匯出工作相關的所有動作，記錄在不可變更的稽核追蹤中。這項記錄會列出每項工作的建立、啟動、成功或失敗情形，以及啟動動作的使用者、時間戳記和工作參數。

  注意： 目前版本的 API 沒有內建排程器，無法設定每日匯出功能以符合法規。如要設定每日週期性匯出，請自行建立自動化動作。

• 效能和規模最佳化：API 使用強大的工作管理系統。這個系統包含佇列和優先順序機制，可確保平台穩定性，並避免單一租戶壟斷資源。

• 提升資料完整性和存取權：系統會自動將資料整理到 Google Cloud Storage 儲存空間值區內的邏輯目錄結構中，方便您找出特定時間範圍的資料，並進行歷來分析。

重要詞彙與概念

• 匯出作業：單一非同步作業，可將特定時間範圍的記錄資料匯出至 Google Cloud Storage 值區。系統會使用專屬 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 的資料。如果是較大的資料集，建議將匯出作業拆成多個工作，並縮小時間範圍。
• 並行工作：每個客戶租戶最多可同時執行或排定 3 項匯出工作。如果新工作建立要求超過這個上限，系統就會拒絕。
• 工作完成時間：匯出資料量決定工作完成時間。單一工作最多可能需要 18 小時。
• 匯出格式和資料範圍：這項 API 支援大量匯出特定時間點的資料，但有下列限制和功能：
  • 僅限原始記錄：您只能匯出原始記錄 (而非 UDM 記錄、UDM 事件或偵測結果)。如要匯出 UDM 資料，請參閱在自行管理的專案中，設定將資料匯出至 BigQuery Google Cloud。
  • 資料壓縮：API 會以未壓縮的文字格式匯出資料。

先決條件和架構

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

事前準備

使用資料匯出 API 前，請先完成下列必要步驟，設定 Google Cloud Storage 目的地並授予必要權限。

1. 授予 API 使用者權限：如要使用資料匯出 API，您需要下列 IAM 角色。

   • Chronicle administrator (creating/managing jobs)：授予完整權限，可使用 API 建立、更新、取消及查看匯出作業。
   • Chronicle Viewer：授予唯讀存取權，可使用 API 查看工作設定和記錄。

2. 建立 Google Cloud Storage 值區：在專案中，於與 Google SecOps 租戶相同的區域，建立新的 Google Cloud Storage 值區 (匯出資料的目的地)。 Google Cloud設為私人，防止未經授權的存取行為。詳情請參閱「建立值區」。

3. 授予服務帳戶權限：將必要的 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": "[e-mail]"
      }
      

   2. 將下列 IAM 角色授予目的地 Google Cloud Storage bucket 的 Google SecOps 服務帳戶主體：這個角色可讓 Google SecOps 服務將匯出的資料檔案寫入 Google Cloud Storage bucket。

      • Storage object administrator (roles/storage.objectAdmin)
      • Legacy bucket reader (roles/storage.legacyBucketReader)

      詳情請參閱「授予 Google SecOps 服務帳戶存取權」。

4. 完成驗證：Data Export API 會驗證您的呼叫。如要設定這項驗證機制，請按照下列章節的指示操作：

   1. Google Cloud 服務的驗證方式
   2. 應用程式預設憑證

主要用途

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

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

核心工作流程

本節說明如何管理匯出工作的生命週期。

建立新的資料匯出工作

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

• 找出 Google SecOps 執行個體的專屬服務帳戶。 詳情請參閱「FetchServiceAccountForDataExports」。

• 如要開始新的匯出作業，請向 dataExports.create 端點傳送 POST 要求。
  詳情請參閱 CreateDataExport 端點。

監控資料匯出工作狀態

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

• 如要查看特定匯出工作，請參閱 GetDataExport。

• 如要使用篩選器列出特定類型的資料匯出工作，請參閱 ListDataExport。

管理已排入佇列的工作

工作處於 IN_QUEUE 狀態時，您可以修改或取消工作。

• 如要變更參數 (例如時間範圍、記錄類型清單或目的地值區)，請參閱 UpdateDataExport。

• 如要取消已加入佇列的工作，請參閱 CancelDataExport。

疑難排解常見問題

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

標準程式碼	錯誤訊息
INVALID_ARGUMENT	INVALID_REQUEST：要求參數 <Parameter1, Parameter2,..> 無效。請修正要求參數，然後再試一次。
NOT_FOUND	BUCKET_NOT_FOUND：目的地 Google Cloud Storage bucket「<bucketName>」不存在。請建立目標 Google Cloud Storage bucket，然後再試一次。
NOT_FOUND	REQUEST_NOT_FOUND：資料匯出 ID：<dataExportId> 不存在。請新增有效的 dataExportId，然後再試一次。
FAILED_PRECONDITION	BUCKET_INVALID_REGION：Google Cloud Storage bucket「<bucketId>」的區域「<region1>」與 SecOps 租戶區域「<region2>」不同。請在與 SecOps 租戶相同的區域建立 Google Cloud Storage bucket，然後再試一次。
FAILED_PRECONDITION	INSUFFICIENT_PERMISSIONS：服務帳戶 <P4SA> 對於目的地 Google Cloud Storage bucket <bucketName> 沒有 storage.objects.create、storage.objects.get 和 storage.buckets.get 權限。請為服務帳戶提供必要存取權，然後再試一次。
FAILED_PRECONDITION	INVALID_UPDATE：要求狀態處於「<status>」階段，因此無法更新。只有在狀態為「IN_QUEUE」階段時，才能更新要求。
FAILED_PRECONDITION	INVALID_CANCELLATION：要求狀態處於「<status>」階段，因此無法取消。只有在狀態為「IN_QUEUE」階段時，才能取消要求。
RESOURCE_EXHAUSTED	CONCURRENT_REQUEST_LIMIT_EXCEEDED：要求大小 <sizelimit> 已達並行要求上限 <limit>。請等待現有要求完成，然後再試一次。
RESOURCE_EXHAUSTED	REQUEST_SIZE_LIMIT_EXCEEDED：要求的預估匯出量 (<estimatedVolume>) 大於每個要求允許的匯出量上限 (<allowedVolume>)。請再次嘗試提出要求，但須符合允許的匯出量上限。
INTERNAL	INTERNAL_ERROR：發生內部錯誤。請再試一次。

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