遷移至 Chronicle API

支援的服務：

Google SecOps SOAR

如果您使用整合服務、自訂指令碼或自訂動作，以程式輔助方式呼叫 SOAR API，請參閱這份文件。本文將逐步說明如何將程式輔助 API 參照更新為 Chronicle API 的新 SOAR API 端點，並列出相關注意事項。

Chronicle API 介面推出多項改善措施，旨在簡化開發流程。同時解決舊版 API 的限制和複雜問題。

舊版 SOAR API 和 API 金鑰將於 2027 年 3 月 31 日停用。

必要條件

遷移 SOAR API 前，請先完成下列事項：

• 完成遷移作業第 1 階段。

主要異動和強化功能

下表列出新舊 API 介面的主要差異：

功能區域	舊版 API	新 API	詳細資料
驗證	API 權杖	OAuth 2.0	新的驗證方式可提升安全性，並標準化程序。
資料模型	扁平結構	以資源為導向的設計	這項新設計可提升資料一致性，並簡化物件操作。
端點命名	不一致	RESTful 和標準化	一致的命名方式可讓 API 更直覺，也更容易整合。

淘汰時程

SOAR 的舊版 API 介面預計於 2027 年 3 月 31 日全面淘汰。建議您在上述日期前完成遷移，以免服務中斷。

遷移步驟

本節將概述如何成功將應用程式遷移至 Chronicle API：

詳閱說明文件

請詳閱新版 API 的完整說明文件，包括 Chronicle API 參考指南。

將端點對應至新的 API 介面

找出應用程式發出的每個舊 API 呼叫對應的新端點。同樣地，請將舊資料模型對應至新模型，並考量任何結構變更或新欄位。詳情請參閱 API 端點對應表。

選用：建立測試整合

如果您要編輯自訂整合項目或商業整合項目的元件，建議先將變更推送至測試整合項目。這樣一來，您就能在不影響正式版自動化流程的情況下進行測試。如果您要遷移使用 SOAR API 的自訂應用程式，可以跳到下一個步驟。如要進一步瞭解整合測試模式，請參閱「在測試模式中測試整合」。

更新服務端點和網址

服務端點是指定 API 服務網路位址的基準網址。一項服務可以有多個服務端點。Chronicle 是區域性服務，僅支援區域端點。

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

[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 Security Operations SIEM 客戶 ID。

區域性位址：

• africa-south1：https://chronicle.africa-south1.rep.googleapis.com

• asia-northeast1：https://chronicle.asia-northeast1.rep.googleapis.com

• asia-south1：https://chronicle.asia-south1.rep.googleapis.com

• asia-southeast1：https://chronicle.asia-southeast1.rep.googleapis.com

• asia-southeast2：https://chronicle.asia-southeast2.rep.googleapis.com

• australia-southeast1：https://chronicle.australia-southeast1.rep.googleapis.com

• europe-west12：https://chronicle.europe-west12.rep.googleapis.com

• europe-west2：https://chronicle.europe-west2.rep.googleapis.com

• europe-west3：https://chronicle.europe-west3.rep.googleapis.com

• europe-west6：https://chronicle.europe-west6.rep.googleapis.com

• europe-west9：https://chronicle.europe-west9.rep.googleapis.com

• me-central1：https://chronicle.me-central1.rep.googleapis.com

• me-central2：https://chronicle.me-central2.rep.googleapis.com

• me-west1：https://chronicle.me-west1.rep.googleapis.com

• northamerica-northeast2：https://chronicle.northamerica-northeast2.rep.googleapis.com

• southamerica-east1：https://chronicle.southamerica-east1.rep.googleapis.com

• us：https://chronicle.us.rep.googleapis.com

• eu：https://chronicle.eu.rep.googleapis.com

舉例來說，如要取得美國某項專案的所有案件清單，請執行下列指令：

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

更新驗證方式

新 API 使用 Google Cloud IAM 進行驗證。您需要更新應用程式或回應整合，才能導入這項新的驗證流程。請確認執行指令碼的使用者具備正確權限，可存取要使用的端點。如要導入這項新流程，您必須更新回應整合服務或應用程式。請確認執行指令碼的使用者具備目標端點的必要權限。如需詳細操作說明，請參閱「向 Chronicle API 進行驗證」頁面。

將服務帳戶或工作負載身分對應至 SOAR 參數

如果您使用服務帳戶或 Workload Identity Federation 向 Chronicle API 進行驗證，則必須在平台中授權，確保能與 Google SecOps 順利通訊。必須完成這項對應，服務帳戶或工作負載身分才能取得 SOC 角色和環境的必要存取權。

如要將服務帳戶存取權或 Workload Identity Federation 存取權授予 Google SecOps，您必須將身分對應至平台的存取控管參數。這項對應作業是必要步驟，可為身分提供必要的 SOC 角色和環境存取權，以便執行自動化工作或 API 作業。

注意：將 Google Cloud IAM 角色授予服務帳戶或主體是必要步驟，但光是這樣還不足以存取 Google SecOps SOAR API。如果服務帳戶未明確對應至群組對應，即使已設定所有必要的專案層級 IAM 角色，API 要求仍會失敗，並顯示 401 UNAUTHENTICATED 錯誤。

1. 依序前往「設定」>「存取管理」>「群組對應」。
2. 按一下「新增」圖示 。

3. 在「Add Mapping」(新增對應) 對話方塊中填寫欄位，將身分對應至平台的存取控管參數。

   1. 在「IdP / User group」(IdP/使用者群組) 欄位中，輸入下列其中一項：
      • 服務帳戶的完整電子郵件地址 (如果身分是使用 Cloud Identity 設定)。
      • Workload Identity 主體字串 (如果身分是透過員工身分聯盟設定)。

   2. 設定下列存取控管欄位：

      欄位	說明
      權限群組	選取權限群組，定義身分可存取的模組和子模組。
      資安營運中心 (SOC) 角色	選取 SOC 角色，定義身分的角色 (例如第 1 級)。
      環境	選取身分可存取的環境或環境群組 (例如「All Environments」)。
      群組成員	視需要輸入必要的使用者電子郵件地址。每新增一個電子郵件地址，就按下 Enter 鍵。
      受限制的動作	選取受限動作，限制模組內的特定操作。

4. 按一下「新增」。

如要進一步瞭解如何對應使用者和服務帳戶，請參閱「在平台使用第三方身分對應使用者」或「在平台使用 Cloud Identity 對應使用者」。

更新 API 邏輯

分析 API 參考資料中提供的新資料模型和端點結構。並非所有方法都有重大變更，部分現有程式碼可以重複使用。主要目標是查看新的參考文件，並針對每個特定用途，找出並實作應用程式邏輯中欄位名稱和資料結構的必要變更。

測試整合項目

在部署至正式環境前，請先在測試整合環境中測試更新後的應用程式：

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

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