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

迁移到 Chronicle API

支持范围：

Google SecOps SOAR

本文档概述了相关步骤和注意事项，可帮助您将程序化 API 参考文档更新为 Chronicle API 中的 SOAR API 端点。

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

旧版 SOAR API 和 API 密钥在 2027 年 3 月 31 日之前仍可使用，之后将停止运行。

开箱即用的响应集成

如果您使用的是调用旧版 SOAR API 的过时集成版本，请在 2027 年 3 月 31 日之前更新集成软件包：

内容中心集成：在 Google Security Operations 中打开内容中心，并将所有过时的商业集成更新到最新版本。如需了解详情，请参阅内容中心概览。
Splunk 插件：如果您使用 Chronicle SOAR Add-on for Splunk，请将 Splunk 中的 TA-Siemplify 升级到最新版本。升级后，请重新配置插件，以使用区域级 Chronicle API 端点和 Google Cloud 服务账号凭证。

前提条件

在将 SOAR API 调用迁移到 Chronicle API 之前，请先完成迁移的第 1 阶段（Google.com 会显示在 SOAR 设置 > 许可管理中的系统版本旁边）。您可以在为 SOAR 权限组启用 Google Cloud Identity and Access Management (IAM) 之前或之后，测试和迁移程序化 Chronicle API 调用。

主要变化和增强功能

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

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

弃用时间表

旧版 siemplify-soar.com API Surface 和 AppKey 身份验证在 2027 年 3 月 31 日之前仍可使用，之后将停止运行。

在 2027 年 3 月 31 日之前，旧版 SOAR API 将继续与 Chronicle API 并行运行，即使您启用了 Google Cloud IAM 也是如此。因此，您可以按照自己的节奏逐步迁移和验证每个组件，而不会中断活跃的工作流。

由于旧版 SOAR API 的效率低于 Chronicle API，我们建议您尽快迁移到 Chronicle API 替代方案，并在 2027 年 3 月 31 日之前完成迁移，以免服务中断。

迁移步骤

本部分概述了将应用成功迁移到 Chronicle API 的步骤：

查看文档

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

将端点映射到新的 API Surface

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

可选：创建预演集成

如果您要修改自定义集成或自定义操作，Google 建议您先将更改推送到预演集成。这样，您就可以在不影响生产自动化流程的情况下进行测试。如果您要迁移使用 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 版本。请尽可能使用 v1，如果 v1 尚不可用，则回退到 v1beta 或 v1alpha（请查看 SOAR API 映射表，了解每个端点支持的版本）。
project_id：您的项目 ID（与您为 IAM 权限定义的项目相同）
location：项目的位置（区域）；与区域端点相同
instance_id：您的 Google Security Operations SIEM 客户 ID。

区域级地址：

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

例如，如需获取美国境内某个项目的所有支持请求的列表，请运行以下命令：

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

更新身份验证方法

Chronicle API 使用 Google Cloud IAM 进行身份验证。更新您的自定义集成或外部应用，以实现此身份验证流程。确保运行脚本的用户或服务账号对目标端点拥有所需权限。如需了解详情，请参阅向 Chronicle API 进行身份验证。

将服务账号或 Workload Identity 映射到 SOAR 参数

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

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

注意：向服务账号或主账号授予 Google Cloud IAM 角色是访问 Google SecOps SOAR API 的必要条件，但并非充分条件。如果服务账号未在群组映射中明确映射，则即使配置了所有必需的项目级 IAM 角色，API 请求也会失败并显示 401 UNAUTHENTICATED 错误。

依次前往设置 > 访问权限管理 > 群组映射。
点击添加添加。

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

在 IdP/用户群组字段中，输入以下内容之一：
- 服务账号的完整邮箱（如果身份是使用 Cloud Identity 设置的）。
- Workload Identity 主账号字符串（如果身份是使用员工身份联合设置的）。

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

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

点击 Add（添加）。

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

更新 API 逻辑

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

将自定义 API 调用迁移到 Chronicle API

并非 Google SecOps 中的所有自定义 Python 代码都需要更改：

内置 SDK 方法无需更改代码：自定义集成、Playbook 操作、连接器和作业中使用的标准内置 SDK 方法（例如 siemplify.add_comment()、siemplify.get_case_comments() 或 siemplify.update_alerts_additional_data()）的自定义 Python 代码无需修改代码。Google SecOps 会自动通过统一的 API 接口路由内置 Siemplify SDK 方法。
只有手动 HTTP 请求需要更新：您只需更新使用 SDK 属性手动构建对旧版 SOAR API 的 HTTP 请求的自定义 Python 脚本，例如使用 siemplify.API_ROOT 构建网址，并使用 requests 或 siemplify.session 通过 siemplify.api_key 进行身份验证。如需识别受影响的自定义组件，请在Logs Explorer中运行 resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true"（检查 labels.integration_name、labels.action_name、labels.connector_name、labels.job_name 和 labels.playbook_name），或查看旧版 API 使用情况摘要报告中的 CustomCode 列表。

测试您的集成

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

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

配额和速率限制

Chronicle API 会强制执行 Google Cloud 项目级配额，以维持服务可用性并防止流量失控：

默认配额：Chronicle API 在 Google Cloud 项目级层强制执行每分钟请求数 (RPM) 限制，通常为每个项目 6,000 RPM，并设有区域 API 子限制。
速率限制错误 (HTTP 429)：如果集成或外部脚本超出项目配额，Chronicle API 会返回 HTTP 429（RESOURCE_EXHAUSTED 或 TooManyRequestsException）。

如需查看当前的 Chronicle API 配额用量或申请提高配额上限，请按以下步骤操作：

在 Google Cloud 控制台中，依次前往 IAM 和管理 > 配额和系统限制：

进入“配额和系统限制”
点击过滤条件，选择服务，然后输入 chronicle.googleapis.com，以检查当前用量和限额。如需了解详情，请参阅在 Google Cloud 控制台中查看配额。
如果您的生产提取、自动化或工单集成需要更高的限制，请选中相关配额旁边的复选框，然后点击修改（或修改配额）以申请增加配额。如需了解详细步骤，请参阅申请配额调整。您也可以通过 Cloud Customer Care 或 Google SecOps 代表提交配额增加请求。

审核剩余的旧版 API 使用情况

您可以使用 Logging、产品内系统通知或旧版 API 使用情况摘要端点来识别剩余的旧版 SOAR API 调用。

查询日志记录

旧版 API 弃用警告 (labels.auth_deprecation="true") 会作为 WARNING 严重级别的 SOAR 操作日志在 resource.labels.namespace_name="chronicle-soar" 下发出（请参阅收集 SOAR 平台日志），而不是在 Cloud Audit Logs 中发出。只有客户可采取行动的警告 (labels.actionable_by="Customer") 会导出到您的 Google Cloud 项目；内部 Google 界面和系统调用会自动过滤掉。

在 Logs Explorer 中运行以下查询：

远程代理归因 (labels.is_remote="true")：表示来自远程代理上运行的代码的旧版调用。首先，将远程代理升级到 2.6.2 或更高版本，并将其迁移到服务账号身份验证（请参阅迁移远程代理身份验证基础架构）。升级远程代理并为其配置 Google Cloud 服务账号后，代理自身的控制平面轮询将使用 OAuth 2.0；远程代理 SDK 调用的完整组件标签归因功能正在生产环境中分阶段发布。如果迁移代理后仍有条目，请检查该代理上运行的集成或自定义代码是否已过时。
30 天零日志完成情况检查（所有可由客户操作的旧版通话）：
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
```
如果此查询连续 30 天返回零日志，则表示您的 API 迁移已完成。
直接调用旧版 API 的外部脚本和第三方工具 (AppKey)：
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="false"
```
发出的字段包括 labels.app_key（旧版 API 密钥标识符）、labels.via_xlb（"true" 表示外部入站流量）以及 textPayload (Deprecated direct AppKey authentication detected (Route: ROUTE).) 中调用的 HTTP 路由。
过时的 Content Hub 集成：如需检查已安装的商业集成是否仍调用旧版 SOAR API，请运行以下查询以列出匹配的弃用条目（请参阅开箱即用的响应集成）：
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="true"
labels.is_custom="false"
```
图 1. Logs Explorer 查询结果，其中列出了过时商业集成的弃用条目。

展开匹配的日志条目，查看 labels.integration_name、labels.integration_version、labels.latest_integration_version 和触发组件（labels.action_name、labels.connector_name、labels.job_name 或 labels.playbook_name）：

图 2. 展开的弃用日志条目，其中显示了已安装的商业集成版本和最新商业集成版本。

您还可以查看旧版 API 使用情况摘要报告中的 OutdatedIntegrations 列表。
进行手动 HTTP 调用的自定义 Python 代码：运行 resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true"（请参阅将自定义 API 调用迁移到 Chronicle API）。

查看产品内系统通知

当此功能在 Google SecOps 实例中可用时，系统通知会显示过去 24 小时内，过时的 Content Hub 集成、自定义 IDE 组件和外部 API 密钥中需要客户采取行动的旧版 API 调用摘要，如以下示例所示：

Non-1P API usage summary (last 24h): 2294 legacy API call(s) require action.
Content Hub - Update 1 outdated integration(s): GoogleChronicle (v94->v98).
IDE - Refactor 15 custom component(s): Action 'CustomAction' (LegacyAuthCases),
Connector 'CustomConnector' (LegacyAuthCases), Job 'CustomJob'
(LegacyAuthCases) (+12 more).
Settings > API Keys - Migrate 1 external key(s) to 1P auth:
'example_external_automation_key'.

查询旧版 API 用量摘要端点

您还可以直接查询 GET /api/external/v1/logging/non-1p-api-usage，以检索近期旧版 API 调用的汇总 JSON 报告：

在 SOAR 设置 > 高级 > API 密钥中，创建或选择分配给包含设置权限的权限组的旧版 API 密钥。如需查看相关说明，请参阅向旧版 SOAR API 进行身份验证。

发送包含 AppKey 标头的 GET 请求（将 hoursBack 设置为 1 到 168 之间的值；默认值为 24）：

curl -H "AppKey: API_KEY" \
  "https://INSTANCE.siemplify-soar.com/api/external/v1/logging/non-1p-api-usage?hoursBack=24"

响应会将客户可采取行动的弃用警告分为以下几个部分：

OutdatedIntegrations：列出 InstalledVersion 早于 LatestVersion 的商业 Content Hub 集成，包括 IntegrationName、InstalledVersion、LatestVersion、ActionNeeded、InvocationCount、FirstUsedTimestamp、LastUsedTimestamp 和受影响的组件（AffectedActions、AffectedConnectors、AffectedJobs、AffectedPlaybooks），类似于以下示例：

{
  "OutdatedIntegrations": [
    {
      "IntegrationName": "GoogleChronicle",
      "InstalledVersion": "94",
      "LatestVersion": "98",
      "ActionNeeded": "Upgrade integration to v98 in Content Hub",
      "AffectedActions": ["Ping"],
      "AffectedConnectors": ["Google Chronicle - Chronicle Alerts Connector"],
      "InvocationCount": 202,
      "FirstUsedTimestamp": "2026-10-14T19:16:31Z",
      "LastUsedTimestamp": "2026-10-14T19:44:54Z"
    }
  ]
}

CustomCode：列出进行手动旧版 API 调用的自定义 SDK 组件（ComponentType：Action、Connector、Job、Playbook 或 Custom Script），包括 ComponentName、IntegrationName、AffectedPlaybooks、RoutesUsed、InvocationCount、FirstUsedTimestamp 和 LastUsedTimestamp。

DirectAppKeys：列出在 SDK 之外进行的直接外部 AppKey 调用，包括 AppKey、ActionNeeded、RoutesUsed、InvocationCount、FirstUsedTimestamp 和 LastUsedTimestamp，类似于以下示例：

{
  "DirectAppKeys": [
    {
      "AppKey": "example_external_automation_key",
      "ActionNeeded": "Migrate external script or automation to use Google Cloud service account or OAuth authentication",
      "RoutesUsed": [
        "GET /api/external/v1/cases/GetCaseFullDetails/14",
        "GET /api/external/v1/dynamic-cases/GetCaseDetails/14",
        "GET /api/external/v1/ide/GetIdeItemCards",
        "GET /api/external/v1/jobs/GetInstalledJobs",
        "GET /api/external/v1/jobs/GetJobHistoryLogs/jobIdStr",
        "GET /api/external/v1/logging/non-1p-api-usage",
        "GET /api/external/v1/playbooks/GetWorkflowFullInfoWithEnvFilterByIdentifier/00000000-0000-0000-0000-000000000000",
        "POST /api/external/v1/ide/GetIdeItem",
        "POST /api/external/v1/ide/TestItem",
        "POST /api/external/v1/integrations/GetOptionalIntegrationInstances",
        "POST /api/external/v1/jobs/RunJob",
        "POST /api/external/v1/playbooks/AttacheWorkflowToCase",
        "POST /api/external/v1/playbooks/GetWorkflowMenuCardsWithEnvFilter",
        "POST /api/external/v1/playbooks/RerunPlaybook"
      ],
      "InvocationCount": 1084,
      "FirstUsedTimestamp": "2026-10-14T19:30:15.169684Z",
      "LastUsedTimestamp": "2026-10-14T20:24:13.552893800Z"
    }
  ]
}

TopOffenders（TopAppKeys 和 TopRoutes）：汇总最常用的旧版 AppKey 身份和 HTTP 路由（HTTP 方法和路由），帮助您确定迁移工作的优先级。