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 Security Operations SOAR，您必须更新 SOAR 集成和连接器（例如 Google Chronicle 集成），以使用 Chronicle API。如需了解详情，请参阅迁移 SOAR 集成。

未变更内容

直接在 Google Security Operations 界面 (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	现代化的内置基础架构控制措施符合行业合规性和监管标准。
日志记录和审核	旧版审核流	Cloud Audit Logs 已集成到您的 Google Cloud 项目中	直接集成可提供集中式审核跟踪记录和监控。
身份验证	API 令牌和服务账号凭证	OAuth 2.0，支持现代身份验证方法，包括 Workload Identity 和服务账号，如 Google Cloud API 和服务的身份验证中所述	这些现代身份验证方法可提供更高的安全性，并使凭证流程标准化。
数据模型和 API 设计	扁平化专有结构	面向资源的设计、RESTful 架构以及遵循 AIP 的标准化命名	这种现代设计提高了数据一致性，使 API 更加直观，并简化了对象操作。
端点命名	不一致	RESTful 且标准化	一致的命名方式使 API 更直观、更易于集成。
生态系统	非常有限	与 MCP、Terraform、客户端库和 SDK 集成	与现代云工具和自动化框架广泛兼容。
合作伙伴授权	直接在客户代码中使用合作伙伴令牌或 API 密钥	针对租户资源的跨项目 IAM 委托；合作伙伴范围的 TenantService 方法	TenantService 方法在合作伙伴项目中运行。所有其他租户 API 都需要租户在租户项目中授予跨项目 IAM 委托。

合作伙伴授权

对于多租户合作伙伴工作流，Chronicle API 中的授权取决于资源所有权。托管资源的项目决定了合作伙伴需要哪些凭证和 IAM 权限。将租户操作范围限定为租户委托的凭据，符合核心安全原则，即合作伙伴在未获得租户明确许可的情况下，不得访问、检索或修改租户数据。下表比较了旧版 Backstory API 和 Chronicle API 中的合作伙伴授权：

API	方法	资源范围	授权
旧版 Backstory API	`/v1/partner/customer/*` 个端点	合作伙伴的所有客户代码	合作伙伴使用自己的合作伙伴令牌或 API 密钥直接调用这些端点。
Chronicle API：`TenantService`	`CreateTenant`、`ListTenants`和`UpdateTenant`	合作伙伴的实例：`projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/*`	合作伙伴使用其自己的服务账号或在合作伙伴项目中具有 `chronicle.googleapis.com/tenants.*` 权限的凭据直接调用这些方法。
Chronicle API：其他服务，例如 `InstanceService` 和 `ForwarderService`	`GetInstance`、`UpdateInstance`、`GenerateForwarderFiles` 和其他租户级方法	租户的实例：`projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/...`	仅凭合作伙伴凭证无法访问或修改租户数据。租户管理员必须在租户的 Google Cloud 项目中向合作伙伴的服务账号或工作负载身份联合主体授予 IAM 角色，例如 `roles/chronicle.admin`、`roles/chronicle.viewer`或自定义角色。

弃用时间表

旧版 SIEM API 计划于 2027 年 7 月 20 日关停。我们建议您在此日期之前完成迁移，以免服务中断：

自 2026 年 10 月 26 日起，您将无法再从新实例调用旧版 API（Backstory API 和 Ingestion API）。
您必须在 2027 年 7 月 20 日之前将所有现有实例迁移到 Chronicle API，因为届时旧版 API 将不再可用。

准备工作

在迁移到 Chronicle API 之前，请务必完成以下操作：

在现代 SIEM 基础设施上部署：确保使用现代 SIEM 基础设施在您或您的 MSSP 合作伙伴的 Google Cloud 项目中部署实例。如需详细说明，请参阅 SIEM 迁移概览。
启用 Chronicle API：在 Google Cloud 控制台中，前往托管实例的项目，然后启用 Chronicle API (chronicle.googleapis.com)。如需了解详情，请参阅在 Google Cloud 项目中启用 API。
确定 SOAR 集成：如果您的环境将 Google SecOps SOAR 连接到 Google Security Operations SIEM，请验证现有连接器。如需了解详情，请参阅迁移 SOAR 集成。

迁移 SOAR 集成

如果贵组织将 Google SecOps SOAR 连接到 Google SecOps SIEM，则必须迁移 SOAR 集成和连接器（例如 Google Chronicle 集成），以使用 Chronicle API。

如需详细了解如何升级 Google Chronicle 集成和连接器以使用 Chronicle API（包括查找环境的 Chronicle API 根目录和配置身份验证凭证），请参阅从 Backstory API 迁移到 Chronicle API。

迁移到 Chronicle API

完成以下步骤，将自定义脚本和集成从旧版 API 迁移到 Chronicle API：

审核 API 使用情况：确定环境中调用旧版端点的所有自定义脚本和集成。
设置身份验证和授权：配置您的环境，以便对向 Chronicle API 发出的请求进行身份验证和授权。
映射端点并更新网址：将旧版端点替换为对应的现代区域端点。
更新 API 逻辑：调整请求载荷和响应处理，以匹配现代 API 的数据模型。
测试集成：在部署到生产环境之前，先在预演环境中验证更改。

审核 API 使用情况

审核您的环境，找出调用 backstory.googleapis.com 或 malachiteingestion-pa.googleapis.com 的自定义脚本或集成。您可以通过查看代码库、自动化脚本和第三方工具来识别这些集成。如果贵组织还使用 Google SecOps SOAR，请参阅迁移 SOAR 集成。

设置身份验证和授权

配置您的环境，以便对向 Chronicle API 发出的请求进行身份验证和授权：

选择身份验证方法：选择工作负载向 Chronicle API 进行身份验证的方式，可从列出的方法中任选其一。我们建议使用工作负载身份联合来提高安全性，因为这样可以避免管理和存储长期有效的服务账号密钥。对于高级身份验证场景（例如服务账号模拟），请参阅向 Chronicle API 进行身份验证。
- 工作负载身份联合（推荐）：设置工作负载身份联合，以允许在 Google Cloud 外部运行的工作负载使用外部身份进行身份验证。
- 服务账号：如果您必须使用服务账号，请在 Google Cloud 项目中创建服务账号，并以 JSON 格式生成和下载私钥。请妥善保管此密钥。
授予 IAM 权限：向用于身份验证的身份（服务账号或外部身份主账号）授予所需的 IAM 权限。请参阅 SIEM API 端点映射，了解替换旧版通话的新版端点所需的特定 IAM 权限。
- 自定义角色（推荐）：创建具有所需权限的自定义 IAM 角色，并将该自定义角色授予服务账号或外部身份主账号。
- 预定义角色：向服务账号或外部身份主账号授予 Google SecOps 预定义角色。这可能会授予超出特定自动化操作所需的权限。
- 多租户合作伙伴委托：如果您是 MSSP 或合作伙伴，负责管理 TenantService 之外的租户资源（例如 GetInstance、UpdateInstance 或 GenerateForwarderFiles），则租户管理员必须在租户的 Google Cloud 项目中，向您的服务账号或工作负载身份联合主账号明确授予所需的 IAM 角色。
设置凭证环境变量：通过设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量，将运行时环境配置为使用具有应用默认凭据 (ADC) 的凭证。此变量应指向下载的服务账号密钥 JSON 文件或工作负载身份联合凭证配置文件。Google Cloud 客户端库会自动检测此变量，以对请求进行身份验证：
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
更新 OAuth 范围：如果您的旧版集成脚本明确请求了用于生成令牌的 OAuth 范围，请更新范围字符串。旧版范围不授予对现代 API Surface 的访问权限：
- 旧版 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 SecOps 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

验证防火墙配置

如果您在环境和互联网之间使用防火墙或经过身份验证的代理，请配置规则以允许在 TCP 端口 443 上建立出站 HTTPS 连接。允许访问以下主机：

Chronicle API 端点：<var>REGION</var>-chronicle.googleapis.com 或 chronicle.<var>REGION</var>.rep.googleapis.com
Google 身份验证端点：oauth2.googleapis.com、www.googleapis.com 和 accounts.google.com（如果您使用工作负载身份联合或服务账号模拟，则还需加上 sts.googleapis.com 和 iamcredentials.googleapis.com）

如需了解完整的端点详情、Google IP 范围指南、专用连接选项和验证步骤，请参阅验证 Chronicle API 的防火墙配置。

更新 API 逻辑

查看 Chronicle API REST 参考文档，确定并实施应用中字段名称和数据结构的更改。虽然某些旧版端点可能保持不变，但您必须更新集成，以匹配最新的数据模型和端点结构。

使用 Google Cloud 客户端库

简化集成，自动处理身份验证、令牌刷新和传输细节。我们建议您使用官方 Google Cloud 客户端库来执行此操作。Chronicle API 支持八种编程语言，包括 Python、Go、Java、Node.js 和 C#。如需了解安装和使用详情，请参阅客户端库和 SDK。

测试您的集成

在部署到生产环境之前，请先在预演环境中测试更新后的应用：

创建测试计划：定义涵盖所有已迁移功能的测试用例。
执行测试：运行自动化和手动测试，以确认准确性和有效性。
监控性能：使用现代 API 评估应用的性能。

问题排查

本部分介绍了如何解决迁移期间可能遇到的常见错误。

HTTP 403 禁止或 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 未授权或 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）。向其他区域发送请求会导致错误。如需查看区域地址的完整列表，请参阅更新服务端点或官方服务端点参考文档。