Datadog 是监控与可观测性平台，通过 Webhook 通知把告警与恢复事件推送给自建接收服务，再由接收服务调用 ONES 开放平台 REST API v2，在工作项上完成建单、评论或状态流转。本文给出的是自建对接方案设计，Datadog 侧 Webhook 能力有文档依据，ONES 侧的 CN 接口路径、字段与状态映射仍需在目标部署上逐项核验，尚未完成端到端实测。
要点总览（TL;DR）
- 链路为 Datadog Webhook 通知 → 自建接收服务 → ONES 开放平台 REST API v2，单向推送加主动调用，接收服务承担鉴权、去重、字段映射与重试。
- 三类事件分开处理：告警首次到达创建工作项，同一告警的重复通知追加评论，恢复通知追加恢复评论或按映射触发状态流转。
- 恢复通知不等同于自动关闭所有缺陷，是否关闭取决于团队工作流定义；Webhook 存在超时与重试，接收端必须按告警标识去重。
- 接入前确认凭据类型与版本条件：组织凭据文档标注 ONES 6.2.18 及以上，个人 Token 刷新后旧令牌失效，Scope 变更需重新授权。
- 验收覆盖建单、评论、恢复、去重与重新授权五类结果，当前为未实测状态，需在目标部署上逐条完成并留存日志。
告警、恢复与ONES之间走哪条数据链路
这条链路的核心判断是：Datadog 负责产生事件，接收服务负责翻译事件，ONES 开放平台负责承载工作项。三者之间是单向推送加主动调用，不构成双向同步，也不承诺实时性。Datadog Webhooks 集成可发送 JSON 通知，支持自定义载荷和请求头，前提是在监控通知中配置相应 Webhook。这意味着告警名称、严重级别、触发时间、来源链接等信息可以由 Datadog 侧组织进请求体，接收服务按约定格式解析即可。
建议的链路为：Datadog 告警通知 → 自建接收服务 → ONES 开放平台 REST API v2。数据方向是 Datadog 向接收服务推送，接收服务再向 ONES 发起调用；ONES 侧不会反向回写 Datadog。接收服务是整条链路中唯一需要开发的组件，职责包括校验请求来源、管理 ONES 凭据、按告警标识去重、把 Datadog 字段映射为 ONES 工作项字段、处理调用失败与重试、记录可追溯的日志。
| 组件 | 方向 | 主要职责 |
|---|---|---|
| Datadog 监控通知 | 发出 | 按配置的 Webhook 发送 JSON 告警与恢复通知，携带自定义载荷和请求头 |
| 自建接收服务 | 接收并转发 | 鉴权、去重、字段映射、调用 ONES API、重试与日志 |
| ONES 开放平台 REST API v2 | 被调用 | 创建工作项、追加评论、按映射触发状态流转 |
需要明确的是，这套衔接属于自建方案，Datadog 与 ONES 之间没有可直接启用的原生插件。下文给出的字段、状态与异常处理都是设计草案，落地前要在目标部署上验证接口契约与工作流配置。
接入前要准备哪些凭据、权限与版本条件
接入准备的重点是认证方式与版本前提。ONES 开放平台提供 REST API v2，用于应用开发和系统集成，目标租户必须支持对应 API 版本。开放平台文档区分个人 OAuth 凭据和组织凭据，两者代表的身份及作用范围不同，接收服务以哪种身份调用，会直接影响工作项的创建人、可见范围和操作权限，需要按实际归属先定下来。
请求认证使用 Bearer Token，接口路径示例为 /openapi/v2/。这个示例只是路径前缀，不是创建工作项的完整接口地址，具体端点、参数与返回值必须按目标部署的文档确认。国内开放平台入口与 COM 文档体系不能仅凭名称视为同一套接口契约，照搬路径容易在联调阶段返工。
- 版本条件：组织凭据能力在文档中标注为 ONES 6.2.18 及以上，实施前确认实际版本、管理角色及授权范围。
- 令牌刷新：个人 Token 刷新会产生新的访问和刷新令牌，旧令牌失效，接收服务需保存并使用新令牌，否则链路会在刷新后中断。
- Scope 变更：改变凭据 Scope 不会自动改变已发出的 Token，需重新授权使新范围生效，只改配置而继续用旧授权会持续报权限错误。
- 权限核验：确认调用身份对目标项目、工作项类型、评论与状态流转字段具备操作权限。
建议把上述内容整理成一张准备清单，逐项标注确认人与确认结果，尤其是版本号、凭据类型、授权范围和目标项目，这四项决定了后续映射能否成立。
告警建单、已有任务评论与恢复处理怎么分别设计
三类事件需要分开设计，避免用一套逻辑处理所有通知。告警首次到达时创建工作项，载荷至少包含告警标识、告警名称、严重级别、触发时间、来源链接；同一告警的后续通知按告警标识匹配已有工作项，追加评论而不新建；恢复通知按映射规则追加恢复评论或触发状态流转。恢复通知不等同于自动关闭所有缺陷，是否关闭、关闭到哪个状态，取决于团队对工作流状态的定义。
告警状态到 ONES 工作流状态的映射需要自行定义。下面是一份示意映射草案，仅用于说明设计方法，具体状态名与流转规则以目标部署的工作流配置为准，并需在联调中验证。
| Datadog 事件 | 接收服务动作 | ONES 侧结果（待验证） |
|---|---|---|
| 告警首次触发 | 按告警标识查询是否存在工作项，不存在则创建 | 新增工作项，写入名称、级别、触发时间与来源链接 |
| 同一告警重复通知 | 命中已有工作项，追加评论 | 工作项新增一条告警更新评论，不新增工作项 |
| 告警恢复 | 追加恢复评论，或按映射触发状态流转 | 工作项新增恢复评论，或状态变为待验证/已恢复 |
示意载荷可以按如下结构组织，字段名由接收服务与 Datadog 自定义载荷共同约定，属于方案设计而非官方字段定义：
{
"alert_id": "示例告警标识",
"alert_name": "示例告警名称",
"severity": "示例级别",
"triggered_at": "示例触发时间",
"source_url": "示例来源链接",
"event_type": "alert 或 recovery"
}
告警关联键、CN 字段与状态映射、恢复通知内容目前属于资料核验缺口，只能作为待验证设计。建议在联调前先与目标部署的管理员确认工作项类型、必填字段与状态机，再回填映射表，避免接收服务写完才发现字段对不上。
重试、重复通知与异常怎么处理
Datadog Webhook 存在超时和重试行为，接收端应按同一告警标识去重，不能把每次通知都创建为新缺陷。去重的关键是选择一个在告警生命周期内稳定的标识，并把它与已创建的 ONES 工作项建立对应关系。存储位置可以放在接收服务自己的数据库或缓存中，记录告警标识、工作项 ID、最近处理时间与处理结果。
- 重复建单防护：收到通知后先查去重表，命中则走评论分支，未命中才调用创建工作项接口，创建成功后立即写入去重表。
- 调用失败重试：接收服务调用 ONES 失败时按退避策略重试，重试前再次检查去重表，避免重复评论或重复流转。
- 令牌失效识别：认证失败时区分令牌过期与权限不足，前者触发刷新并保存新令牌，后者检查 Scope 是否已重新授权。
- 恢复先于建单到达：恢复通知找不到对应工作项时，可暂存为待处理事件，待建单成功后再补写恢复评论，或按规则直接建单并标注已恢复。
- 无法匹配已有工作项：记录原始载荷并进入人工兜底队列，由值班人员判断是否需要手工建单。
- 失败留痕：每次调用记录请求摘要、响应状态与错误信息，保留可追溯的处理日志。
异常处理的目标是让链路在部分失败时仍可恢复，而不是追求零错误。建议为接收服务设置一个可查询的失败记录视图，值班人员能据此判断是重放、补录还是人工关闭。
怎样验证这条链路已经跑通
验收要覆盖建单、评论、恢复与去重四类结果，并在目标部署上实际执行。当前方案处于未实测状态，以下验收项需要在联调环境中逐条完成并留存证据。
| 验收项 | 预期结果 | 证据形式 |
|---|---|---|
| 首次告警建单 | 工作项创建成功，名称、级别、触发时间、来源链接完整 | 接收服务日志、ONES 工作项记录 |
| 重复通知处理 | 只产生评论，不新增工作项 | 去重命中记录、工作项评论列表 |
| 恢复通知处理 | 按映射产生恢复评论或状态变化，不误关缺陷 | 工作项状态历史、评论记录 |
| 令牌刷新后链路 | 刷新并保存新令牌后调用恢复正常 | 认证日志、调用成功记录 |
| Scope 变更后链路 | 重新授权后新范围生效，调用不再报权限错误 | 授权记录、调用日志 |
验收时建议先用手工构造的告警与恢复载荷跑通单条链路，再接入真实监控通知观察重复通知与超时重试的表现。全部验收项通过并留存日志后，这条自建链路才算在目标部署上完成验证。
常见问题
Datadog 的恢复通知到达时，接收服务应该直接关闭工作项吗？
不建议把恢复通知直接等同于关闭。恢复只说明监控侧指标回到阈值内，工作项是否关闭取决于团队对缺陷与告警的处理约定，例如是否还需要人工确认、是否要等待验证。可行的做法是让恢复通知追加一条恢复评论，或按预先定义的映射把状态推进到待验证一类的中间状态，再由负责人决定是否关闭。状态名与流转规则以目标部署的工作流配置为准，属于待验证设计。
接收服务用个人凭据还是组织凭据调用 ONES API？
开放平台文档区分个人 OAuth 凭据和组织凭据，两者代表的身份与作用范围不同，会直接影响工作项的创建人、可见范围和操作权限。组织凭据能力在文档中标注为 ONES 6.2.18 及以上，实施前需确认实际版本、管理角色与授权范围。如果告警建单需要归属到固定的集成账号，通常倾向组织凭据；如果只是个人调试，个人凭据更简单。选定后把凭据类型写进准备清单，避免联调阶段反复切换。
令牌刷新或 Scope 调整后链路中断，怎么排查？
先看认证日志区分两类失败：个人 Token 刷新会产生新的访问和刷新令牌、旧令牌失效，接收服务必须保存并使用新令牌；改变凭据 Scope 不会自动改变已发出的 Token，需要重新授权使新范围生效。前者表现为旧令牌被拒，后者表现为权限不足。排查时确认接收服务读取的是最新令牌、授权记录已更新，再重放一条测试通知验证调用恢复。
恢复通知比建单通知先到，或者重复通知连续到达，怎么处理？
Webhook 存在超时和重试行为，接收端应按同一告警标识去重，不能把每次通知都创建为新缺陷。恢复先到时，可把事件暂存为待处理记录，待建单成功后再补写恢复评论，或按规则直接建单并标注已恢复。重复通知到达时先查去重表，命中则走评论分支，未命中才调用创建工作项接口，创建成功后立即写入去重表，重试前再次检查，避免重复评论或重复流转。
联调时怎样确认接口路径和字段没有用错？
ONES 开放平台提供 REST API v2，文档中的接口路径示例为 /openapi/v2/，这只是路径前缀，不是创建工作项的完整地址。国内开放平台入口与 COM 文档体系不能仅凭名称视为同一套接口契约，具体端点、参数与返回值要按目标部署的文档确认。联调时先用手工构造的告警与恢复载荷跑通单条链路，核对工作项字段与状态是否符合映射草案，再接入真实监控通知观察重复与重试表现。
官方参考资料
- ONES Open API v2（ONES）
- Open API Authentication And Authorization（ONES）
- Webhooks integration（Datadog）
