企业官网建设流程全解析

OneUptime 公开状态页 API 使用指南：通过 HTTP 接口读取监控状态、事件与维护信息

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

公开状态页 API（Public Status Page API）是 OneUptime 提供给外部系统读取状态页数据的无鉴权 HTTP 接口，用于将监控总览、事件（Incidents）、计划维护（Scheduled Maintenance）与公告（Announcements）以结构化 JSON 形式交付给第三方系统。本文基于仓库内 de/status-pages/public-api.md 编写，并结合 StatusPageAPI.ts 源码逐条验证端点的真实行为与参数约束，读完即可直接对接该 API 构建自己的状态监控聚合面板。

API 概览

公开状态页 API 的核心用法非常简单：向对应端点发送一个POST请求即可，无需携带 API Key 或身份令牌。所有端点统一挂在/status-page-api路由前缀之下（该前缀定义于 StatusPage/src/Utils/Config.ts），并在 StatusPageAPI.ts 中注册实现。

其中:statusPageId是状态页的唯一标识。需要说明的是，源码中总览、事件、维护、公告四个端点实际注册的路径参数为:statusPageIdOrDomain（详见下文“ID 与自定义域名解析”小节），即除状态页 ID 外还支持传入状态页绑定的自定义域名，这比文档示例更具灵活性。

总览 API（Overview API）

总览 API 一次性返回状态页上所有资源的状态数据，包括资源的总体状态、事件、计划维护、公告、状态时间线等全部视图数据，是构建状态聚合看板最常用的端点。

请求方式：

curl -X POST https://oneuptime.com/status-page-api/overview/:statusPageId

该端点对应的路由注册位于 StatusPageAPI.ts，返回的 JSON 响应包含以下字段（字段结构与文档中的完整响应示例一致）：

{ "overallStatus": { // Monitor Status 对象 // 总体状态取状态页上所有监控器与监控组中最差的那个状态 }, "scheduledMaintenanceEventsPublicNotes": [ // Scheduled Maintenance Public Note 对象（计划维护的公开说明） ], "statusPageHistoryChartBarColorRules": [ // Status Page History Chart Bar Color Rule 对象（历史图表柱状图着色规则） ], "scheduledMaintenanceEvents": [ // Scheduled Maintenance Event 对象 ], "activeAnnouncements": [ // Status Page Announcement 对象（进行中的公告） ], "incidentPublicNotes": [ // Incident Public Note 对象（事件的公开说明） ], "activeIncidents": [ // Incident 对象（进行中的事件） ], "monitorStatusTimelines": [ // Monitor Status Timeline 对象（监控器状态时间线） ], "resourceGroups": [ // Resource Group 对象（资源分组） ], "monitorStatuses": [ // Monitor Status 对象 ], "statusPageResources": [ // Status Page Resource 对象（状态页资源） ], "incidentStateTimelines": [ // Incident State Timeline 对象（事件状态流转时间线） ], "statusPage": { // Status Page 对象（状态页自身配置信息） }, "scheduledMaintenanceStateTimelines": [ // Scheduled Maintenance State Timeline 对象（维护状态流转时间线） ], "monitorGroupCurrentStatuses": { // 监控组的当前状态 }, "monitorsInGroup": { // 分组中的监控器 } }

各字段对应实体可在状态页与事件相关的数据模型中找到，例如监控器状态、状态时间线等对象由 StatusPageAPI.ts 顶部引入的MonitorStatusService、MonitorStatusTimelineService、IncidentService、ScheduledMaintenanceService、StatusPageAnnouncementService等服务加载后组装。理解这些对象的字段含义，建议结合 资源与分组文档 阅读。

实现层面的两个关键细节（源码可验证）：

• 访问控制前置：响应构建之前，每个请求都会先经过checkHasReadAccess检查（StatusPageAPI.ts），私有页面、IP 白名单、主密码（master password）等访问约束在这里强制执行，即使后续命中缓存也不会绕过。
• 响应缓存：总览响应用InMemoryTTLCache按statusPageId做进程内缓存，并配套“in-flight 合并”机制——冷缓存时并发请求会共享同一次数据库构建而非各自打库；同时响应会设置no-cache头（StatusPageAPI.ts），避免共享缓存层缓存到可能包含私有页面数据的响应。

可用率 API（Uptime API）

可用率 API 用于获取状态页上所有资源的可用率数据。

请求方式：

curl -X POST https://oneuptime.com/status-page-api/uptime/:statusPageId

可选请求体（request body）：

可通过startDate与endDate指定统计时间范围：

{ "startDate": "2021-09-01T00:00:00Z", "endDate": "2021-09-30T23:59:59Z" }

参数约束（源码 StatusPageAPI.ts 可逐条验证）：

• startDate与endDate使用 ISO 8601 时间字符串（如2021-09-01T00:00:00Z）；
• 两个日期之间的跨度不得超过 90 天，超出会抛出BadDataException（错误信息：You can only get uptime for 90 days. Please select a date range within 90 days.）；
• startDate不得晚于endDate（否则抛出Start date cannot be after end date）；
• 不传任何日期时，默认统计最近 14 天：源码中startDate默认取 14 天前（OneUptimeDate.getSomeDaysAgo(14)），endDate默认为当前时间；
• 若只传endDate而未传startDate，则startDate自动取endDate前 14 天。

可用率的统计精度与计算由StatusPageResourceUptimeUtil（Common/Utils/StatusPage/ResourceUptime 引入）负责，时间范围确定后，接口会加载该范围内的监控状态时间线并计算各资源与分组的可用率。

事件 API（Incidents API）

事件 API 用于获取状态页上全部事件（Incidents）列表。事件是状态页中记录服务异常与故障的核心数据来源。

请求方式：

curl -X POST https://oneuptime.com/status-page-api/incidents/:statusPageId

事件数据来自IncidentService、IncidentPublicNoteService与IncidentStateTimelineService，响应中包含事件本体、公开说明与状态流转时间线。事件产生的背景与生命周期可参考 事件概览文档 关联的 Incident 模块说明。

计划维护 API（Scheduled Maintenance API）

计划维护 API 用于获取状态页上的全部计划维护（Scheduled Maintenance）信息。

请求方式：

curl -X POST https://oneuptime.com/status-page-api/scheduled-maintenance/:statusPageId

值得注意的源码细节：该端点在 StatusPageAPI.ts 中实际注册的路径为/scheduled-maintenance-events/:statusPageIdOrDomain（比文档示例多-events后缀，并同样支持域名解析）。维护数据由ScheduledMaintenanceService、ScheduledMaintenancePublicNoteService、ScheduledMaintenanceStateTimelineService组装。

公告 API（Announcements API）

公告 API 用于获取状态页上的全部公告（Announcements），例如面向订阅者的通知声明。

请求方式：

curl -X POST https://oneuptime.com/status-page-api/announcements/:statusPageId

公告数据由StatusPageAnnouncementService提供。公告的创建与管理属于状态页订阅者功能的一部分，可结合 订阅者与公告文档 了解其业务含义。

源码实现要点：ID 与自定义域名解析

文档示例统一使用:statusPageId作为路径参数，但从 StatusPageAPI.ts 的源码可以看到，总览、事件、计划维护、公告四个端点都经过resolveStatusPageIdOrThrow函数处理：

• 该函数调用StatusPageService.resolveStatusPageIdOrNull，同时支持状态页 ID 与状态页绑定的自定义域名；
• 自定义域名到状态页 ID 的解析带有缓存（每个域名在 TTL 内只需一次 Postgres 查询，而不是每个请求一次）；
• 解析不到对应的状态页时抛出NotFoundException（"Status Page not found"）。

这意味着你在实际对接时，/status-page-api/overview/:statusPageIdOrDomain这类端点可以传入状态页 ID，也可以传入该状态页配置的自定义域名（域名绑定配置见 品牌与域名文档），这为通过自有域名聚合多个状态页提供了便利。

进一步阅读

• 状态页概览 —— 状态页是什么，各组成部分如何协同；
• 状态页资源与分组 —— 上述端点返回的资源对象详解；
• 状态页品牌与域名 —— 通过自定义域名交付这些端点的配置方式；
• 订阅者与公告 —— 公告端点所返回公告的来源与订阅管理；
• StatusPageAPI.ts —— 全部公开状态页端点的源码实现（路由注册、访问控制、缓存与日期校验）；
• StatusPage/src/Utils/Config.ts ——/status-page-api路由前缀的定义位置。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime