OneUptime 公开状态页 API 使用指南通过 HTTP 接口读取监控状态、事件与维护信息【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime公开状态页 APIPublic 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 中注册实现。端点相对路径说明POST /status-page-api/overview/:statusPageId获取状态页全部资源的总览数据POST /status-page-api/uptime/:statusPageId获取状态页所有资源的可用率POST /status-page-api/incidents/:statusPageId获取状态页上的全部事件POST /status-page-api/scheduled-maintenance/:statusPageId获取状态页上的全部计划维护POST /status-page-api/announcements/:statusPageId获取状态页上的全部公告其中:statusPageId是状态页的唯一标识。需要说明的是源码中总览、事件、维护、公告四个端点实际注册的路径参数为:statusPageIdOrDomain详见下文“ID 与自定义域名解析”小节即除状态页 ID 外还支持传入状态页绑定的自定义域名这比文档示例更具灵活性。总览 APIOverview 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避免共享缓存层缓存到可能包含私有页面数据的响应。可用率 APIUptime 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 天。可用率的统计精度与计算由StatusPageResourceUptimeUtilCommon/Utils/StatusPage/ResourceUptime 引入负责时间范围确定后接口会加载该范围内的监控状态时间线并计算各资源与分组的可用率。事件 APIIncidents API事件 API 用于获取状态页上全部事件Incidents列表。事件是状态页中记录服务异常与故障的核心数据来源。请求方式curl -X POST https://oneuptime.com/status-page-api/incidents/:statusPageId事件数据来自IncidentService、IncidentPublicNoteService与IncidentStateTimelineService响应中包含事件本体、公开说明与状态流转时间线。事件产生的背景与生命周期可参考 事件概览文档 关联的 Incident 模块说明。计划维护 APIScheduled 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组装。公告 APIAnnouncements 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 查询而不是每个请求一次解析不到对应的状态页时抛出NotFoundExceptionStatus 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考