Xlink IoT Agent

通过基于签名的认证方式，使用GatewayAppClient控制和查询XLink IoT平台上的物联网设备及事件。

使用场景

✅ 适用场景

• - 查询XLink IoT平台上的设备状态和统计数据
• 监控设备告警和事件
• 批量查询设备属性（最新值或历史数据）
• 远程控制物联网设备（调用物模型服务）
• 按项目/产品筛选设备数据

❌ 不适用场景

• - 其他物联网平台（AWS IoT、Azure IoT、阿里云IoT等）
• 直接本地设备控制（不通过XLink IoT平台）
• 历史天气数据或恶劣天气预警（请使用天气技能）
• 非物联网相关的设备管理任务

---

快速开始

1. 设置环境变量

bash
export XLINKBASEURL=https://api-gw.xlink.cn
export XLINKAPPID=your-app-id
export XLINKAPPSECRET=your-app-secret
export XLINKAPIGROUP=your-group-id

2. 运行命令

bash
cd /path/to/xlink-iot-agent

设备概览

python scripts/xlink_api.py overview

待处理事件

python scripts/xlink_api.py event-instances --status 1 --limit 20

告警统计（最近24小时）

python scripts/xlink_api.py alert-statistics

设备控制

python scripts/xlink_api.py device-control \ --thing-id 10299402 \ --service deviceattributeset_service \ --input {PowerSwitch:true}

---

核心命令

命令	功能	示例
overview	设备概览统计	python scripts/xlinkapi.py overview
device-list

设备列表查询 | python scripts/xlinkapi.py device-list --limit 20 | | device-trend | 设备统计趋势 | python scripts/xlink_api.py device-trend --start-time 2026-03-17T00:00 --end-time 2026-03-24T23:59 | | device-history | 设备属性历史快照 | python scripts/xlink_api.py device-history --device-ids 300513220,501548135 | | device-latest | 设备最新属性 | python scripts/xlink_api.py device-latest --device-ids 300513220,501548135 | | device-control | 设备控制 | python scripts/xlinkapi.py device-control --thing-id 10299402 --service deviceattributesetservice --input {PowerSwitch:true} | | alert-overview | 告警概览 | python scripts/xlink_api.py alert-overview | | alert-statistics | 告警时序统计 | python scripts/xlink_api.py alert-statistics --interval hour | | event-instances | 事件实例查询 | python scripts/xlink_api.py event-instances --status 1 --limit 20 |

---

常见查询示例

设备概览

bash
python scripts/xlink_api.py overview

输出：

==================================================
📊 XLINK 设备概览
==================================================

📱 设备总数： 7823
🟢 在线： 143 (1.8%)
✅ 已激活： 6756 (86.4%)
⚫ 离线： 7680
⏸️ 未激活： 1067

待处理事件

bash
python scripts/xlink_api.py event-instances --status 1 --limit 20

告警概览

bash
python scripts/xlink_api.py alert-overview

设备列表（带筛选）

bash

按项目筛选

python scripts/xlink_api.py device-list \
--query {logic:AND,device:{project_id:{$eq:XJA1JJAJA}}} \
--limit 20

JSON输出

python scripts/xlink_api.py device-list --limit 20 --json

设备控制

bash

设置属性

python scripts/xlink_api.py device-control \
--thing-id 10299402 \
--service deviceattributeset_service \
--input {ColorTemperature: 8}

带命令缓存（10分钟）

python scripts/xlink_api.py device-control \ --thing-id 10299402 \ --service deviceattributeset_service \ --input {Brightness: 100} \ --ttl 600

控制响应码：

代码	说明
200	✅ 成功 - 设备已响应
202

⏸️ 设备离线 - 命令未发送 |
| 408 | ⚠️ 连接断开 - 设备休眠中 |
| 503 | ❌ 控制失败 |

---

Python API

python
import sys
sys.path.insert(0, scripts)
from xlink_api import XlinkIoTClient

初始化（从环境变量读取）

client = XlinkIoTClient()

设备概览

overview = client.getdeviceoverview(project_id=ab582)

设备列表

devices = client.getdevicelist(limit=50)

告警统计

alerts = client.getalertstatistics(interval=hour)

事件实例

events = client.geteventinstances(status=[1], limit=20)

设备控制

result = client.control_device( thing_id=10299402, service=deviceattributeset_service, input_params={PowerSwitch: True} )

---

详细文档

完整的CLI命令参考、参数说明和API文档：

• - references/cli-reference.md - 完整的CLI命令参考
• references/api-auth.md - 认证机制与安全
• references/api-doc.md - 完整的API文档
• references/response-schema.md - 响应格式定义

---

错误处理

状态码	说明	解决方案
401 Unauthorized	认证无效	检查App ID/Secret
403 Forbidden

访问被拒绝 | 验证Group ID和权限 | | 404 Not Found | 资源未找到 | 检查端点路径或资源ID | | 429 Too Many Requests | 请求频率限制 | 实现指数退避重试 | | 500 Server Error | 服务器错误 | 稍后重试 |

---

最佳实践

1. 1. 使用分页 - 对于大数据集，使用--offset和--limit
2. 尽早筛选 - 应用筛选条件（状态、设备、时间）以减少数据传输
3. 缓存结果 - 设备状态变化不频繁，可缓存30-60秒
4. 处理频率限制 - 对429错误实现指数退避
5. 脚本使用JSON输出 - 使用--json进行程序化解析
6. 调试模式 - 使用--debug进行故障排查