用途:本技能面向 Terra API Streaming(实时)API,用于从可穿戴设备获取实时、约每秒级的生物特征数据,通过 WebSocket 传输。适用于构建实时流式应用,而非获取已完成训练、睡眠、每日汇总等长时段数据(那些属于 Unified API)。
主要能力:实时流式架构由四部分组成——可穿戴设备(BLE/ANT+ 广播)、生产者(运行 Terra RT SDK 的移动应用)、Terra API WebSocket 代理(Terra 托管)、消费者(你的后端)。需建立三条连接:设备到应用、应用到代理、代理到后端。RT SDK 支持十七种 DataTypes,涵盖心率、HRV、RR 间期、ECG、步数、步频、距离、速度、爬楼层数、活动、骑行功率、加速度、陀螺仪、卡路里、MET、位置等。
使用方式:新应用可从示例起步,运行 terra examples list --select name,title,description 与 terra examples clone streaming-mobile-app my-app(无需登录)。CLI 缺失时可安装:macOS/Linux 用 curl -fsSL https://cli.tryterra.co/install.sh | sh,Windows PowerShell 用 irm "https://cli.tryterra.co/install.ps1" | iex。聊天助手无法运行 CLI 时,可让用户在终端执行或参考示例源码。账户层检查可用 terra environments list、terra data-tokens list、terra users list、terra unified-api sources list 等只读命令。WebSocket 端点为 wss://ws.tryterra.co/connect,IDENTIFY 的 type 字段决定角色(0 生产者,1 消费者)。
限制与要点:令牌均为一次性,IDENTIFY 成功后即删除,重连需重新铸造;手机注册令牌 3 分钟过期,须即时铸造。连接后 15 秒内须 IDENTIFY,否则以 4000 关闭;心跳缺失以 4005 关闭。关闭码 4000/4003/4004/1003 属客户端缺陷,不应盲目重试;4001 需重新铸造令牌;4002 为消费者会话上限。seq 单调但稀疏,间隙正常。REPLAY 需同时提供 after 与 before,且回放有几秒延迟。请求某数据类型不等于能收到,设备广播决定实际数据。可在仪表盘创建测试用户,用合成数据端到端验证。Apple Watch 非训练时段频率降低。平台设置与完整消费者协议见 references/。