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

遷移至 Chronicle API

支援的服務：

Google SecOps SOAR

本文將說明相關步驟和注意事項，協助您更新程式輔助 API 參考資料，指向 Chronicle API 的 SOAR API 端點。

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

舊版 SOAR API 和 API 金鑰會開放使用至 2027 年 3 月 31 日，之後就會停止運作。

現成的回應整合

如果您使用的整合版本過舊，會呼叫舊版 SOAR API，請在 2027 年 3 月 31 日前更新整合套件：

內容中心整合：在 Google Security Operations 中開啟「Content Hub」，並將所有過時的商業整合更新至最新版本。詳情請參閱「Content Hub 總覽」。
Splunk 外掛程式：如果您使用 Chronicle SOAR Add-on for Splunk，請將 Splunk 中的 TA-Siemplify 升級至最新版本。升級後，請重新設定外掛程式，使用區域 Chronicle API 端點和 Google Cloud 服務帳戶憑證。

必要條件

將 SOAR API 呼叫遷移至 Chronicle API 前，請先完成遷移作業第 1 階段 (依序前往「SOAR 設定」>「授權管理」，系統版本旁會顯示「Google.com」)。您可以在啟用 Google Cloud SOAR 權限群組的身分與存取權管理 (IAM) 之前或之後，測試及遷移程式輔助 Chronicle API 呼叫。

主要異動和強化功能

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

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

淘汰時程

舊版 siemplify-soar.com API 介面和 AppKey 驗證機制會開放使用至 2027 年 3 月 31 日，之後就會停止運作。

2027 年 3 月 31 日前，舊版 SOAR API 仍會與 Chronicle API 並行運作，即使啟用 Google Cloud IAM 也不受影響。因此，您可以按照自己的步調逐步遷移及驗證各個元件，不會中斷進行中的工作流程。

舊版 SOAR API 的效率不如 Chronicle API，因此建議您盡快改用 Chronicle API 替代方案，並在 2027 年 3 月 31 日前完成，以免服務中斷。

遷移步驟

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

詳閱說明文件

熟悉新 API 的完整說明文件，包括 Chronicle API 參考指南。

將端點對應至新的 API 介面

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

選用：建立測試整合

如要編輯自訂整合或自訂動作，Google 建議您先將變更推送至測試整合。這樣一來，您就能在不影響正式版自動化流程的情況下進行測試。如果您要遷移使用 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 版本。請盡可能使用 v1，如果 v1 尚不支援，請改用 v1beta 或 v1alpha (請參閱 SOAR API 對應表，瞭解各端點支援的版本)。
project_id：專案 ID (與您為 IAM 權限定義的專案相同)
location：專案的位置 (區域)，與區域端點相同
instance_id：Google Security Operations SIEM 客戶 ID。

區域性位址：

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

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

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

更新驗證方式

Chronicle 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 錯誤。

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

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

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

設定下列存取控管欄位：

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

按一下「新增」。

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

更新 API 邏輯

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

將自訂 API 呼叫遷移至 Chronicle API

Google SecOps 中的自訂 Python 程式碼不一定需要變更：

內建 SDK 方法不需變更程式碼：自訂整合、Playbook 動作、連接器和工作中的自訂 Python 程式碼，如果使用標準內建 SDK 方法 (例如 siemplify.add_comment()、siemplify.get_case_comments() 或 siemplify.update_alerts_additional_data())，則不需修改程式碼。Google SecOps 會自動透過統一的 API 介面，轉送內建的 Siemplify SDK 方法。
只有手動 HTTP 要求需要更新：只有使用 SDK 屬性手動建構 HTTP 要求，並傳送至舊版 SOAR API 的自訂 Python 指令碼需要更新，例如使用 siemplify.API_ROOT 建構網址，並使用 requests 或 siemplify.session 透過 siemplify.api_key 進行驗證。如要找出受影響的自訂元件，請在Logs Explorer中執行 resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" (檢查 labels.integration_name、labels.action_name、labels.connector_name、labels.job_name 和 labels.playbook_name)，或查看舊版 API 使用情形摘要報告中的 CustomCode 清單。

測試整合項目

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

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

配額與頻率限制

Chronicle API 會強制執行 Google Cloud 專案層級配額，以維持服務可用性並防止流量失控：

預設配額：Chronicle API 會在 Google Cloud 專案層級強制執行每分鐘要求數 (RPM) 限制，通常是每個專案 6,000 RPM，並設有區域 API 子限制。
頻率限制錯誤 (HTTP 429)：如果整合服務或外部指令碼超出專案配額，Chronicle API 會傳回 HTTP 429 (RESOURCE_EXHAUSTED 或 TooManyRequestsException)。

如要查看目前的 Chronicle API 配額用量，或申請提高配額，請按照下列步驟操作：

在 Google Cloud 控制台，依序前往「IAM & Admin」(IAM 與管理) >「Quotas & System Limits」(配額與系統限制)：

前往「Quotas & System Limits」(配額與系統限制)
按一下「篩選器」，選取「服務」，然後輸入 chronicle.googleapis.com，即可查看目前用量和限制。詳情請參閱「在 Google Cloud 控制台中查看配額」。
如果正式版攝入、自動化或票證整合功能需要更高的限制，請勾選相關配額旁的核取方塊，然後按一下「編輯」(或「編輯配額」) 申請提高配額。如需詳細步驟，請參閱「要求調整配額」。您也可以透過 Cloud Customer Care 或 Google SecOps 代表，提交提高配額的要求。

稽核其餘舊版 API 的使用情形

您可以使用 Logging、產品內系統通知或舊版 API 使用情形摘要端點，找出剩餘的舊版 SOAR API 呼叫。

查詢記錄

舊版 API 淘汰警告 (labels.auth_deprecation="true") 會以 WARNING 嚴重程度的 SOAR 作業記錄形式，在 resource.labels.namespace_name="chronicle-soar" 下發出 (請參閱「收集 SOAR 平台記錄檔」)，而非在 Cloud 稽核記錄中發出。只有客戶可採取行動的警告 (labels.actionable_by="Customer") 會匯出至 Google Cloud 專案，Google 內部 UI 和系統呼叫會自動篩除。

在Logs Explorer中執行下列查詢：

遠端代理歸因 (labels.is_remote="true")：表示來自遠端代理上執行程式碼的舊版通話。請先將遠端代理程式升級至 2.6.2 以上版本，並遷移至服務帳戶驗證 (請參閱「遷移遠端代理程式驗證基礎架構」)。遠端代理程式升級並設定 Google Cloud 服務帳戶後，代理程式本身的控制層輪詢會使用 OAuth 2.0；遠端代理程式 SDK 呼叫的完整元件標籤歸因功能，正在正式環境中分階段推出。如果遷移代理後仍有項目，請檢查該代理上是否有過時的整合或自訂程式碼。
30 天零記錄完成檢查 (所有客戶可操作的舊版通話)：
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
```
如果這項查詢連續 30 天傳回 0 筆記錄，表示 API 遷移作業已完成。
直接呼叫舊版 API (AppKey) 的外部指令碼和第三方工具：
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="false"
```
發出的欄位包括 labels.app_key (舊版 API 金鑰 ID)、labels.via_xlb (外部輸入的 "true")，以及 textPayload (Deprecated direct AppKey authentication detected (Route: ROUTE).) 中呼叫的 HTTP 路由。
過時的 Content Hub 整合：如要檢查已安裝的商業整合是否仍呼叫舊版 SOAR API，請執行下列查詢，列出相符的淘汰項目 (請參閱現成可用的回應整合)：
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="true"
labels.is_custom="false"
```
圖 1. Logs Explorer 查詢結果，列出過時商業整合的淘汰項目。

展開相符的記錄項目，查看 labels.integration_name、labels.integration_version、labels.latest_integration_version 和觸發元件 (labels.action_name、labels.connector_name、labels.job_name 或 labels.playbook_name)：

圖 2. 展開的淘汰記錄項目，顯示已安裝和最新的商業整合版本。

您也可以查看舊版 API 使用情形摘要報告中的 OutdatedIntegrations 清單。
手動發出 HTTP 呼叫的自訂 Python 程式碼：執行 resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" (請參閱「將自訂 API 呼叫遷移至 Chronicle API」)。

查看產品內系統通知

Google SecOps 執行個體推出這項功能後，系統通知會顯示過去 24 小時內，客戶可採取行動的舊版 API 呼叫摘要，涵蓋過時的 Content Hub 整合、自訂 IDE 元件和外部 API 金鑰，類似於以下範例：

Non-1P API usage summary (last 24h): 2294 legacy API call(s) require action.
Content Hub - Update 1 outdated integration(s): GoogleChronicle (v94->v98).
IDE - Refactor 15 custom component(s): Action 'CustomAction' (LegacyAuthCases),
Connector 'CustomConnector' (LegacyAuthCases), Job 'CustomJob'
(LegacyAuthCases) (+12 more).
Settings > API Keys - Migrate 1 external key(s) to 1P auth:
'example_external_automation_key'.

查詢舊版 API 用量摘要端點

您也可以直接查詢 GET /api/external/v1/logging/non-1p-api-usage，擷取近期舊版 API 呼叫的匯總 JSON 報表：

依序前往「SOAR 設定」>「進階」>「API 金鑰」，建立或選取指派給權限群組的舊版 API 金鑰，該群組須包含「設定」權限。如需操作說明，請參閱「向舊版 SOAR API 進行驗證」。

使用 AppKey 標頭傳送 GET 要求 (將 hoursBack 設為 1 至 168 之間，預設值為 24)：

curl -H "AppKey: API_KEY" \
  "https://INSTANCE.siemplify-soar.com/api/external/v1/logging/non-1p-api-usage?hoursBack=24"

回應會將客戶可採取行動的淘汰警告分為以下幾節：

OutdatedIntegrations：列出 InstalledVersion 早於 LatestVersion 的商業 Content Hub 整合，包括 IntegrationName、InstalledVersion、LatestVersion、ActionNeeded、InvocationCount、FirstUsedTimestamp、LastUsedTimestamp 和受影響的元件 (AffectedActions、AffectedConnectors、AffectedJobs、AffectedPlaybooks)，類似於以下範例：

{
  "OutdatedIntegrations": [
    {
      "IntegrationName": "GoogleChronicle",
      "InstalledVersion": "94",
      "LatestVersion": "98",
      "ActionNeeded": "Upgrade integration to v98 in Content Hub",
      "AffectedActions": ["Ping"],
      "AffectedConnectors": ["Google Chronicle - Chronicle Alerts Connector"],
      "InvocationCount": 202,
      "FirstUsedTimestamp": "2026-10-14T19:16:31Z",
      "LastUsedTimestamp": "2026-10-14T19:44:54Z"
    }
  ]
}

CustomCode：列出自訂 SDK 元件 (ComponentType：Action、Connector、Job、Playbook 或 Custom Script)，這些元件會手動進行舊版 API 呼叫，包括 ComponentName、IntegrationName、AffectedPlaybooks、RoutesUsed、InvocationCount、FirstUsedTimestamp 和 LastUsedTimestamp。

DirectAppKeys：列出 SDK 外部的直接外部 AppKey 呼叫，包括 AppKey、ActionNeeded、RoutesUsed、InvocationCount、FirstUsedTimestamp 和 LastUsedTimestamp，類似以下範例：

{
  "DirectAppKeys": [
    {
      "AppKey": "example_external_automation_key",
      "ActionNeeded": "Migrate external script or automation to use Google Cloud service account or OAuth authentication",
      "RoutesUsed": [
        "GET /api/external/v1/cases/GetCaseFullDetails/14",
        "GET /api/external/v1/dynamic-cases/GetCaseDetails/14",
        "GET /api/external/v1/ide/GetIdeItemCards",
        "GET /api/external/v1/jobs/GetInstalledJobs",
        "GET /api/external/v1/jobs/GetJobHistoryLogs/jobIdStr",
        "GET /api/external/v1/logging/non-1p-api-usage",
        "GET /api/external/v1/playbooks/GetWorkflowFullInfoWithEnvFilterByIdentifier/00000000-0000-0000-0000-000000000000",
        "POST /api/external/v1/ide/GetIdeItem",
        "POST /api/external/v1/ide/TestItem",
        "POST /api/external/v1/integrations/GetOptionalIntegrationInstances",
        "POST /api/external/v1/jobs/RunJob",
        "POST /api/external/v1/playbooks/AttacheWorkflowToCase",
        "POST /api/external/v1/playbooks/GetWorkflowMenuCardsWithEnvFilter",
        "POST /api/external/v1/playbooks/RerunPlaybook"
      ],
      "InvocationCount": 1084,
      "FirstUsedTimestamp": "2026-10-14T19:30:15.169684Z",
      "LastUsedTimestamp": "2026-10-14T20:24:13.552893800Z"
    }
  ]
}

TopOffenders (TopAppKeys 和 TopRoutes)：匯總最常用的舊版 AppKey 身分和 HTTP 路由 (HTTP 方法和路由)，協助您排定遷移工作的優先順序。

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