将 SOAR 端点迁移到 Chronicle API

支持的服务：

本文档概述了从 已废弃的 SOAR API Surface 迁移到统一的 Chronicle API 的步骤和注意事项。本指南旨在帮助您顺利高效地完成迁移，最大限度地减少中断并充分利用新功能。

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

前提条件

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

主要变化和增强功能

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

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

弃用时间表

SOAR 的旧版 API Surface 计划于 2026 年 9 月 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 角色和环境的必要访问权限。

如需映射您的服务帐号，请执行以下操作：

  1. 前往SOAR 设置 > 高级 > 群组映射。

  2. 点击 add 添加。

  3. 在添加角色对话框中，在IAM 角色 / IdP 群组 字段中输入服务 账号的完整电子邮件地址或 Workload Identity 主账号字符串。

  4. 选择适当的 SOC 角色 和环境 。

  5. 点击 Add 。

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

更新 API 逻辑

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

测试您的集成

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

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

需要更多帮助？获得社区成员和 Google SecOps 专业人士的解答。