我们已重新整理文档导航结构，使其与您的运营工作流程直接保持一致。如需了解详情，请参阅版本说明和演示视频。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

从旧版 SIEM API 迁移到 Chronicle API

支持的服务：

Google SecOps SIEM

本文档可帮助您管理调用任何旧版 SIEM API（Backstory API 和 Ingestion API）的应用。它介绍了您必须按照哪些步骤设置编程访问权限，以及如何将所有对旧版 SIEM API 端点的引用更新为对现代 Chronicle API 端点的引用。

如需快速了解迁移过程，请观看嵌入式视频。

Chronicle API 界面引入了多项改进，旨在简化您的开发流程并符合 Google Cloud API 标准，从而提高可靠性、安全性和性能，并加强与 Cloud Audit Logs、Cloud Monitoring、Cloud Identity 和 Identity and Access Management (IAM) 的集成。它还解决了旧版 API 的许多限制和复杂性问题。

变更内容

对旧版 Backstory API 和 Ingestion API 端点的所有编程请求都必须迁移到现代 Chronicle API。如果您的组织使用自定义集成、自动化脚本或第三方工具来调用这些旧版端点，则必须在 2027 年 7 月 20 日之前更新这些工作负载，以使用现代端点和身份验证流程。

未变更的内容

直接在 Google SecOps 界面中执行的操作已调用现代 Chronicle API。如果您的组织仅通过界面与 Google SecOps 互动，或者您的集成已调用 Chronicle API 端点，则无需采取任何行动。

主要变化和增强功能

下表重点介绍了旧版 SIEM API 与 Chronicle API 之间的主要区别：

功能区域	旧版 SIEM API	Chronicle API	详细信息
凭据管理	涉及 Google 代表的手动流程	自行管理服务账号、凭据和 IAM 权限	自行管理凭据和 IAM 权限可简化 onboarding 流程，并消除对人工支持请求的依赖。
合规性标准	有限支持	内置支持数据驻留控制、VPC Service Controls、Access Transparency、CMEK 和 FedRAMP	现代内置基础架构控制措施符合行业合规性和监管标准。
日志记录和审核	旧版审核流	集成到 Google Cloud 项目中的 Cloud Audit Logs	直接集成提供集中式审核跟踪和监控。
身份验证	API 令牌和服务帐号凭据	OAuth 2.0，支持现代身份验证方法，包括 Workload Identity 和服务账号（如 API 和服务的 Google Cloud 身份验证中所述）	这些现代身份验证方法可提供更高的安全性并标准化凭据流程。
数据模型和 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 基础架构上：确保实例部署在您或您的 MSSP 合作伙伴的 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 进行身份验证的方式。我们建议使用工作负载身份联合，以提高安全性，因为它避免了管理和存储长期存在的服务帐号密钥。如需了解高级身份验证场景（例如服务帐号模拟），请参阅向 Chronicle API 进行身份验证。
- 工作负载身份联合（推荐）：设置工作负载身份联合，以允许在外部 Google Cloud 运行的工作负载使用外部身份进行身份验证。
- 服务账号：如果您必须使用服务账号，请在您的 Google Cloud 项目中创建一个服务账号，并生成和下载 JSON 格式的私钥。妥善保管此密钥。
授予 IAM 权限：向用于身份验证的身份（服务帐号或外部身份主账号）授予所需的 IAM 权限。请参阅 SIEM API 端点映射，查找替换旧版调用的现代端点所需的特定 IAM 权限。
- 自定义角色（推荐）：创建自定义 IAM 角色，并授予该自定义角色所需的权限，以授予服务帐号或外部身份主账号。
- 预定义角色：向服务帐号或外部身份主账号授予Google SecOps 预定义角色。这可能会授予比特定自动化所需的更多访问权限。
设置凭据环境变量：通过设置 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 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 资源（例如 Case），请发送以下请求：

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 错误，请验证以下内容：

身份验证方法和主账号：确保您使用的是正确凭据。
- 如果使用工作负载身份联合，请验证外部身份正文是否与项目中绑定到 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 密钥文件或工作负载身份联合配置文件。

HTTP 404 Not Found 或区域不匹配

如果 API 调用返回 HTTP 404 Not Found 或无法连接，请检查区域端点：

区域端点： Chronicle API 是一项区域服务。验证您调用的端点是否与 Google SecOps 实例的区域匹配（例如，法兰克福实例的端点为 https://europe-west3-chronicle.googleapis.com）。向其他区域发送请求会导致错误。如需查看区域地址的完整列表，请参阅更新服务端点或官方服务端点参考。