Glance custom-api 如何用 subrequests 与模板内 newRequest 链式调用多个 API【免费下载链接】glanceA self-hosted dashboard that puts all your feeds in one place项目地址: https://gitcode.com/GitHub_Trending/gla/glance当你想让一个 Glancecustom-api组件同时展示多个 JSON API 的数据时官方文档给出了两条路径区别在于两次调用之间有没有依赖关系subrequests在 YAML 里声明附加请求它们与主请求并发执行结果通过.Subrequest key在模板中读取。适用于彼此独立、只需要汇总展示的数据源。newRequest/getResponse在模板内部发起 HTTP 请求第一次调用的返回字段可以拼进第二次调用的 URL 或参数。适用于“第一次调用拿到 ID第二次用这个 ID 拉详情”这类顺序依赖的场景。两条路径的用法分别记录在 docs/custom-api.md 的示例部分和 docs/configuration.md 的subrequests属性小节中。先判断该用哪条路径情况方案关键点多个 API 互不依赖汇总到一个组件subrequests模板里用.Subrequest key访问第二个请求的 URL/参数取决于第一个请求的响应模板内newRequest \| getResponsegetResponse的返回值可用.JSON读取字段URL 需要动态参数如“最近 24 小时”的时间戳省略url请求完全放在模板内newRequestwithParameter由于 subrequests 与主请求是并发发起的某个 subrequest 无法使用另一个 subrequest 的结果存在依赖关系时只能走模板内请求这条路。用 subrequests 并行拉取多个独立 APIsubrequests是一个 mapkey 是模板里要用的名字value 是一个完整的请求定义。官方文档中的示例- type: custom-api cache: 2h subrequests: another-one: url: https://uselessfacts.jsph.pl/api/v2/facts/random title: Random Fact url: https://uselessfacts.jsph.pl/api/v2/facts/random template: | p classsize-h4 color-paragraph{{ .JSON.String text }}/p p classsize-h4 color-paragraph margin-top-15{{ (.Subrequest another-one).JSON.String text }}/p这里主请求和another-one各拉一次随机事实模板里分别渲染。几个要点subrequest 支持与主请求相同的几乎所有属性headers、parameters、method等唯一不能再嵌套的就是subrequests本身。(.Subrequest key)写起来比较啰嗦可以先赋给变量template: | {{ $anotherOne : .Subrequest another-one }} p{{ $anotherOne.JSON.String text }}/psubrequest 的.Response和主请求用法一致可以检查状态码template: | {{ $anotherOne : .Subrequest another-one }} p{{ $anotherOne.Response.StatusCode }}/p如果模板里写了一个没有定义的 key渲染会直接报错报错信息形如subrequest with key xxx has not been defined见 widget-custom-api.go看到这个提示先检查subrequests下的 key 和模板里.Subrequest ...的拼写是否一致。运行层面的行为源码 widget-custom-api.go只要存在 subrequests主请求与所有 subrequest 会并发执行其中一个失败时其余请求会被取消整个组件本次更新失败不会渲染出部分数据。用 newRequest 在模板内发起依赖上一次结果的请求这是 docs/custom-api.md 给出的链式调用示例主请求先拿到id再把这个 ID 拼进第二个请求的 URL- type: custom-api url: https://api.example.com/get-id-of-something template: | {{ $theID : .JSON.String id }} {{ $something : newRequest (concat https://api.example.com/something/ $theID) | withParameter key value | withHeader Authorization Bearer token | getResponse }} {{ $something.JSON.String title }}链式调用中每个环节的职责newRequest创建一个请求对象接收 URL。除文档示例中的concat拼 URL 外源码里它的第一个参数也支持 Go 的格式串写法后面的参数会经fmt.Sprintf代入见 widget-custom-api.go所以newRequest https://api.example.com/something/%s $theID这种写法同样可行。withParameter、withHeader可选给请求追加 query 参数和请求头。getResponse真正执行请求返回一个可以用.JSON和.Response读取的对象。因为getResponse的返回值和主请求、subrequest 一样都提供.JSON所以同样的模式可以连续套用——第二次请求的结果还能作为第三次请求的输入依次发起即可。getResponse的执行细节值得注意源码 widget-custom-api.go如果这次请求本身出错网络失败、响应不是合法 JSON 等它不会中断模板而是返回一个状态不正常的响应对象并把错误信息放在.Response.Status里同时把Could not fetch response within custom API template记入服务端日志。也就是说模板里的状态码检查分支就是为这种情况准备的。省略 url把请求完全放在模板里当目标 URL 需要动态参数时可以不在 YAML 里写url整个请求都从模板内发出。文档示例是拉取最近 24 小时的事件- type: custom-api title: Events from the last 24h template: | {{ $events : newRequest https://api.example.com/events | withParameter after (offsetNow -24h | formatTime rfc3339) | getResponse }} {{ if eq $events.Response.StatusCode 200 }} {{ range $events.JSON.Array events }} div{{ .String title }}/div div {{ .String date | parseTime rfc3339 | toRelativeTime }}/div {{ end }} {{ else }} pFailed to fetch data: {{ $events.Response.Status }}/p {{ end }}这里有几点约束文档明确提醒走这条路径时必须手动检查状态码上例的{{ if eq $events.Response.StatusCode 200 }}分支就是检查方式失败分支里通过{{ $events.Response.Status }}展示错误。offsetNow的 offset 参数必须形如3h、-1h或2h30m10sformatTime的 layout 参数与parseTime相同可直接用rfc3339。省略url时主请求本身没有响应数据源码中 URL 为空会返回空的 JSON 结果见 widget-custom-api.go所以模板里不要再去读主上下文.JSON的字段一切数据都来自getResponse的返回值。验证配置是否生效保存glance.yml后 Glance 会自动重新加载配置无需重启。若新配置有错控制台会输出错误Glance 继续用旧配置运行把错误修掉后新配置才会加载见 docs/configuration.md。渲染结果落在浏览器里对应组件的位置上链式调用成功时应看到第二个 API 的数据失败时会看到你模板里写的失败分支文案如Failed to fetch data: ...。需要排查但又不想反复打真实 API 时源码中还有一个mock-response字段CustomAPIRequest上的yaml:mock-response见 widget-custom-api.go设置后该请求不发起真实网络调用直接用你给的 JSON 字符串作为响应状态码视为 200。注意这个字段没有出现在文档的属性表中是从源码确认的。限制subrequests 之间是并发的彼此无法传递数据有顺序依赖一律用模板内newRequest。subrequest 不能嵌套subrequests。模板内请求没有默认的状态码兜底检查逻辑要自己写请求失败时组件不会崩但你会在失败分支里看到结果服务端日志里同时留有Could not fetch response within custom API template记录可供对照。配置里如需填 token 一类敏感值headers 的取值支持${ENV_VAR}环境变量语法见 docs/configuration.md避免把密钥明文写进glance.yml。【免费下载链接】glanceA self-hosted dashboard that puts all your feeds in one place项目地址: https://gitcode.com/GitHub_Trending/gla/glance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考