播放语音文件上传

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

概览

• 基础路径: /api
• 接口名称: 设备告警音频上传
• 路径: /api/device/upload/alarm-file
• 方法: POST
• Content-Type: multipart/form-data
• 鉴权方式: 请求头 X-Token
• 处理函数: deviceH.UploadAlarmFile

鉴权头

通用鉴权失败响应

{
  "code": 401,
  "msg": "未登录或登录过期",
  "data": null
}

{
  "code": 401,
  "msg": "登录已过期，请重新登录",
  "data": null
}

2. 适用对象

本文档给服务端接口调用方或 App/H5/管理后台对接人员使用。

你只需要调用服务端接口，不需要直接请求设备本地地址，也不需要自己生成设备签名参数。

3. 功能说明

客户端上传一个音频文件，由服务端转发到指定设备的告警音频上传接口。

服务端会读取上传文件流，并以 multipart/form-data 方式透传给设备，不会先落盘到本地。

4. 请求参数

请求体使用 multipart/form-data。

5. 请求示例

curl --request POST "http://localhost:8080/api/device/upload/alarm-file" \
  --header "X-Token: <token>" \
  --form "deviceId=dev_001" \
  --form "times=3" \
  --form "file=@./alarm.wav"

6. 参数校验规则

• deviceId 不能为空。
• times 不传时默认值为 1。
• file 必须上传。

7. 响应说明

该接口会透传设备响应内容和 HTTP 状态码。

7.1 成功响应示例

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

7.2 常见失败响应

参数缺失:

{
  "code": 400,
  "msg": "deviceId 不能为空",
  "data": null
}

times 非法:

{
  "code": 400,
  "msg": "times 必须是整数",
  "data": null
}

文件缺失:

{
  "code": 400,
  "msg": "请上传文件",
  "data": null
}

设备连接失败时，服务端返回 502，并附带错误消息。

8. 对接说明

• 调用方只需要关心服务端接口 /api/device/upload/alarm-file。
• 设备真实地址、签名参数 t 和 token 均由服务端自动处理。
• 当前实现中，times 会参与设备端 command 的最终拼接。

9. 代码位置

• 路由注册: cmd/main.go
• 处理函数: internal/handler/device_handler.go
• 转发逻辑: internal/clouds/cloud_request.go

10. 设备端实现参考

本站文档中心