Speedtest-Tracker API 数据格式变更解析与HomeAssistant集成方案

背景介绍

Speedtest-Tracker是一款用于监控网络连接状态的实用工具，它通过定期执行Speedtest测试来记录网络性能指标。近期该项目进行了API的重大更新，从旧版API迁移到了新版v1 API，这给使用旧版API集成的用户（如HomeAssistant用户）带来了一些适配需求。

API数据格式对比

旧版API特点

旧版API直接返回经过转换的"人类友好"数据格式，例如：

• 下载/上传速度以Mbps为单位
• 服务器信息直接平铺在数据结构中
• 结果URL直接可访问

新版API改进

新版API采用了更规范的数据结构：

1. 原始数据保留：保持从Ookla Speedtest CLI获取的原始字节数据
2. 结构化嵌套：服务器信息和测试结果分别放在独立对象中
3. 多种格式支持：同时提供原始字节、比特值及人类可读格式

关键变更点解析

1. 速度单位处理

新版API最大的变化是速度值的表示方式：

• download/upload：原始字节值(Byte)
• download_bits/upload_bits：转换为比特值(bit)
• download_bits_human/upload_bits_human：自动转换的最高量级格式(如Mbps)

这种设计保留了原始数据精度，同时提供多种转换选项，满足不同使用场景。

2. 服务器信息位置

服务器相关信息从原来的平铺结构改为嵌套在server对象中：

"server": {
    "id": 52365,
    "host": "speedtest.ams.t-mobile.nl",
    "name": "Odido",
    "location": "Amsterdam"
}

3. 测试结果信息

测试结果元数据现在位于result对象中：

"result": {
    "id": "a7570e25-REDACTED",
    "url": "https://www.speedtest.net/result/c/a7570e25-REDACTED"
}

HomeAssistant集成方案

对于使用HomeAssistant REST传感器的用户，需要调整配置以适应新版API：

1. 速度值转换：在value_template中进行单位转换
2. 属性路径调整：使用json_attributes_path指向正确的数据结构位置
3. 认证支持：新版API可能需要授权头部

示例配置

- platform: rest
  name: SpeedTest Download
  resource: http://[IP]:[PORT]/api/v1/results/latest
  headers: 
    Authorization: "Bearer YOUR_TOKEN"
  value_template: >
    {{ (value_json['data']['download_bits'] | float / 1000000) | round(2) }}
  json_attributes_path: "$.data.data"
  json_attributes:
    - "server"
    - "result"
  unit_of_measurement: Mb/s

配置说明

1. 单位转换：将比特值除以1000000转换为Mbps，保留2位小数
2. 属性访问：通过json_attributes_path正确指向嵌套的数据结构
3. 历史数据兼容：保持与旧版相同的单位(Mb/s)，确保历史数据连续性

最佳实践建议

1. 数据存储考虑：直接存储比特值可保持最大精度，便于后续分析
2. 显示优化：在前端展示时使用人类可读格式提升用户体验
3. 错误处理：增加API调用超时设置，避免因网络问题导致传感器不可用
4. 频率控制：合理设置scan_interval，平衡数据实时性和系统负载

通过以上调整，用户可以平滑过渡到新版API，同时保持监控系统的稳定性和数据连续性。这种结构化设计也为未来的功能扩展提供了更好的基础。