[关闭]
@soszrg 2019-06-19T01:52:49.000000Z 字数 8766 阅读 622

OTA接口文档（V3）

v3文档 v3前端接口 v3设备端文档

前端用OTA接口

固件上传（Token）

POST /v3/ota/files/

请求参数

参数名 类型 必须 说明
product string 是 产品ID
file_name string 是 文件名
file_url string 是 固件下载链接
size int 是 固件大小
md5 string 是 固件的md5
version string 否 用户定义的固件版本号
component string 否 用户定义的固件名称
description string 是 固件描述
extend json对象 否 扩展字段

字段说明

返回值

  1. {
  2.     "meta":{
  3.         "message":"固件创建成功",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "ofid":4,
  8.         "file_name":"a.bin",
  9.         "file_url":"https://test.com/a.bin",
  10.         "size":10,
  11.         "md5":"abcde...",
  12.         "version":1,
  13.         "component":"test",
  14.         "description":"bin file",
  15.         "extend":{"customize":1},
  16.         "product":"test01"
  17.     }
  18. }

错误码

错误代码 错误说明
10000 参数错误

获取某个产品的固件列表（Token）

GET /v3/ota/files/

请求参数

参数名 类型 必须 说明
product string 是 产品ID

返回值

  1. {
  2.     "meta":{
  3.         "message":"固件列表",
  4.         "code":0
  5.     },
  6.     "data":[
  7.         {
  8.             "ofid":5,
  9.             "file_name":"a.bin",
  10.             "file_url":"https://test.com/a.bin",
  11.             "size":10,
  12.             "md5":"aabbxx...",
  13.             "version":1,
  14.             "component":"test",
  15.             "upload_time":"2017-05-09T14:30:39.570000",
  16.             "description":"",
  17.             "extend":{
  18.                 "a":1
  19.             },
  20.             "product":"8d01f204150911e7a554fa163e876164"
  21.         },
  22.         {
  23.             "ofid":4,
  24.             "file_name":"a.bin",
  25.             "file_url":"https://test.com/a.bin",
  26.             "size":10,
  27.             "md5":"122aaa",
  28.             "version":2,
  29.             "component":"test",
  30.             "upload_time":"2017-05-09T14:30:20.511000",
  31.             "description":"",
  32.             "extend":{},
  33.             "product":"8d01f204150911e7a554fa163e876164"
  34.         }
  35.     ]
  36. }

错误码

错误代码 错误说明
29010 参数错误：缺少product参数

获取某类产品的固件列表（Token）

GET /v3/ota/files/

请求参数

参数名 类型 必须 说明
type int 是 产品类别：0→CP产品，1→IP产品，2→OTA产品

返回值

  1. {
  2.     "meta":{
  3.         "message":"固件列表",
  4.         "code":0
  5.     },
  6.     "data":[
  7.         {
  8.             "ofid":5,
  9.             "file_name":"a.bin",
  10.             "file_url":"https://test.com/a.bin",
  11.             "size":10,
  12.             "md5":"aabbxx...",
  13.             "version":1,
  14.             "component":"test",
  15.             "upload_time":"2017-05-09T14:30:39.570000",
  16.             "description":"",
  17.             "extend":{
  18.                 "a":1
  19.             },
  20.             "product":"8d01f204150911e7a554fa163e876164"
  21.         },
  22.         {
  23.             "ofid":4,
  24.             "file_name":"a.bin",
  25.             "file_url":"https://test.com/a.bin",
  26.             "size":10,
  27.             "md5":"122aaa",
  28.             "version":2,
  29.             "component":"test",
  30.             "upload_time":"2017-05-09T14:30:20.511000",
  31.             "description":"",
  32.             "extend":{},
  33.             "product":"8d01f204150911e7a554fa163e876164"
  34.         }
  35.     ]
  36. }

错误码

错误代码 错误说明
29010 参数错误：缺少product参数

单个固件信息（Token）

GET /v3/ota/files/<ofid>/

请求参数

参数名 类型 必须 说明
ofid int 是 固件ID

返回值

  1. {
  2.     "ofid":2,
  3.     "file_name":"1",
  4.     "file_url":"upload_time",
  5.     "size":1,
  6.     "md5":"1",
  7.     "version":"1",
  8.     "component":"test",
  9.     "upload_time":"2017-05-07T19:58:17.817000",
  10.     "description":"1",
  11.     "customize":"",
  12.     "extend":null,
  13.     "product":"8d01f204150911e7a554fa163e876164"
  14. }

错误码

错误代码 错误说明
10000 参数错误：参考Response中的message

创建OTA任务（Token）

POST /v3/ota/tasks/

请求参数

参数名 类型 必须 说明
ota_files list 是 OTA文件ID list
status string 是 任务状态：测试，上线
onset_time string 是 任务起效时间
description string 否 任务描述
is_fog int 否 是否为fog产品
notify_type int 否 通知类型
ug_type int 否 升级类型
ug_range int 否 升级范围类型
version_range int 否 要升级的版本范围
area_range string 否 要升级的设备所在的地域
mac_range string 否 要升级的MAC地址范围
extend string 否 扩展字段

返回值

  1. {
  2.     "meta":{
  3.         "message":"ota file info",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "ofid":8,
  8.         "file_name":"a.bin",
  9.         "file_url":"https://test.com/a.bin",
  10.         "size":10,
  11.         "md5":"122aaa",
  12.         "version":1,
  13.         "component":"test",
  14.         "description":"",
  15.         "extend":{},
  16.         "product":"test"
  17.     }
  18. }

错误码

错误代码 错误说明
10000 参数错误：缺少product参数

任务列表（Token）

GET /v3/ota/tasks/

请求参数

参数名 类型 必须 说明
ofid int 否 OTA文件ID list
product string 否 产品ID

说明

返回值

  1. {
  2.     "meta":{
  3.         "message":"",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "count":1,
  8.         "next":null,
  9.         "previous":null,
  10.         "results":[
  11.             {
  12.                 "otid":25,
  13.                 "product":{
  14.                     "productid":"8d01f204150911e7a554fa163e876164",
  15.                     "pname":"zrgtest033001"
  16.                 },
  17.                 "status":1,
  18.                 "onset_time":"2017-05-05T00:59:00",
  19.                 "description":"",
  20.                 "is_fog":1,
  21.                 "notify_type":1,
  22.                 "ug_type":1,
  23.                 "ug_range":0,
  24.                 "mac_range":[],
  25.                 "create_time":"2017-05-11T10:25:50.221000",
  26.                 "extend":null,
  27.                 "ota_files":[
  28.                     3,
  29.                     2
  30.                 ]
  31.             }
  32.         ]
  33.     }
  34. }

错误码

错误代码 错误说明
10000 参数错误：缺少product参数

单个任务信息（Token）

GET /v3/ota/tasks/<otid>/

请求参数

参数名 类型 必须 说明
otid int 是 任务ID

返回值

  1. {
  2.     "otid": 25,
  3.     "status": 1,
  4.     "onset_time": "2017-05-05T00:59:00",
  5.     "description": "",
  6.     "is_fog": 1,
  7.     "notify_type": 1,
  8.     "ug_type": 1,
  9.     "ug_range": 0,
  10.     "mac_range": [],
  11.     "create_time": "2017-05-11T10:25:50.221000",
  12.     "extend": null,
  13.     "product": "8d01f204150911e7a554fa163e876164",
  14.     "ota_files": [
  15.         3,
  16.         2
  17.     ]
  18. }

错误码

错误代码 错误说明
10000 参数错误：参考Response中的message

任务发布（Token）

PUT /v3/ota/tasks/<otid>/release/

请求参数

参数名 类型 必须 说明
otid int 是 任务ID

返回值

  1. {
  2.     "meta":{
  3.         "message":"发布成功",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "otid":27,
  8.         "product":{
  9.             "productid":"8d01f204150911e7a554fa163e876164",
  10.             "pname":"zrgtest033001"
  11.         },
  12.         "ota_files":[
  13.             {
  14.                 "ofid":3,
  15.                 "file_name":"1",
  16.                 "component":"test",
  17.                 "description":"1",
  18.                 "version":"1",
  19.                 "upload_time":"2017-05-07T19:58:17.817000"
  20.             },
  21.         ],
  22.         "status":1,
  23.         "onset_time":"2017-05-05T00:59:00",
  24.         "description":"",
  25.         "is_fog":1,
  26.         "notify_type":1,
  27.         "ug_type":1,
  28.         "ug_range":0,
  29.         "mac_range":[],
  30.         "create_time":"2017-05-12T10:32:41.138000",
  31.         "extend":null
  32.     }
  33. }

错误码

错误代码 错误说明
10000 参数错误：参考Response中的message

OTA任务的设备列表（Token）

GET /v3/ota/devices/

请求参数

参数名 类型 必须 说明
otid int 是 任务ID

返回值

  1. {
  2.     "meta":{
  3.         "message":"OTA设备列表",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "count":5,
  8.         "next":null,
  9.         "previous":null,
  10.         "results":[
  11.             {
  12.                 "odid":"9b59b080-3494-11e7-91bc-dc536017523b",
  13.                 "otid":22,
  14.                 "product_id":"8d01f204150911e7a554fa163e876164",
  15.                 "device_id":"dba54e9e346311e79216dc536017523b",
  16.                 "dsn":"zrgtest050905",
  17.                 "status":0,
  18.                 "onset_time":"2017-05-10 16:50:54.528000",
  19.                 "create_time":"2017-05-09 16:50:54.528000"
  20.             },
  21.             {
  22.                 "odid":"9b59b080-3494-11e7-91bc-dc536017523b",
  23.                 "otid":22,
  24.                 "product_id":"8d01f204150911e7a554fa163e876164",
  25.                 "device_id":"dba54e9e346311e79216dc536017523b",
  26.                 "dsn":"zrgtest050905",
  27.                 "status":0,
  28.                 "onset_time":"2017-05-10 16:50:54.528000",
  29.                 "create_time":"2017-05-09 16:50:54.528000"
  30.             }
  31.         ]
  32.     }
  33. }

错误码

错误代码 错误说明
10000 参数错误：缺少otid参数

OTA设备的Log列表（Token）

GET /v3/ota/tasks/<odid>/logs/

请求参数

参数名 类型 必须 说明
odid string 是 OTA设备ID，不是设备ID，放在URL中

返回值

  1. {
  2.     "meta":{
  3.         "message":"Log列表",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "count":2,
  8.         "next":null,
  9.         "previous":null,
  10.         "results":[
  11.             {
  12.                 "olid":"9b76ff91-3620-11e7-af30-dc536017523b",
  13.                 "product_id":"8d01f204150911e7a554fa163e876164",
  14.                 "device_id":"bbddc751346311e7bc7bdc536017523b",
  15.                 "dsn":"zrgtest050901",
  16.                 "content":"OTA任务完成",
  17.                 "customize":null,
  18.                 "create_time":"2017-05-11T16:05:33.321000"
  19.             },
  20.             {
  21.                 "olid":"9b761530-3620-11e7-be45-dc536017523b",
  22.                 "product_id":"8d01f204150911e7a554fa163e876164",
  23.                 "device_id":"bbddc751346311e7bc7bdc536017523b",
  24.                 "dsn":"zrgtest050901",
  25.                 "content":"固件[test]更新完成",
  26.                 "customize":null,
  27.                 "create_time":"2017-05-11T16:05:33.315000"
  28.             }
  29.         ]
  30.     }
  31. }

错误码

错误代码 错误说明
10000 参数错误

获取某类产品的所有Log（Token）

GET /v3/ota/logs/

请求参数

参数名 类型 必须 说明
type int 是 产品类型：0→CP产品，1→IP产品，2→OTA产品

返回值

  1. {
  2.     "meta":{
  3.         "message":"Log列表",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "count":2,
  8.         "next":null,
  9.         "previous":null,
  10.         "results":[
  11.             {
  12.                 "olid":"9b76ff91-3620-11e7-af30-dc536017523b",
  13.                 "product_id":"8d01f204150911e7a554fa163e876164",
  14.                 "device_id":"bbddc751346311e7bc7bdc536017523b",
  15.                 "dsn":"zrgtest050901",
  16.                 "content":"OTA任务完成",
  17.                 "customize":null,
  18.                 "create_time":"2017-05-11T16:05:33.321000"
  19.             },
  20.             {
  21.                 "olid":"9b761530-3620-11e7-be45-dc536017523b",
  22.                 "product_id":"8d01f204150911e7a554fa163e876164",
  23.                 "device_id":"bbddc751346311e7bc7bdc536017523b",
  24.                 "dsn":"zrgtest050901",
  25.                 "content":"固件[test]更新完成",
  26.                 "customize":null,
  27.                 "create_time":"2017-05-11T16:05:33.315000"
  28.             }
  29.         ]
  30.     }
  31. }

错误码

错误代码 错误说明
10000 参数错误

OTA任务的推送接口（Token）

POST /v3/ota/tasks/<otid>/push/

请求参数

参数名 类型 必须 说明
otid int 是 OTA任务ID，放在URL中
dsn_list string list 是 需要接收推送通知的设备的串号或MAC地址列表

返回值

  1. {
  2.     "meta":{
  3.         "message":"推送完成",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "successes":[
  8.             "zrgtest051501"
  9.         ],
  10.         "errors":[
  12.         ]
  13.     }
  14. }

返回值字段说明

字段 说明
successes 推送成功的串号或MAC地址列表
errors 推送失败的串号或MAC地址列表

错误码

错误代码 错误说明
10000 参数错误，参考返回数据中的message

设备用OTA接口

FOG设备通过设备ID检查OTA

PUT /v3/ota/device/

请求参数

参数名 类型 必须 说明
deviceid string 是 设备ID
password string 是 设备密码
component string 否 固件名称

返回值

  1. {
  2.     "meta":{
  3.         "message":"ota file info",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "files":[
  8.             {
  9.                 "file_url":"https://test.com/a.bin",
  10.                 "component":"test1",
  11.                 "md5":"1abx..",
  12.                 "version":"1.0.1",
  13.                 "customize":""
  14.             },
  15.             {
  16.                 "file_url":"https://test.com/a.bin",
  17.                 "component":"test2",
  18.                 "md5":"1safa...",
  19.                 "version":"1.0.1",
  20.                 "customize":""
  21.             }
  22.         ],
  23.         "otid":25
  24.     }
  25. }

字段说明

返回值字段 字段类型 字段说明
need_upgrade bool 是否需要升级
otid int 任务ID
files list 升级文件列表

说明

错误码

错误代码 错误说明
10000 参数错误：具体信息见Response的message字段

设备通过产品ID检查OTA

PUT /v3/ota/product/

请求参数

参数名 类型 必须 说明
productid string 是 产品ID
dsn string 否 设备串号或MAC地址
component string 否 固件名称

返回值

  1. {
  2.     "meta":{
  3.         "message":"ota file info",
  4.         "code":0
  5.     },
  6.     "data":{
  7.         "files":[
  8.             {
  9.                 "file_url":"https://test.com/a.bin",
  10.                 "component":"test1",
  11.                 "md5":"1abx..",
  12.                 "version":"1.0.1",
  13.                 "customize":""
  14.             },
  15.             {
  16.                 "file_url":"https://test.com/a.bin",
  17.                 "component":"test2",
  18.                 "md5":"1safa...",
  19.                 "version":"1.0.1",
  20.                 "customize":""
  21.             }
  22.         ],
  23.         "otid":25
  24.     }
  25. }

字段说明

返回值字段 字段类型 字段说明
need_upgrade bool 是否需要升级
otid int 任务ID
files list 升级文件列表

错误码

错误代码 错误说明
10000 参数错误：具体信息见Response的message字段

设备发送OTA完成的通知

PUT /v3/ota/device/log/

请求参数

参数名 类型 必须 说明
deviceid string 是 设备ID
password string 是 设备密码
otid string 是 任务ID
isfinished bool 否 设备固件是否全部更新完成，默认为true
components string Array 否 本次更新完成的固件名称列表
customize string 否 用户自定义字符串

返回值

  1. {
  2.     "meta":{
  3.         "message":"ok",
  4.         "code":0
  5.     },
  6.     "data":{
  7.     }
  8. }

错误码

错误代码 错误说明
10000 参数错误：具体信息见Response的message字段

设备通过产品ID上报OTA完成的通知

PUT /v3/ota/product/log/

请求参数

参数名 类型 必须 说明
productid string 是 设备ID
dsn string 是 设备串号或MAC地址
otid string 是 任务ID
isfinished bool 否 设备固件是否全部更新完成，默认为true
components string Array 否 本次更新完成的固件名称列表
customize string 否 用户自定义字符串

返回值

  1. {
  2.     "meta":{
  3.         "message":"ok",
  4.         "code":0
  5.     },
  6.     "data":{
  7.     }
  8. }

错误码

错误代码 错误说明
10000 参数错误：具体信息见Response的message字段
添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注