我們重新調整了說明文件的導覽結構，直接對應您的作業工作流程。詳情請參閱版本資訊和逐步解說影片。

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 的許多限制和複雜性。

有何異動

所有對舊版 Backstory API 和 Ingestion API 端點的程式輔助要求，都必須改用新版 Chronicle API。如果貴機構使用自訂整合、自動化指令碼或第三方工具呼叫這些舊版端點，請務必在 2027 年 7 月 20 日前，更新這些工作負載，改用新版端點和驗證流程。

維持不變的部分

直接在 Google SecOps 使用者介面 (UI) 中執行的動作，會叫用新版 Chronicle API。如果貴機構只透過使用者介面與 Google SecOps 互動，或整合項目已呼叫 Chronicle API 端點，則不必採取任何行動。

主要異動和強化措施

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

特色區域	舊版 SIEM API	Chronicle API	詳細資料
憑證管理	需要 Google 代表介入的手動程序	自助管理服務帳戶、憑證和 IAM 權限	自助式憑證和 IAM 管理功能可簡化新手上路程序，並免除手動支援要求。
法規遵循標準	有限支援	內建支援資料落地控管機制、VPC Service Controls、資料存取透明化控管機制、CMEK 和 FedRAMP	內建的現代化基礎架構控管機制，符合業界法規遵循和監管標準。
記錄與稽核	舊版稽核串流	整合至 Google Cloud 專案的 Cloud 稽核記錄	直接整合可提供集中式稽核追蹤和監控功能。
驗證	API 權杖和服務帳戶憑證	OAuth 2.0，支援現代驗證方法，包括「API 和服務驗證 Google Cloud 」一文所述的 Workload Identity 和服務帳戶	這些新式驗證方法可提升安全性，並將憑證流程標準化。
資料模型和 API 設計	無格式專屬結構	資源導向設計、RESTful 架構，以及遵循 AIP 的標準化命名	這項現代化設計可提升資料一致性、讓 API 更直觀，並簡化物件操作。
端點命名	不一致	RESTful 且標準化	一致的命名方式可讓 API 更直覺，也更容易整合。
生態系統	非常有限	與 MCP、Terraform、用戶端程式庫和 SDK 整合	廣泛相容於現代雲端工具和自動化架構。

淘汰時間表

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

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

事前準備

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

部署在現代化 SIEM 基礎架構上：請務必在 Google Cloud 專案中部署執行個體，並運用現代化 SIEM 基礎架構。如需詳細操作說明，請參閱 SIEM 遷移總覽。
啟用 Chronicle API：在 Google Cloud 控制台中，前往您的專案並啟用 Chronicle API (chronicle.googleapis.com)。詳情請參閱「在專案中啟用 API Google Cloud 」。

遷移至 Chronicle API

如要將指令碼和整合項目從舊版 API 遷移至 Chronicle API，請完成下列步驟：

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

稽核 API 使用情形

稽核環境，找出會叫用 backstory.googleapis.com 或 malachiteingestion-pa.googleapis.com 的指令碼或整合項目。您可以查看程式碼集、自動化指令碼和第三方工具，找出這些整合項目。

設定驗證與授權

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

選擇驗證方法：從列出的方法中選擇一種，讓工作負載向 Chronicle API 進行驗證。建議使用 Workload Identity Federation，因為這樣就不必管理及儲存長期有效的服務帳戶金鑰，安全性更高。如需進階驗證情境 (例如服務帳戶模擬)，請參閱「通過 Chronicle API 驗證」。
- Workload Identity Federation (建議)：設定 Workload Identity Federation，允許在 Google Cloud 外部執行的工作負載使用外部身分驗證。
- 服務帳戶：如必須使用服務帳戶，請在 Google Cloud 專案中建立服務帳戶，並以 JSON 格式產生及下載私密金鑰。請妥善保管這組金鑰。
授予 IAM 權限：將必要的 IAM 權限授予用於驗證的身分 (服務帳戶或外部身分主體)。根據所需的存取層級，將必要的 IAM 角色指派給您的身分。詳情請參閱「管理專案、資料夾和機構的存取權」。預先定義的角色包括：
建議您使用最低權限原則，並運用自訂或預先定義的 IAM 角色，僅授予自動化作業所需的權限。

注意： 請參閱「SIEM API 端點對應」，瞭解取代舊版呼叫的現代端點需要哪些精細 IAM 權限。
設定憑證環境變數：設定執行階段環境，透過設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數，使用應用程式預設憑證 (ADC) 取得憑證。這個變數應指向下載的服務帳戶金鑰 JSON 檔案，或是 Workload Identity 聯盟憑證設定檔。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 Security Operations 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

更新 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 Unauthorized 或 UNAUTHENTICATED

如果 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 專業人員尋求解答。