Hyperion.ng项目JSON API命令详解与技术指南

Hyperion.ng项目JSON API命令详解与技术指南

hyperion.ng The successor to Hyperion aka Hyperion Next Generation 项目地址: https://gitcode.com/gh_mirrors/hy/hyperion.ng

前言

Hyperion.ng作为一款开源的LED环境照明控制软件，其JSON API提供了丰富的控制接口。本文将全面解析这些API命令的使用方法、权限要求以及适用场景，帮助开发者更好地集成和使用Hyperion.ng。

API命令分类解析

1. 授权管理类命令

授权管理是API安全的基础，主要包含以下功能：

• 登录/登出：基础身份验证功能
• 令牌管理：创建、删除、重命名访问令牌
• 密码修改：管理员可重置用户密码
• 请求处理：处理待授权的令牌请求

权限说明：

• 大部分授权操作需要管理员权限
• 登录和令牌请求是少数不需要认证的操作

2. 实例控制类命令

实例是Hyperion.ng的核心概念，相关命令包括：

• 生命周期管理：创建、启动、停止实例
• 实例切换：在不同实例间快速切换
• 数据获取：获取LED快照、图像快照等实例数据

技术要点：

• 部分命令可同时操作多个实例
• 某些操作要求目标实例必须处于运行状态

3. LED控制类命令

直接控制LED的核心功能：

• 颜色控制：设置单色显示
• 效果控制：应用预定义或自定义效果
• 图像流处理：实时图像流处理
• 清屏操作：清除当前LED显示

使用建议：

• 多数命令支持多实例同时操作
• 图像流相关命令仅支持WebSocket连接

4. 配置管理类命令

系统配置相关操作：

• 配置获取/设置：读写系统配置
• 配置重载：动态加载配置变更
• 配置恢复：回滚到默认配置

安全提示：

• 所有配置操作都需要管理员权限
• 配置变更可能影响系统稳定性

5. 系统信息类命令

获取系统状态信息：

• 服务器信息：获取运行状态
• 系统信息：获取硬件和软件信息
• 订阅更新：实时获取状态变更

高级功能：

• 支持多种订阅类型
• 可针对特定实例订阅更新

订阅更新机制详解

Hyperion.ng提供了强大的订阅机制，允许客户端实时获取系统状态变更。主要订阅类型包括：

1. 调整更新：颜色调整参数变更
2. 组件更新：组件状态变化
3. 效果更新：效果列表变更
4. LED映射更新：图像到LED的映射关系变化
5. 优先级更新：LED优先级队列变化

订阅特点：

• 多数订阅支持"all"通配符
• 部分订阅是实例特定的
• 更新通过WebSocket推送

最佳实践建议

1. 权限管理：

   • 生产环境务必启用授权
   • 合理分配管理员权限
   • 定期轮换访问令牌

2. 实例操作：

   • 操作前检查实例状态
   • 批量操作时注意性能影响
   • 重要变更前备份配置

3. 实时控制：

   • 优先使用WebSocket连接
   • 合理设置订阅频率
   • 处理异常断开情况

4. 错误处理：

   • 检查命令返回值
   • 处理权限不足情况
   • 记录操作日志

总结

Hyperion.ng的JSON API提供了从基础控制到高级管理的完整接口集。理解这些命令的分类、权限要求和适用场景，可以帮助开发者构建更稳定、更安全的集成方案。在实际应用中，建议根据具体需求选择合适的命令组合，并遵循最佳实践以确保系统稳定运行。

hyperion.ng The successor to Hyperion aka Hyperion Next Generation 项目地址: https://gitcode.com/gh_mirrors/hy/hyperion.ng