设备播放语音

设备告警音频上传接口文档（设备端对接）

1. 接口信息

• 接口名称: 告警音频文件上传
• 真实路径: /api/sys/uploadAlarmFile
• 方法: POST
• Content-Type: multipart/form-data
• 调用方: 服务端内部转发

2. 适用对象

本文档给设备端或固件端对接人员使用。

你需要关注设备最终收到的 HTTP 请求格式、查询参数、文件字段和响应约定。

3. 功能说明

设备接收服务端转发的告警音频文件，并根据查询参数中的 command 执行业务逻辑。

4. 最终请求地址格式

服务端会根据 deviceId 拼接设备地址，并自动附加签名参数。

最终请求格式如下:

[http://{deviceHost}/api/sys/uploadAlarmFile?from=media&name=feeder_speaker_audio.wav&command=alarmAudioFile](http://{deviceHost}/api/sys/uploadAlarmFile?from=media&name=feeder_speaker_audio.wav&command=alarmAudioFile)'/media/feeder_speaker_audio.wav'{times}&t={ts}&token=cloud_{sign}

5. 查询参数

6. multipart 请求体

6.1 文件字段

6.2 当前实现细节

• 文件表单字段名固定为 file。
• 当前服务端转发时，文件名固定为 feeder_speaker_audio.wav。
• 当前 command 生成格式为:

alarmAudioFile'/media/feeder_speaker_audio.wav'{times}

其中 times 为服务端收到的播放次数参数，默认值为 1。

7. 响应约定

服务端会透传设备返回的 HTTP 状态码和响应体，因此设备应直接返回业务结果。

成功响应示例:

{
  "code": 0,
  "msg": "ok"
}

建议失败响应示例:

{
  "code": 1001,
  "msg": "upload failed"
}

8. 签名与调用说明

• 设备端无需关心上层用户 JWT。
• 设备端只需要校验服务端附加的业务查询参数与签名参数。
• t 和 token 由服务端生成。
• 服务端当前超时时间为 200 秒。

9. 代码位置

• 设备侧调用封装: internal/clouds/cloud_request.go
• 服务端入口: internal/handler/device_handler.go