将 SOAR 端点迁移到 Chronicle API

支持的平台：

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

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

前提条件

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

主要变化和增强功能

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

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

弃用时间表

SOAR 的旧 API surface 计划于 2026 年 6 月 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

  • 我们：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 进行身份验证。您需要更新应用或响应集成，以实现这一新的身份验证流程。确保运行脚本的用户拥有对所尝试访问的端点的正确权限。

更新 API 逻辑

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

测试您的集成

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

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

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