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

從舊版 SIEM API 遷移至 Chronicle API

支援的服務：

Google SecOps SIEM

本文說明如何管理呼叫舊版 SIEM API (Backstory API 和 Ingestion API) 的應用程式。其中說明設定程式輔助存取權，以及將舊版 SIEM API 端點的所有參照更新為新版 Chronicle API 端點的必要步驟。

如要快速瞭解遷移程序，請觀看嵌入的影片。

Chronicle API 介面推出多項改良功能，可簡化開發流程，並符合 Google Cloud API 標準，提高可靠性、安全性和效能，並與 Cloud 稽核記錄、Cloud Monitoring、Cloud Identity 和 Identity and Access Management (IAM) 整合。此外，這項 API 也解決了舊版 API 的許多限制和複雜問題。

有何異動

所有向舊版 Backstory API 和 Ingestion API 端點發出的程式輔助要求，都必須改用新版 Chronicle API。如果貴組織使用自訂整合、自動化指令碼或第三方工具，且會呼叫這些舊版端點，請務必在 2027 年 7 月 20 日前更新這些工作負載，改用新版端點和驗證流程。此外，如果貴組織使用 Google Security Operations SOAR，請務必更新 SOAR 整合服務和連接器 (例如 Google Chronicle 整合服務)，改用 Chronicle API。詳情請參閱「遷移 SOAR 整合功能」。

維持不變的部分

直接在 Google Security Operations 使用者介面 (UI) 執行的動作，已叫用新版 Chronicle API。如果貴組織只透過 UI 與 Google SecOps 互動，或整合服務已呼叫 Chronicle API 端點，則不須採取任何行動。

主要異動和強化功能

下表列出舊版 SIEM API 和 Chronicle API 的主要差異：

功能區域	舊版 SIEM API	Chronicle API	詳細資料
憑證管理	需要 Google 代表參與的人工作業	自助管理服務帳戶、憑證和 IAM 權限	自助式憑證和 IAM 管理功能可簡化新手上路流程，不必再手動提出支援要求。
法規遵循標準	支援能力有限	內建支援資料落地控管、VPC Service Controls、資料存取透明化控管機制、CMEK 和 FedRAMP	內建現代化基礎架構控管機制，符合業界法規遵循和監管標準。
記錄和稽核	舊版稽核串流	Cloud 稽核記錄已整合至 Google Cloud 專案	直接整合可提供集中式稽核追蹤記錄和監控功能。
驗證	API 權杖和服務帳戶憑證	OAuth 2.0 支援新式驗證方法，包括 Workload Identity 和服務帳戶，詳情請參閱「 Google Cloud API 和服務的驗證」	這些新式驗證方式可強化安全性，並標準化憑證流程。
資料模型和 API 設計	扁平、專屬結構	資源導向設計、RESTful 架構，以及遵循 AIP 的標準化命名	這項現代化設計可提升資料一致性、讓 API 更直觀，並簡化物件操作。
端點命名	不一致	RESTful 和標準化	一致的命名方式可讓 API 更直覺，也更容易整合。
生態系統	非常有限	與 MCP、Terraform、用戶端程式庫和 SDK 整合	廣泛相容於現代雲端工具和自動化架構。
合作夥伴授權	直接在客戶程式碼中使用合作夥伴權杖或 API 金鑰	租戶資源的跨專案 IAM 委派；合作夥伴範圍的 TenantService 方法	TenantService 方法會在合作夥伴專案中執行。所有其他租戶 API 都需要租戶在租戶專案中授予跨專案 IAM 委派權限。

合作夥伴授權

如果是多租戶合作夥伴工作流程，Chronicle API 的授權取決於資源擁有權。託管資源的專案會決定合作夥伴需要哪些憑證和 IAM 權限。將租戶作業範圍限定為租戶委派的憑證，符合核心安全性原則，即合作夥伴在未經租戶明確授權的情況下，不得存取、擷取或修改租戶資料。下表比較舊版 Backstory API 和 Chronicle API 的合作夥伴授權：

API	方法	資源範圍	授權
舊版 Backstory API	`/v1/partner/customer/*` 個端點	合作夥伴的所有客戶代碼	合作夥伴會直接使用自己的合作夥伴權杖或 API 金鑰呼叫這些端點。
Chronicle API：`TenantService`	`CreateTenant`、`ListTenants` 和 `UpdateTenant`	合作夥伴的執行個體：`projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/*`	合作夥伴會直接使用自己的服務帳戶或憑證呼叫這些方法，這些帳戶或憑證在合作夥伴專案中具有 `chronicle.googleapis.com/tenants.*` 權限。
Chronicle API：其他服務，例如 `InstanceService` 和 `ForwarderService`	`GetInstance`、`UpdateInstance`、`GenerateForwarderFiles` 和其他租戶範圍方法	租戶的執行個體：`projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/...`	合作夥伴憑證本身無法存取或修改租戶資料。租戶管理員必須在租戶的 Google Cloud 專案中，將 IAM 角色 (例如 `roles/chronicle.admin`、`roles/chronicle.viewer` 或自訂角色) 授予合作夥伴的服務帳戶或 Workload Identity Federation 主體。

淘汰時程

舊版 SIEM API 預計於 2027 年 7 月 20 日停用。建議您在上述日期前完成遷移，以免服務中斷：

2026 年 10 月 26 日起，您將無法再從新執行個體呼叫舊版 API (Backstory API 和 Ingestion API)。
2027 年 7 月 20 日前，您必須將所有現有執行個體遷移至 Chronicle API，因為舊版 API 將不再可用。

事前準備

遷移至 Chronicle API 之前，請務必完成下列事項：

在現代化 SIEM 基礎架構上部署：請確認執行個體是使用現代化 SIEM 基礎架構，部署在您或 MSSP 合作夥伴的 Google Cloud 專案中。如需詳細操作說明，請參閱「SIEM 遷移總覽」。
啟用 Chronicle API：在 Google Cloud 控制台中，前往託管執行個體的專案，並啟用 Chronicle API (chronicle.googleapis.com)。詳情請參閱「在 Google Cloud 專案中啟用 API」。
找出 SOAR 整合項目：如果環境將 Google SecOps SOAR 連結至 Google Security Operations SIEM，請確認現有連接器。詳情請參閱「遷移 SOAR 整合項目」。

遷移 SOAR 整合項目

如果貴組織將 Google SecOps SOAR 連結至 Google SecOps SIEM，則必須遷移 SOAR 整合項目和連接器 (例如 Google Chronicle 整合項目)，才能使用 Chronicle API。

如需升級 Google Chronicle 整合服務和連接器，改用 Chronicle API 的詳細操作說明 (包括找出環境的 Chronicle API 根目錄，以及設定驗證憑證)，請參閱「從 Backstory API 遷移至 Chronicle API」。

遷移至 Chronicle API

請按照下列步驟，將自訂指令碼和整合服務從舊版 API 遷移至 Chronicle API：

稽核 API 使用情形：找出環境中叫用舊版端點的所有自訂指令碼和整合項目。
設定驗證和授權：設定環境，驗證及授權 Chronicle API 要求。
對應端點並更新網址：將舊版端點替換為新版區域端點。
更新 API 邏輯：調整要求酬載和回應處理方式，以符合新版 API 的資料模型。
測試整合：先在測試環境中驗證變更，再部署至正式環境。

稽核 API 使用情形

稽核環境，找出叫用 backstory.googleapis.com 或 malachiteingestion-pa.googleapis.com 的自訂指令碼或整合服務。您可以查看程式碼集、自動化指令碼和第三方工具，找出這些整合項目。如果貴組織也使用 Google SecOps SOAR，請參閱「遷移 SOAR 整合項目」。

設定驗證與授權

設定環境，驗證及授權 Chronicle API 要求：

選擇驗證方式：選擇工作負載向 Chronicle API 驗證身分的方式，可用的方法列於下方。建議使用 Workload Identity Federation，避免管理及儲存長期服務帳戶金鑰，提高安全性。如需進階驗證情境 (例如服務帳戶模擬)，請參閱「向 Chronicle API 進行驗證」。
- Workload Identity Federation (建議)：設定 Workload Identity Federation，允許在 Google Cloud 外部執行的工作負載使用外部身分進行驗證。
- 服務帳戶：如需使用服務帳戶，請在 Google Cloud 專案中建立服務帳戶，然後產生並下載 JSON 格式的私密金鑰。請妥善保管這組金鑰。
授予 IAM 權限：將必要的 IAM 權限授予用於驗證的身分 (服務帳戶或外部身分主體)。請參閱「SIEM API 端點對應」，瞭解新版端點取代舊版呼叫所需的特定 IAM 權限。
- 自訂角色 (建議)： 建立具備必要權限的自訂 IAM 角色，並將自訂角色授予服務帳戶或外部身分主體。
- 預先定義的角色：將 Google SecOps 預先定義的角色授予服務帳戶或外部身分主體。這可能會授予超出特定自動化作業所需的存取權。
- 多租戶合作夥伴委派：如果您是 MSSP 或合作夥伴，負責管理 TenantService 以外的租戶資源 (例如 GetInstance、UpdateInstance 或 GenerateForwarderFiles)，租戶管理員必須明確授予您的服務帳戶或 Workload Identity Federation 主體，租戶 Google Cloud 專案中的必要 IAM 角色。
設定憑證環境變數：設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數，讓執行階段環境使用應用程式預設憑證 (ADC) 的憑證。這個變數應指向下載的服務帳戶金鑰 JSON 檔案，或 Workload Identity Federation 憑證設定檔。Google Cloud 用戶端程式庫會自動偵測這個變數，驗證要求：
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
更新 OAuth 範圍：如果舊版整合指令碼明確要求 OAuth 範圍來產生權杖，請更新範圍字串。舊版範圍不會授予新版 API 介面的存取權：
- 舊版 Backstory 範圍： https://www.googleapis.com/auth/chronicle-backstory
- Chronicle 範圍： https://www.googleapis.com/auth/chronicle (或更廣泛的 https://www.googleapis.com/auth/cloud-platform 範圍)。

對應端點並更新網址

熟悉 Chronicle API 介面、對應舊版呼叫，並更新應用程式中的服務端點。

查看參考文件

熟悉 Chronicle API 的完整說明文件。

將端點對應至 Chronicle API

找出應用程式發出的每個舊版 API 呼叫對應的新版端點。同樣地，請將現有資料模型對應至現代化結構，並考量任何結構定義變更或額外欄位。如要瞭解所有 SIEM 端點的詳細資料，請參閱「SIEM API 端點對應」。如果工作流程也會與 SOAR 端點互動，請參閱 SOAR API 端點對應表。

更新服務端點

更新 API 呼叫的基準網址，指向正確的區域性服務端點。Chronicle API 是區域性服務，因此您必須呼叫與 Google SecOps 執行個體位置相符的區域性服務端點。

所有現代端點都使用一致的前置字串，因此最終端點位址可預測。以下範例顯示新版端點網址結構：

[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

這個結構會產生端點的最終位址，如下所示：

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

其中：

service_endpoint：區域服務位址。
api_version：要查詢的 API 版本。可以是 v1alpha、v1beta 或 v1。
project_id：專案 ID (與您定義 IAM 權限的專案相同)。
location：專案的位置 (區域)，與區域端點相同。
instance_id：您的 Google SecOps SIEM 客戶 ID。

區域位址：

africa-south1：https://africa-south1-chronicle.googleapis.com或https://chronicle.africa-south1.rep.googleapis.com
asia-northeast1：https://asia-northeast1-chronicle.googleapis.com或https://chronicle.asia-northeast1.rep.googleapis.com
asia-south1：https://asia-south1-chronicle.googleapis.com 或 https://chronicle.asia-south1.rep.googleapis.com
asia-southeast1：https://asia-southeast1-chronicle.googleapis.com 或 https://chronicle.asia-southeast1.rep.googleapis.com
asia-southeast2：https://asia-southeast2-chronicle.googleapis.com或https://chronicle.asia-southeast2.rep.googleapis.com
australia-southeast1：https://australia-southeast1-chronicle.googleapis.com 或 https://chronicle.australia-southeast1.rep.googleapis.com
europe-west12：https://europe-west12-chronicle.googleapis.com或https://chronicle.europe-west12.rep.googleapis.com
europe-west2：https://europe-west2-chronicle.googleapis.com 或 https://chronicle.europe-west2.rep.googleapis.com
europe-west3：https://europe-west3-chronicle.googleapis.com 或 https://chronicle.europe-west3.rep.googleapis.com
europe-west6：https://europe-west6-chronicle.googleapis.com 或 https://chronicle.europe-west6.rep.googleapis.com
europe-west9：https://europe-west9-chronicle.googleapis.com 或 https://chronicle.europe-west9.rep.googleapis.com
me-central1：https://me-central1-chronicle.googleapis.com 或 https://chronicle.me-central1.rep.googleapis.com
me-central2：https://me-central2-chronicle.googleapis.com或https://chronicle.me-central2.rep.googleapis.com
me-west1：https://me-west1-chronicle.googleapis.com 或 https://chronicle.me-west1.rep.googleapis.com
northamerica-northeast2：https://northamerica-northeast2-chronicle.googleapis.com或https://chronicle.northamerica-northeast2.rep.googleapis.com
southamerica-east1：https://southamerica-east1-chronicle.googleapis.com或https://chronicle.southamerica-east1.rep.googleapis.com
美國 (us)：https://us-chronicle.googleapis.com 或 https://chronicle.us.rep.googleapis.com
歐洲 (eu)：https://eu-chronicle.googleapis.com 或 https://chronicle.eu.rep.googleapis.com

如需所有支援端點的完整清單，請參閱 Chronicle API 服務端點說明文件中的官方參考資料。

舉例來說，如要列出 us 位置中某個執行個體的所有偵測規則，請傳送下列要求：

GET
  https://us-chronicle.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/rules

同樣地，如要使用區域端點 (rep) 別名查詢 SOAR 資源 (例如案件)，請傳送下列要求：

GET
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

驗證防火牆設定

如果您在環境和網際網路之間使用防火牆或經過驗證的 Proxy，請設定規則，允許 TCP 通訊埠 443 上的 HTTPS 傳出連線。允許存取下列主機：

Chronicle API 端點：<var>REGION</var>-chronicle.googleapis.com 或 chronicle.<var>REGION</var>.rep.googleapis.com
Google 驗證端點：oauth2.googleapis.com、www.googleapis.com 和 accounts.google.com (如果使用 Workload Identity Federation 或服務帳戶模擬，則加上 sts.googleapis.com 和 iamcredentials.googleapis.com)

如需完整的端點詳細資料、Google IP 範圍指南、私人連線選項和驗證步驟，請參閱「驗證 Chronicle API 的防火牆設定」。

更新 API 邏輯

請參閱 Chronicle API REST 參考資料，找出並實作應用程式中欄位名稱和資料結構的變更。雖然部分舊版端點可能維持不變，但您必須更新整合功能，以符合最新的資料模型和端點結構。

使用 Google Cloud 用戶端程式庫

簡化整合程序，自動處理驗證、權杖重新整理和傳輸詳細資料。建議您使用官方 Google Cloud 用戶端程式庫執行這項操作。Chronicle API 支援八種程式設計語言，包括 Python、Go、Java、Node.js 和 C#。如要瞭解安裝和使用詳情，請參閱「用戶端程式庫和 SDK」。

測試整合項目

在測試環境中測試更新後的應用程式，再部署至正式環境：

制定測試計畫：定義測試案例，涵蓋所有遷移的功能。
執行測試：執行自動化和手動測試，確認準確性和有效性。
監控成效：使用新版 API 評估應用程式成效。

疑難排解

本節說明如何解決遷移期間可能遇到的常見錯誤。

HTTP 403 Forbidden 或 PERMISSION_DENIED

如果 API 呼叫傳回 HTTP 403 Forbidden 或 PERMISSION_DENIED 錯誤，請確認下列事項：

驗證方式和主體：請確認您使用的是正確憑證。
- 如果使用 Workload Identity Federation，請確認外部身分主體與專案中繫結至 IAM 角色的主體相符。
- 如果使用服務帳戶，請確認使用的是正確的服務帳戶，且該帳戶未停用。請勿將舊版服務帳戶 (電子郵件地址通常包含 bk 或 malachite-cx) 用於新版 Chronicle API 端點。
IAM 角色：確認服務帳戶或外部身分主體，已在 Google Cloud 專案中取得必要的預先定義或自訂 IAM 角色 (例如 Chronicle API Viewer 或 Chronicle API Editor)。如要瞭解精細的端點權限，請參閱「SIEM API 端點對應」。

HTTP 401 未授權或未經驗證

如果 API 呼叫失敗，並顯示 HTTP 401 Unauthorized 或 UNAUTHENTICATED，請檢查下列事項：

OAuth 範圍：確認自訂指令碼要求的是新版範圍：https://www.googleapis.com/auth/chronicle (或更廣泛的 https://www.googleapis.com/auth/cloud-platform 範圍)。舊版範圍 (https://www.googleapis.com/auth/chronicle-backstory) 不會授予新版 Chronicle API 的存取權。
環境變數：確認 GOOGLE_APPLICATION_CREDENTIALS 環境變數已設定，並指向執行階段環境中正確的 JSON 金鑰檔案或 Workload Identity Federation 設定檔。

HTTP 404 找不到網頁或區域不符

如果 API 呼叫傳回 HTTP 404 Not Found 或無法連線，請檢查區域端點：

區域端點：Chronicle API 是區域性服務。確認您呼叫的端點與 Google SecOps 執行個體所在區域相符 (例如，法蘭克福執行個體的端點為 https://europe-west3-chronicle.googleapis.com)。如果將要求傳送至其他區域，就會發生錯誤。如需區域位址的完整清單，請參閱「更新服務端點」或官方服務端點參考資料。

後續步驟

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