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

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

迁移到 Chronicle API

支持：

Google secops SOAR

如果您使用集成、自定义脚本或自定义操作以编程方式调用 SOAR API，则本文档适用于您。本文档简要介绍了相关步骤和注意事项，可帮助您将编程 API 引用更新为 Chronicle API 的一部分的新 SOAR API 端点。

Chronicle API Surface 引入了多项改进，旨在简化您的开发流程。它还解决了旧版 API 中存在的限制和复杂性问题。

旧版 SOAR API 和 API 密钥将一直可用到 2026 年 11 月 30 日，之后将不再有效。

前提条件

在执行 SOAR API 迁移之前，您需要执行以下操作：

完成迁移的第 1 阶段。

主要变化和增强功能

下表重点介绍了新旧 API Surface 之间的主要区别：

功能区域	旧版 API	新版 API	详细信息
身份验证	API 令牌	OAuth 2.0	新的身份验证方法可提供更高的安全性并实现流程标准化。
数据模型	扁平化结构	面向资源的设计	这种新设计可提高数据一致性并简化对象操作。
端点命名	不一致	RESTful 且标准化	一致的命名使 API 更加直观且更易于集成。

弃用时间表

SOAR 的旧版 API Surface 计划于 2026 年 11 月 30 日全面弃用。我们建议您在此日期之前完成迁移，以免服务中断。

迁移步骤

本部分简要介绍了将应用成功迁移到 Chronicle API 的步骤：

查看文档

熟悉新版 API 的全面文档，包括 Chronicle API 参考指南。

将端点映射到新的 API Surface

为应用发出的每个旧版 API 调用确定相应的新的端点。同样，将旧数据模型映射到新数据模型，并考虑任何结构变化或新字段。如需了解详情，请参阅 API 端点映射表。

可选：创建预演集成

如果您要修改自定义集成或商业集成，建议您先将更改推送到预演集成。此过程可让您在不影响生产自动化流程的情况下进行测试。如果您要迁移使用 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 版本。可以是 v1alpha、v1beta 或 v1。
project_id：您的项目 ID（与您为 IAM 权限定义的项目相同）
location：项目的位置（区域）；与区域端点相同
instance_id：您的 Google Security Operations SIEM 客户 ID。

区域地址：

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

例如，如需获取美国境内某个项目的所有案例的列表，请执行以下操作：

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

更新身份验证方法

新版 API 使用 Google Cloud IAM 进行身份验证。您需要更新应用或响应集成，以实现此新的身份验证流程。确保运行脚本的用户拥有尝试访问的端点的正确权限。如需实现此新流程，您必须更新响应集成或应用。确保执行脚本的用户拥有目标端点的必要权限。如需了解详细说明，请参阅向 Chronicle API 进行身份验证页面。

将服务帐号或工作负载身份映射到 SOAR 参数

如果您使用服务帐号或工作负载身份联合向 Chronicle API 进行身份验证，则必须在平台内对其进行授权，以确保其能够成功与 Google SecOps 通信。此映射是必需的，以便为服务帐号或工作负载身份提供对 SOC 角色和环境的必要访问权限。

如需向 Google SecOps 授予服务账号访问权限或工作负载身份联合访问权限，您必须将身份映射到平台的访问权限控制参数。此映射是必需的步骤，以便为身份提供执行自动化任务或 API 操作所需的 SOC 角色 和环境的必要访问权限。

前往SOAR 设置 > 高级 > 群组映射。
点击“添加” Add。

填写添加映射 对话框中的字段，将身份映射到平台的访问权限控制参数。

在 IdP / 用户组 字段中，输入以下内容之一：
- 服务帐号的完整电子邮件地址（如果身份是使用 Cloud Identity 设置的）。
- Workload Identity 正文字符串（如果身份是使用 Workforce Identity Federation 设置的）。

配置以下访问权限控制字段：

字段	说明
权限组	选择权限组以定义身份可以访问的模块和子模块。
SOC 角色	选择 SOC 角色以定义身份的角色（例如第 1 层）。
环境	选择身份可以访问的环境或环境组（例如所有环境）。
群组成员	输入所需的用户电子邮件地址（如果适用）。添加每个电子邮件地址后，按 Enter 键。
受限操作	选择受限操作以限制模块中的特定操作。

点击 Add （添加）。

如需详细了解如何映射用户和服务账号，请参阅使用第三方身份在平台中映射用户或使用 Cloud Identity 在平台中映射用户。

更新 API 逻辑

分析 API 参考中提供的新数据模型和端点结构。并非所有方法都发生了重大变化，并且可以重复使用一些现有代码。主要目标是查看新的参考文档，并针对每个特定用例，识别并实现对字段名称和数据结构的必要更改，这些更改位于您的应用程序逻辑中。

测试您的集成

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

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