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

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 界面 (UI) 中执行的操作已调用现代 Chronicle API。如果贵组织仅通过界面与 Google SecOps 互动，或者您的集成已调用 Chronicle API 端点，则您无需采取任何行动。

主要变化和增强功能

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

功能区域	旧版 SIEM API	Chronicle API	详细信息
凭据管理	涉及 Google 代表的手动流程	自行管理服务账号、凭据和 IAM 权限	自助式凭据和 IAM 管理可简化初始配置流程，并避免依赖人工支持请求。
合规性标准	有限支持	内置支持数据驻留控制、VPC Service Controls、Access Transparency、CMEK 和 FedRAMP	现代化的内置基础架构控制措施可满足行业合规性和监管标准。
日志记录和审核	旧版审核信息流	集成到 Google Cloud 项目中的 Cloud Audit Logs	直接集成可提供集中式审核跟踪记录和监控。
身份验证	API 令牌和服务账号凭据	OAuth 2.0，支持现代身份验证方法，包括 Workload Identity 和服务账号（如 Google Cloud API 和服务的身份验证中所述）	这些现代身份验证方法可增强安全性并使凭据流程标准化。
数据模型和 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 基础设施上：确保您的实例部署在利用现代 SIEM 基础设施的 Google Cloud 项目中。如需详细说明，请参阅 SIEM 迁移概览。
启用 Chronicle API：在 Google Cloud 控制台中，前往您的项目并启用 Chronicle API (chronicle.googleapis.com)。如需了解详情，请参阅在 Google Cloud 项目中启用 API。

迁移到 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 权限。根据所需的访问权限级别，为您的身份分配所需的 IAM 角色。如需了解详情，请参阅管理对项目、文件夹和组织的访问权限。预定义角色包括：
我们建议您遵循最小权限原则，利用自定义或预定义的 IAM 角色，仅授予自动化流程所需的权限。

注意：请参阅 SIEM API 端点映射，了解取代旧版调用的新端点所需的具体精细 IAM 权限。
设置凭据环境变量：通过设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量，将运行时环境配置为使用具有应用默认凭据 (ADC) 的凭据。此变量应指向下载的服务账号密钥 JSON 文件或工作负载身份联合凭据配置文件。Google Cloud 客户端库会自动检测此变量以对请求进行身份验证：
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
更新 OAuth 范围：如果您的旧版集成脚本明确请求了用于生成令牌的 OAuth 范围，请更新范围字符串。旧版范围不授予对现代 API Surface 的访问权限：
- 旧版背景故事范围： 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 错误（未找到）或区域不匹配

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

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