管理 REST API

• Swagger UI
• JWT Token
• 控制器概览

Swagger UI

安装TBMQ后，可使用Swagger UI浏览REST API。

通过以下URL访问Swagger UI：

1
http(s)://YOUR_HOST:PORT/swagger-ui/

本地安装请使用以下URL：

1
http://localhost:8083/swagger-ui/

该URL提供交互界面，用于浏览和使用TBMQ的REST API端点。 使用Swagger UI可便捷地探索功能、测试API调用并获取TBMQ提供的服务端API信息。

若您已在主登录页完成授权，文档页将自动使用您的凭证， 无需额外认证即可无缝访问文档。

若需手动授权或使用不同凭证，可点击文档页右上角的”Authorize”按钮。 该按钮用于提供认证信息并以所需权限完成授权。

使用”Authorize”按钮可灵活地以不同用户身份认证，根据授权级别访问文档中的相应部分。

JWT Token

TBMQ使用 JWT（JSON Web Tokens）在API客户端（如浏览器和脚本）与平台之间安全表示声明。 JWT token用于安全交换信息的机制。

登录broker时，用户名和密码将换得一对token。这些JWT形式的token封装了用户认证与授权所需的必要信息， 确保凭证安全传输，并允许API客户端与平台安全通信，同时维护所交换信息的完整性和机密性。

主token为短效token，用于执行API调用。主token过期后，refresh token用于获取新的主token。 主token和refresh token的过期时间可在系统设置中配置，通过JWT_TOKEN_EXPIRATION_TIME和JWT_REFRESH_TOKEN_EXPIRATION_TIME参数。默认过期时间分别为2.5小时和1周。

参见以下示例命令，为用户”sysadmin@thingsboard.org”、密码”sysadmin”及服务器”THINGSBOARD_MQTT_BROKER_URL”获取token：

1
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"username":"sysadmin@thingsboard.org", "password":"sysadmin"}' 'http://THINGSBOARD_MQTT_BROKER_URL/api/auth/login'

1
{"token":"$YOUR_JWT_TOKEN", "refreshToken":"$YOUR_JWT_REFRESH_TOKEN"}

将X-Authorization请求头设置为Bearer $YOUR_JWT_TOKEN。请确保使用主JWT token，而非refresh token。

控制器概览

• Admin Controller：用于查看、创建或删除管理员用户。
• App Controller：用于broker状态的高级监控与控制。
• App Shared Subscription Controller：用于查看、创建或删除Application共享订阅。
• Auth Controller：用于查看当前用户信息及修改密码。
• Client Session Controller：用于查看Client Session信息、断开连接并清除它们。
• Login Endpoint：用于用户认证及获取JWT token数据。
• MQTT Client Credentials Controller：用于查看、创建或删除MQTT客户端凭证。
• Retained Msg Controller：用于查看主题保留消息信息，并强制清理存储保留消息的数据结构。
• Subscription Controller：用于查看Client订阅信息，并强制清理存储订阅的数据结构。
• Time series Controller：用于获取和删除历史统计数据。
• Unauthorized Client Controller：用于获取和删除系统中的未授权客户端。
• WebSocket Connection Controller：用于为WebSocket客户端创建、获取和删除WebSocket连接。
• WebSocket Subscription Controller：用于为WebSocket客户端创建、获取和删除WebSocket订阅。