OneUptime REST API 参考指南：API Key 认证、资源端点与自动化集成

OneUptime REST API 参考指南API Key 认证、资源端点与自动化集成【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 提供了一套完整的 REST API可将监控Monitoring、事件管理Incident Management与状态页Status Page能力集成到自有应用和运维工作流中。原文档 api-reference.md德语版给出了入门要点API 基于 REST 原则构建、使用标准 HTTP 响应码与认证机制、所有端点均返回 JSON 响应且在 OneUptime Dashboard 中能做的任何事情都可以通过 API 完成从而支持自动化与自定义集成。读完本文你将掌握 API 的认证方式、参考站点的页面结构、多语言路由机制以及可直接复制的调用示例。一、API 总体设计REST 原则与 JSON 响应按照文档入门章节的说明OneUptime API 的设计约定可以归纳为三点REST 风格组织端点按资源Resource划分使用标准 HTTP 动词GET/POST/PUT/PATCH/DELETE表达语义标准 HTTP 响应码成功、客户端错误4xx、服务端错误5xx均遵循通用语义便于程序化判断统一 JSON 响应所有 API 端点返回 JSON可直接被脚本、CI/CD 管道或后端服务消费。这一约定在参考站点的服务端实现中可以得到印证App/FeatureSet/APIReference/Index.ts 在特性集初始化时init注册了一整套/reference/*路由其中每个资源模型都有对应的文档页处理器ModelServiceHandler并且 CodeExamples/Model 目录下按 CRUD 语义组织了完整的请求/响应示例文档——ListRequest/ListResponse、ItemRequest/ItemResponse、CreateRequest/CreateResponse、UpdateRequest/UpdateResponse、DeleteRequest/DeleteResponse、CountRequest/CountResponse说明 API 对每个资源提供了列表、单条读取、创建、更新、删除与计数六类标准操作。此外CodeExamples/DataTypes 目录列出了查询可使用的数据类型操作符文档包括EqualTo、EqualToOrNull、NotEqualTo、GreaterThan、GreaterThanOrEqual、LessThan、LessThanOrEqual、Includes、IsNull、NotNull、Select、Sort等说明列表类端点支持条件过滤与排序参数可用于自动化脚本中按状态、时间等条件拉取资源。二、认证API Key 的生成与使用文档明确所有 API 请求都必须使用 API 密钥API-Schlüssel认证密钥在 Dashboard 的 设置Einstellungen API 密钥API-Schlüssel 中生成。参考站点的认证页面模板 authentication.ejs 进一步给出了实际调用方式第 38 行处的代码示例curl --header ApiKey: {secret-api-key} https://oneuptime.com/api/path即认证凭据通过 HTTP 请求头ApiKey传递值为在 Dashboard 生成的密钥。该页面还包含三个关键小节对应模板中的generateApiKey、projectId、authWithApiKey三个锚点生成 API Key在 Dashboard 设置中创建并引导读者跳转至权限permissions页了解密钥的权限范围Project ID项目 ID部分端点需要指明目标项目/工作区文档单独设节说明密钥安全警告模板中以警告框warning文案提示保护密钥安全。关于密钥形态从 CLI 认证文档 可以看到OneUptime 的 API 密钥以sk-前缀开头例如sk-your-api-key。若通过官方 CLI 操作凭证解析遵循固定的优先级顺序CLI 标志--api-key与--url环境变量ONEUPTIME_API_KEY与ONEUPTIME_URL通过--context指定的命名上下文当前上下文保存在~/.oneuptime/config.json文件权限0600。因此在 CI 环境中推荐直接使用环境变量方式调用 APIexport ONEUPTIME_API_KEYsk-abc123 export ONEUPTIME_URLhttps://oneuptime.com oneuptime incident list或者最直接的 curl 方式curl --header ApiKey: $ONEUPTIME_API_KEY \ $ONEUPTIME_URL/api/resource-path三、参考站点/reference的页面结构与源码映射文档正文的核心指向是参考站点原德语文档给出链接/reference英文原文补充说明参考站点支持多语言首选语言由浏览器自动检测可随时通过顶部导航的语言选择器切换。这一语言自动检测行为可以直接在路由源码中找到对应实现。路由与语言解析App/FeatureSet/APIReference/Index.ts 中的pickLanguage函数定义了语言选择优先级URL 参数:lang若为受支持的语言代码则直接采用请求头Accept-Language按权重拆分后逐个匹配主语言代码回退到默认文档语言DEFAULT_DOCS_LANGUAGE即英文。静态资源则挂载在/reference下并设置 30 天缓存maxAge: 2592000见 Index.ts 第 68 行。页面处理器一览从 Index.ts 第 127-154 行 的分支逻辑可以确认参考站点包含以下页面每个页面均有独立的 Service 处理器页面路径/reference/:lang/之后处理器内容主题introductionIntroduction.ts入门与推荐资源Featured ResourcesauthenticationAuthentication.tsAPI Key 认证、项目 IDpermissionsPermissions.ts权限体系paginationPagination.ts分页请求/响应约定见 Pagination 代码示例errorsErrors.ts错误码说明openapiOpenAPI.tsOpenAPI 规范入口statusStatus.tsAPI 状态说明master-admin-apisMasterAdminApis.ts实例级管理员 API仅自托管data-types及各类型详情页DataType.ts / DataTypeDetail.ts数据类型操作符参考各资源模型名Model.ts单个资源的端点文档CRUD 计数值得注意的一个分支条件是master-admin-apis页面仅在IsBillingEnabled为false时可达Index.ts 第 141-147 行。源码注释说明实例级管理员 API 由持有实例主 API 密钥的人访问而主密钥只存在于自托管self-hosted安装中在启用计费SaaS的构建里该页面会落入 404。这明确了该文档体系适用的前提限制master admin APIs 章节只对自托管部署有意义。兼容旧 URL 的重定向源码中还保留了两类兼容路由保证旧书签继续可用根路径/reference与/reference/:lang重定向到对应语言的 introduction 页Index.ts 第 73-92 行单段旧 URL/reference/:page按pickLanguage结果重定向到/reference/:lang/:pageIndex.ts 第 176-183 行未匹配的语言感知 404 与兜底/reference/*路由返回 404 页。四、多语言文档体系从 Docs 站点到参考站点原关联文档本身属于 OneUptime 文档站点的多语言内容树App/FeatureSet/Docs/Content/de/api-reference/api-reference.md 是德语de版本同级目录en、zh-CN、ja、ko、fr等下存在同一章节的其他语言版本英文版内容与德语版一致REST 入门、认证、指向参考站点仅补充了语言自动检测 顶部切换的说明。参考站点自身的界面文案则放在 App/FeatureSet/APIReference/Locales/ 下按语言组织为en.json、de.json、zh-CN.json等 17 个文件页面渲染时通过buildRenderContextRenderContext.ts与t()翻译函数注入对应语言文案如 Authentication.ts 中的ctx.t(pages.authentication.metaTitle)用法。五、实战集成清单结合原文档承诺的Dashboard 能做的都能通过 API 做一个最小可用的自动化集成流程是生成密钥Dashboard → 设置 → API 密钥创建一个作用域合适的密钥验证调用curl --header ApiKey: $ONEUPTIME_API_KEY $ONEUPTIME_URL/api/resource-path确认返回 JSON 且 HTTP 状态码为 2xx列表与过滤参考各资源模型的 List 端点文档利用数据类型操作符如EqualTo、GreaterThan、Includes构造查询条件并遵循 Pagination 约定 处理分页处理错误以 errors 页 的错误码语义为标准实现重试与告警逻辑自托管场景如需实例级管理操作参考 master-admin-apis 页注意仅在自托管构建中可用。六、延伸阅读路径关联原文档App/FeatureSet/Docs/Content/de/api-reference/api-reference.md德语及 英文版参考站点路由与语言解析App/FeatureSet/APIReference/Index.ts参考站点各页面处理器App/FeatureSet/APIReference/Service/CRUD 请求/响应代码示例App/FeatureSet/APIReference/CodeExamples/CLI 认证与多环境上下文配置App/FeatureSet/Docs/Content/de/cli/authentication.md。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考