WebThings Gateway API开发指南：如何通过RESTful接口集成第三方应用

WebThings Gateway API开发指南：如何通过RESTful接口集成第三方应用

【免费下载链接】gatewayWebThings Gateway - a self-hosted web application for monitoring and controlling a building over the web项目地址: https://gitcode.com/gh_mirrors/gat/gateway

WebThings Gateway是一个开源的自托管物联网网关，允许您通过RESTful API监控和控制连接的设备。本文将为您提供完整的WebThings Gateway API开发指南，帮助您快速掌握如何通过API集成第三方应用，实现智能家居自动化控制。无论您是开发者还是物联网爱好者，本指南都将为您提供实用的技术指导。

📋 WebThings Gateway API概述

WebThings Gateway提供了一套完整的RESTful API接口，支持对设备、属性、动作和事件的管理。API基于HTTP/HTTPS协议，使用JSON格式进行数据交换，支持WebSocket实时通信。

核心API端点

WebThings Gateway的主要API端点位于/api路径下，包括：

• 设备管理：/api/things- 获取和管理连接的物联网设备
• 属性操作：/api/things/{thingId}/properties- 读取和设置设备属性
• 动作执行：/api/things/{thingId}/actions- 触发设备动作
• 事件订阅：/api/things/{thingId}/events- 订阅设备事件
• 规则管理：/api/rules- 创建和管理自动化规则
• 插件管理：/api/addons- 管理网关插件和适配器

🚀 快速开始：API认证与基础调用

1. 获取访问令牌

在调用API之前，您需要获取访问令牌。WebThings Gateway支持JWT（JSON Web Token）认证：

# 获取访问令牌 curl -X POST https://your-gateway.local/api/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"your-password"}'

2. 基础API调用示例

使用获取的令牌进行API调用：

# 获取所有设备列表 curl -X GET https://your-gateway.local/api/things \ -H "Authorization: Bearer YOUR_TOKEN" # 获取特定设备信息 curl -X GET https://your-gateway.local/api/things/light-1 \ -H "Authorization: Bearer YOUR_TOKEN"

🔌 设备管理API详解

发现新设备

WebThings Gateway支持自动发现新设备：

# 开始设备发现 curl -X POST https://your-gateway.local/api/new_things \ -H "Authorization: Bearer YOUR_TOKEN" # 获取已发现的设备 curl -X GET https://your-gateway.local/api/new_things \ -H "Authorization: Bearer YOUR_TOKEN"

设备属性操作

设备属性是物联网设备的核心状态值，如温度、亮度、开关状态等：

# 获取设备所有属性 curl -X GET https://your-gateway.local/api/things/thermostat-1/properties \ -H "Authorization: Bearer YOUR_TOKEN" # 设置设备属性 curl -X PUT https://your-gateway.local/api/things/light-1/properties/on \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"on": true}'

⚡ 实时通信：WebSocket API

对于需要实时更新的应用场景，WebThings Gateway提供了WebSocket API：

// WebSocket连接示例 const ws = new WebSocket('wss://your-gateway.local/api/things/ws'); ws.onopen = () => { // 订阅设备属性更新 ws.send(JSON.stringify({ messageType: 'addEventSubscription', data: { 'light-1': {} } })); }; ws.onmessage = (event) => { const data = JSON.parse(event.data); console.log('收到设备更新:', data); };

🎯 规则引擎API

WebThings Gateway内置了强大的规则引擎，支持创建复杂的自动化规则：

创建自动化规则

# 创建温度触发规则 curl -X POST https://your-gateway.local/api/rules \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "温度过高自动开空调", "enabled": true, "trigger": { "property": { "thing": "thermostat-1", "name": "temperature" }, "type": "LevelTrigger", "level": 28, "operator": "gt" }, "effect": { "type": "SetEffect", "property": { "thing": "ac-1", "name": "on" }, "value": true } }'

📊 事件与日志API

设备事件订阅

# 订阅设备事件 curl -X POST https://your-gateway.local/api/things/motion-sensor-1/events \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "motion", "data": {} }'

系统日志查询

# 获取系统日志 curl -X GET https://your-gateway.local/api/logs \ -H "Authorization: Bearer YOUR_TOKEN" # 获取内部调试日志 curl -X GET https://your-gateway.local/api/internal-logs \ -H "Authorization: Bearer YOUR_TOKEN"

🔧 高级功能：插件与扩展API

插件管理

WebThings Gateway支持通过插件扩展功能：

# 获取已安装插件列表 curl -X GET https://your-gateway.local/api/addons \ -H "Authorization: Bearer YOUR_TOKEN" # 安装新插件 curl -X POST https://your-gateway.local/api/addons \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/addon.zip", "manifest": { "name": "custom-adapter", "version": "1.0.0" } }'

OAuth客户端管理

对于需要第三方集成的应用，可以使用OAuth API：

# 创建OAuth客户端 curl -X POST https://your-gateway.local/api/oauth/clients \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Mobile App", "description": "移动应用客户端", "redirect_uri": "https://app.example.com/callback" }'

🛠️ 最佳实践与注意事项

1. 错误处理

所有API调用都应包含适当的错误处理：

try { const response = await fetch('/api/things', { headers: { 'Authorization': `Bearer ${token}` } }); if (!response.ok) { const error = await response.json(); console.error('API错误:', error); } } catch (error) { console.error('网络错误:', error); }

2. 性能优化

• 使用WebSocket进行实时更新，减少HTTP轮询
• 批量获取设备信息，减少API调用次数
• 合理设置缓存策略

3. 安全建议

• 使用HTTPS保护数据传输
• 定期更新访问令牌
• 限制API访问权限
• 监控API调用频率

📁 相关源码文件

如果您需要深入了解API实现细节，可以参考以下源码文件：

• API路由配置：src/router.ts - 主要API路由配置
• 设备控制器：src/controllers/things_controller.ts - 设备管理API实现
• 规则控制器：src/controllers/rules_controller.ts - 规则管理API
• 动作控制器：src/controllers/actions_controller.ts - 动作执行API
• 事件控制器：src/controllers/events_controller.ts - 事件管理API

🎉 结语

通过本文的WebThings Gateway API开发指南，您应该已经掌握了如何通过RESTful接口集成第三方应用。无论是构建移动应用、Web界面还是自动化脚本，WebThings Gateway都提供了强大而灵活的API支持。

记住，良好的API设计是成功集成的关键。始终遵循最佳实践，确保您的应用安全、高效地与WebThings Gateway交互。现在就开始您的物联网开发之旅吧！

提示：在实际开发中，建议先使用API测试工具（如Postman或curl）验证API调用，然后再集成到您的应用中。

【免费下载链接】gatewayWebThings Gateway - a self-hosted web application for monitoring and controlling a building over the web项目地址: https://gitcode.com/gh_mirrors/gat/gateway