跳转到主要内容
Open API 用于通过 HTTP 接口主动调用 Flashduty,查询和管理故障、协作空间、值班表等实体数据。使用 API 与您登录 Flashduty 控制台 后进行页面操作本质上是相同的。
不确定是否需要 Open API? Flashduty 提供多种数据交互方式:
  • Open API(本文档)— 您主动调用 Flashduty,查询或操作数据。查看 API 总览 了解全部接口。
  • 标准告警事件 — 将自研监控系统的告警推送到 Flashduty,触发故障处理流程。详见自定义告警事件。
  • 自定义变更事件 — 推送变更事件关联故障,辅助根因分析。详见自定义变更事件。
  • Webhook 推送 — Flashduty 主动向您的系统推送故障/告警事件通知。详见故障 Webhook 和告警 Webhook。
  • 自定义操作 — 在故障详情页触发外部操作。详见自定义操作。

请求规范

请求地址

所有 API 只接受 HTTPS 访问,且只有一个 Endpoint:

请求方法与 Headers

绝大多数接口使用 POST 方法、JSON 请求体,请设置:
少数读接口使用 GET 方法和 query 参数(例如状态页的查询接口、Prometheus 兼容的标签查询),以各接口页面标注的方法为准。不需要参数的 POST 接口请传 {}。

字符编码

请求与响应均使用 UTF-8 编码。

响应语言

错误信息会按语言返回。语言依次取自 query 参数 locale、query 参数 lang、请求头 Accept-Language,例如 Accept-Language: zh-CN 或 en-US。字段名、枚举值和错误码不会被翻译。

认证方式

所有 Open API 使用 APP Key 进行鉴权。

获取 APP Key

1

登录控制台

2

创建 APP Key

将鼠标悬停在左下角头像上,在 个人中心 一列选择 APP Key,输入名称并选择权限范围后,点击添加按钮完成创建。详见个人设置。
  • 全部权限:不额外限制接口范围,但仍受创建者当前角色权限约束。
  • 自定义权限:从可选 API 权限点中至少选择一项;该 APP Key 只能调用选中的接口范围。
APP Key 的实际可访问范围同时受其权限范围和创建者当前角色权限限制。创建成功后请立即妥善保存完整密钥;离开创建页面后无法再次查看。不要把 APP Key 硬编码在客户端代码里,请通过环境变量或密钥管理服务注入,并及时删除不再使用的密钥。
您可以在 APP Key 列表中编辑已有密钥的名称和权限范围。

APP Key 泄露了怎么办

如果 APP Key 可能已泄露(例如被提交到公开代码仓库,或出现在日志、截图中),请按以下步骤处置:
1

创建替代密钥

在 个人中心 → APP Key 中创建一个新的 APP Key。
2

切换集成

把使用旧密钥的集成、脚本和配置切换到新密钥,并确认调用正常。
3

禁用或删除旧密钥

在 APP Key 列表中禁用或删除旧密钥。之后使用旧密钥的请求返回 401 Unauthorized。

传递 APP Key

通过 query 参数 app_key 传入:
也可以放在请求头 Fd-App-Key 中,避免密钥出现在 URL 和访问日志里:
两者同时存在时以 query 参数为准。缺少或无效的 APP Key 返回 401 Unauthorized。
使用 Go?推荐用官方 Go SDK 调用 Flashduty,直接获得类型化的请求参数、响应结构和错误码,无需手写 HTTP 请求。

响应结构

所有响应均为 JSON,遵循统一结构: 成功时 HTTP 状态码为 200。失败时返回错误码列表中对应的 HTTP 状态码,但请以 error.code 而不是状态码做判断。

响应示例

Error 对象结构


数据约定

  • 时间戳均为 Unix 时间戳整数。大多数以秒为单位;部分(AI SRE 和 RUM 的大多数时间字段、故障动态、审计日志)以毫秒为单位。每个时间字段的描述都会写明单位。
  • 枚举区分大小写,可能是字符串或整数;每个字段都会列出可选值及含义。
  • ID 按各字段标注的类型(整数或字符串)返回,回传时请保持相同类型。
  • 列表均分页返回,见关于分页。
  • 更新接口会逐字段说明:不传某字段时是保留原值还是清空。

限制与错误

频率限制、权限校验、完整错误码列表和重试建议见使用限制与错误码。每个接口页面的 限制说明 部分也列出了该接口自己的频率限制和所需权限。