文件管理协议

最近更新时间：2023-11-03 10:39:41
我的收藏
本页目录：

功能概述
文件管理功能是用于厂商去完成设备端、平台侧与应用端间的文件互传，用于存储设备量产后用户在使用设备过程中所需文件，由于该部分文件权限不归属于设备厂商查看管理，因此由服务端文件管理 topic 消息通道进行实现。
应用场景举例：
用户在小程序端录音，需下发到设备端进行播报。
门禁摄像头在有人来访时，拍取来访人照片，在小程序端进行查看。
实现此类功能需利用如下两个 Topic：
数据上行 Topic（用于发布）：$thing/up/service/${productid}/${devicename}。
数据下行 Topic（用于订阅）：$thing/down/service/${productid}/${devicename}。
设备文件版本信息上报
1. 设备上报当前文件版本信息，设备端通过 MQTT 协议发布一条消息到 $thing/up/service/${productid}/${devicename}，进行版本号的上报，消息为 json 格式，内容如下：
{
    "method": "report_version",
    "request_id": "12345678",
    "report":{"resource_name": "123.wav", "version": "1.0.0", "resource_type": "FILE"}
}
//method：消息类型
//resource_name: 文件名称
//version：文件版本号
//resource_type： 文件类型，固件（fw）、文件（file）
//后台逻辑: 接收消息，并将文件的版本信息更新到对应产品/设备的
特别的，若上报的文件列表为空，则云端会回复云端记录的设备的所有文件列表，设备端可基于此特性，实现设备端文件列表的异常恢复操作。
{
    "method": "report_version",
    "report":{
        "resource_list":[]       
     }
}
2. 服务端收到文件版本信息上报后，服务端通过 $thing/down/service/${productid}/${devicename}，向设备端回复收到的版本信息，消息为 json 格式，内容如下：
{
    "method": "report_version_rsp",
    "result_code":0,
    "result_msg":"success",
    "resource_list":[
        {"resource_name": "audio_woman_mandarin", "version": "1.0.0"，"resource_type": "FILE"},
        {"resource_name": "audio_woman_sichuanhua", "version": "2.0.0"，"resource_type": "FILE"}
    ]   
}
//method：消息类型
//result_code: 版本上报结果
//result_msg：版本上报结果信息
//resource_list: 将收到的版本信息回送过来
//若设备端上报的resource_list为空，则服务端回应已记录的资源列表
设备文件下载
1. 用户在小程序端使用时调用应用端 API 上传文件，创建文件下载任务。
2. 设备端会通过订阅的 $thing/down/service/${productid}/${devicename} 接收文件的更新消息，文件更新消息内容如下：
{
    "method": "update_resource",
    "resource_name": "audio_woman_sichuanhua",
    "resource_type": "FILE",
    "version": "1.0.0",
    "url": "https://ota-1254092559.cos.ap-guangzhou.myqcloud.com",
    "md5sum": "cc03e747a6afbbcbf8be7668acfebee5",
    "file_size": 31242
}
// method：消息类型
// resource_name：文件名称
// resource_type：固件（fw）、文件（file），控制台下拉选择
// version：升级版本
// url：下载文件的url
// md5asum：文件的MD5值
// file_size：文件大小，单位为字节
3. 设备在收到文件更新的消息后，根据 URL 下载资源，下载的过程中设备 SDK 会通过 $thing/up/service/${productid}/${devicename} 不断的上报下载进度，上报的内容如下：
{
    "method": "report_progress",
    "report":{
        "progress": {
            "resource_name": "audio_woman_sichuanhua",
            "state":"downloading",
            "percent":"10",
            "result_code":"0",
            "result_msg":""
        },
      "version": "1.0.0"
    }
}
// method：消息类型
//resource_name:正在下载的文件名称
// state：状态为正在下载中
// percent：当前下载进度，百分比
4. 当设备完成文件下载，设备需要通过 $thing/up/service/${productid}/${devicename} 上报一条下载的结果，内容如下：
//下载成功
{
    "method": "report_result",
    "report":{
        "progress":{
            "resource_name": "audio_woman_sichuanhua",
            "state":"done",
            "result_code":"0",
            "result_msg":"success"
        },
     "version": "1.0.0"
    }
}
// method：消息类型
// state：状态下载结束
// result_code: 下载结果，0成功，非0失败
// result_msg: 失败情况的具体描述信息
设备文件上传
1. 设备请求文件上传的 URL，设备端通过 MQTT 协议发布一条消息到 $thing/up/service/${productid}/${devicename}，请求文件上传的URL，消息为 json 格式，内容如下：
{
    "method": "request_url",
    "request_id": "12345678",
    "report":{"resource_name": "123.wav", "version": "1.0.0", "resource_type": "AUDIO"}
}
//method：消息类型
//resource_name: 文件名称
//version：文件版本号
//resource_type： 文件类型
2. 服务端收到文件版本信息上报后，服务端通过 Topic $thing/down/service/${productid}/${devicename} 向设备端返回已完成预签名的 cos url，消息为 json 格式，内容如下：
{
    "method": "request_url_resp",
    "result_code":0,
    "result_msg":"success",
    "resource_url": "presigned_url_xxx",
    "resource_token": "123456abcdef",
    "request_id": "12345678"
}
//method：消息类型
//result_code: 版本上报结果
//result_msg：版本上报结果信息
//resource_url: cos 预签名 url
//resource_token：文件token，后续可以根据token映射资源url
3. 设备将资源 put 到对应的 cos url，上传结束后，上报上传结果，消息为 json 格式，内容如下：
{
    "method": "report_post_result",
    "report":{
        "progress":{
            "resource_token": "123456abcdef",
            "state":"done",
            "result_code":"0",
            "result_msg":"success"
        },
    }
}
//method：消息类型
//resource_name: 文件名称
//state：上传结果
//result_code: 上传结果错误码，0成功
//result_msg: 上传结果信息
//version：文件版本
﻿
文件删除
1. 设备端会通过订阅的 Topic $thing/down/service/${productID/${deviceName} 接收文件的删除消息，文件删除消息内容如下：
{
    "method": "del_resource",
    "resource_name": "audio_woman_sichuanhua",
    "resource_type": "FILE",
    "version": "1.0.0"
}
// method：消息类型为
// resource_name：文件名称
2. 当设备完成文件下载，设备需要通过 Topic $thing/up/service/${productID/${deviceName}上报一条删除的结果，特别的，若待删除的文件在设备端不存在(设备端刷机导致丢失等)，建议回复删除成功，否则此文件在设备端和云端的记录一直不一致，内容如下：
{
    "method": "del_result",
    "report":{
        "progress":{
            "resource_name": "audio_woman_sichuanhua",
            "state":"done",
            "result_code":"0",
            "result_msg":"success"
        },
    "version": "1.0.0"
    }
}
// method：消息类型
// state：删除结束
// result_code: 删除结果，0成功，非0失败
// result_msg: 失败情况的具体描述信息
﻿
﻿
上一篇: 资源管理协议下一篇: SDK 说明及下载