@soszrg 2018-02-13T06:46:35.000000Z 字数 9765 阅读 542

OTA接口文档_复杂版（V3.1）

`V3.1`

版本：v3.1

URL前缀为v3_1，如：/v3_1/ota/files/

前端用OTA接口

固件上传（Token）

POST /ota/files/

固件上传完成后，将相关信息上报给云端保存。

请求参数

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

字段说明

version:云端不会check该字段的值，需要设备自己check；在设备调用OTA check接口(/ota/device/)后，返回的数据中会带有该值。
component：用于多功能模块分开OTA的场景，用户可以通过指定该字段告诉云端你想取得哪个功能模块的文件（前提是，在创建OTA任务时已经添加了同component的文件）。

返回值

{
    "meta":{
        "message":"固件创建成功",
        "code":0
    },
    "data":{
        "of_id":3,
        "product":{
            "product_id":"d927a33cf7...",
            "name":"test"
        },
        "file_name":"ota_file",
        "file_url":"https://bcsaa...ota.bin",
        "size":"1kb",
        "md5":"dafab...",
        "version":"1.0.1",
        "component":"",
        "upload_time":"2017-10-12 12:50:55",
        "description":"ota file",
        "customize":"",
        "extend":{
        }
    }
}

错误码

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

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

GET /ota/files/

取得某个产品的固件列表

请求参数

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

返回值

{
    "meta":{
        "message":"OTA File列表",
        "code":0
    },
    "data":{
        "count":2,
        "next":null,
        "previous":null,
        "results":[
            {
                "of_id":2,
                "product":{
                    "product_id":"d9afafa...",
                    "name":"test"
                },
                "file_name":"ota_file",
                "file_url":"https://www.ota...le.bin",
                "size":"1kb",
                "md5":"fafavvx...",
                "version":"1.0.1",
                "component":"",
                "upload_time":"2017-1-12 11:40:00",
                "description":"123456",
                "customize":"",
                "extend":{
                }
            },
            {
                "of_id":1,
                "product":{
                    "product_id":"d927a33cf75...",
                    "name":"test"
                },
                "file_name":"test18012201",
                "file_url":"https://bce-b..ota.bin",
                "size":"12kb",
                "md5":"262e...",
                "version":"ota_version_v0.1",
                "component":"",
                "upload_time":"2017-1-12 11:50:00",
                "description":"",
                "customize":"",
                "extend":{
                }
            }
        ]
    }
}

错误码

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

单个固件信息（Token）

GET /ota/files/<of_id>/

取得某个固件信息

请求参数

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

返回值

{
    "meta":{
        "message":"固件信息",
        "code":0
    },
    "data":{
        "of_id":1,
        "product":{
            "product_id":"d927a33cf75211...",
            "name":"test"
        },
        "file_name":"test18012201",
        "file_url":"https://bc0...ota(1).bin",
        "size":"1kb",
        "md5":"262e75bf...",
        "version":"ota_version_v0.1",
        "component":"",
        "upload_time":"2017-10-10 13：10：11",
        "description":"",
        "customize":"",
        "extend":{
        }
    }
}

错误码

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

创建OTA任务（Token）

POST /ota/tasks/

创建OTA任务，如果创建的是全局任务，将导致旧的全局任务失效。

请求参数

参数名	类型	必须	说明
ota_files	int list	是	OTA文件ID list
status	int	是	任务状态：0:测试，1:上线，2:无效
description	string	否	任务描述
ug_type	int	否	升级方式
mac_range	string list	否	要升级的MAC地址范围

ug_type说明：

0：静默升级
1：人工升级
2：强制升级

返回值

{
    "meta":{
        "message":"ä»»å¡åå»ºæå",
        "code":0
    },
    "data":{
        "ot_id":8,
        "product":{
            "product_id":"d927a33..."
            "name":"test"
        },
        "ota_files":[
            {
                "of_id":1,
                "file_name":"test18012201",
                "component":"",
                "description":"",
                "version":"0.1",
                "upload_time":"2018-01-22 10:17:59"
            }
        ],
        "status":0,
        "onset_time":"2018-01-30 10:00:00",
        "description":"123456",
        "ug_type":0,
        "mac_range":[
            "ACFF...",
            "CCCC.."
        ],
        "update_time":"2018-01-30 10:15:44",
        "create_time":"2018-01-30 10:15:44",
        "extend":null
    }
}

返回值说明

字段	类型	说明
ot_id	int	任务ID，任务唯一标识，用于后续任务的修改和删除等

错误码

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

任务列表（Token）

GET /ota/tasks/

任务列表

请求参数

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

说明

of_id和product_id以of_id为主，在两者都有的情况下，取到的是of_id相关的任务；如果两者都没有是取到当前用户的所有任务。

返回值

{
    "meta":{
        "message":"OTA任务列表",
        "code":0
    },
    "data":{
        "count":4,
        "next":null,
        "previous":null,
        "results":[
            {
                "ot_id":8,
                "product":{
                    "product_id":"d927a33c...",
                    "name":"test"
                },
                "ota_files":[
                    {
                        "of_id":1,
                        "file_name":"test18012201",
                        "component":"",
                        "description":"",
                        "version":"v0.2",
                        "upload_time":"2018-01-22 10:17:59"
                    }
                ],
                "status":0,
                "onset_time":"2018-01-30 10:00:00",
                "description":"123456",
                "ug_type":0,
                "mac_range":[
                    "aaa",
                    "bbb"
                ],
                "update_time":"2018-01-30 10:15:44",
                "create_time":"2018-01-30 10:15:44",
                "extend":null
            },
            {
                "ot_id":6,
                "product":{
                    "product_id":"d927a33cf75211e...",
                    "name":"test"
                },
                "ota_files":[
                    {
                        "of_id":1,
                        "file_name":"test18012201",
                        "component":"",
                        "description":"",
                        "version":"v0.1",
                        "upload_time":"2018-01-22 10:17:59"
                    }
                ],
                "status":1,
                "onset_time":"2018-01-30 10:00:00",
                "description":"123456",
                "ug_type":0,
                "mac_range":[
                    "aaa",
                    "bbb"
                ],
                "update_time":"2018-01-30 10:03:46",
                "create_time":"2018-01-30 10:03:46",
                "extend":null
            },
            {
                "ot_id":5,
                "product":{
                    "product_id":"d927a33cf75211e7804bfa163e431402",
                    "name":"test"
                },
                "ota_files":[
                    {
                        "of_id":1,
                        "file_name":"test18012201",
                        "component":"",
                        "description":"",
                        "version":"ota_version_v0.1",
                        "upload_time":"2018-01-22 10:17:59"
                    }
                ],
                "status":2,
                "onset_time":"2018-01-30 10:00:00",
                "description":"123456",
                "ug_type":0,
                "mac_range":[
                    "aaa",
                    "bbb"
                ],
                "update_time":"2018-01-30 09:47:59",
                "create_time":"2018-01-30 09:47:59",
                "extend":null
            },
        ]
    }
}

错误码

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

单个任务详情信息（Token）

GET /ota/tasks/<ot_id>/

获取单个任务的详细信息

请求参数

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

返回值

{
    "meta":{
        "message":"任务信息",
        "code":0
    },
    "data":{
        "ot_id":8,
        "product":{
            "product_id":"d927a33c...
            "name":"test"
        },
        "ota_files":[
            {
                "of_id":1,
                "file_name":"test18012201",
                "component":"",
                "description":"",
                "version":"ota_version_v0.1",
                "upload_time":"2018-01-22 10:17:59"
            }
        ],
        "status":0,
        "onset_time":"2018-01-30 10:00:00",
        "description":"123456",
        "ug_type":0,
        "mac_range":[
            "aaa",
            "bbb"
        ],
        "update_time":"2018-01-30 10:15:44",
        "create_time":"2018-01-30 10:15:44",
        "extend":null
    }
}

错误码

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

任务发布（Token）

PUT /ota/tasks/<ot_id>/release/

任务只有在发布后才能被设备检测到，测试阶段请使用MQTT推送方式，将OTA任务推送给设备，测试通过后，点击发布按钮，发布任务。

请求参数

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

返回值

{
    "meta":{
        "message":"发布成功",
        "code":0
    },
    "data":{
        "ot_id":8,
        "product":{
            "product_id":"d927a33c...
            "name":"test"
        },
        "ota_files":[
            {
                "of_id":1,
                "file_name":"test18012201",
                "component":"",
                "description":"",
                "version":"ota_version_v0.1",
                "upload_time":"2018-01-22 10:17:59"
            }
        ],
        "status":1,
        "onset_time":"2018-01-30 10:00:00",
        "description":"123456",
        "ug_type":0,
        "mac_range":[
            "aaa",
            "bbb"
        ],
        "update_time":"2018-01-30 10:27:49",
        "create_time":"2018-01-30 10:15:44",
        "extend":null
    }
}

错误码

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

OTA任务的设备列表（Token）

GET /ota/devices/

任务创建好后，设备会被添加到任务列表里，可以通过设备列表查看设备当前的更新状态。

请求参数

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

返回值

{
    "meta":{
        "message":"OTA设备列表",
        "code":0
    },
    "data":{
        "count":2,
        "next":null,
        "previous":null,
        "results":[
            {
                "id":8,
                "od_id":"3c58e198-...",
                "ot_id":2,
                "product_id":"d927a33cf75211...",
                "device_id":"3bc6d0a004a311e88...",
                "dsn":"B0F8931025AC",
                "status":1,
                "onset_time":"2018-01-22 10:31:31",
                "create_time":"2018-01-29 11:19:37"
            },
            {
                "id":7,
                "od_id":"6a934c72...",
                "ot_id":2,
                "product_id":"...",
                "device_id":"6a0e527e025c...",
                "dsn":"FCEEE6057262",
                "status":1,
                "onset_time":"2018-01-22 10:31:31",
                "create_time":"2018-01-26 13:47:38"
            }
        ],
        "complete_percentage":12.5
    }
}

错误码

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

OTA设备的Log列表（Token）

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

设备列表

请求参数

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

返回值

{
    "meta":{
        "message":"Log列表",
        "code":0
    },
    "data":{
        "count":2,
        "next":null,
        "previous":null,
        "results":[
            {
                "ol_id":"9b76ff91-3620-11e7-af30-dc536017523b",
                "product_id":"8d01f204150911e7a554fa163e876164",
                "device_id":"bbddc751346311e7bc7bdc536017523b",
                "dsn":"zrgtest050901",
                "content":"OTA任务完成",
                "customize":"",
                "create_time":"2017-05-11T16:05:33.321000"
            },
            {
                "ol_id":"9b761530-3620-11e7-be45-dc536017523b",
                "product_id":"8d01f204150911e7a554fa163e876164",
                "device_id":"bbddc751346311e7bc7bdc536017523b",
                "dsn":"zrgtest050901",
                "content":"固件[test]更新完成",
                "customize":"",
                "create_time":"2017-05-11T16:05:33.315000"
            }
        ]
    }
}

错误码

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

获取所有产品的OTA Log（Token）

GET /ota/logs/

所有产品的OTA log

返回值

{
    "meta":{
        "message":"Log列表",
        "code":0
    },
    "data":{
        "count":2,
        "next":null,
        "previous":null,
        "results":[
            {
                "ol_id":"9b76ff91-3620-11e7-af30-dc536017523b",
                "product_id":"8d01f204150911e7a554fa163e876164",
                "device_id":"bbddc751346311e7bc7bdc536017523b",
                "dsn":"zrgtest050901",
                "content":"OTA任务完成",
                "customize":"",
                "create_time":"2017-05-11T16:05:33.321000"
            },
            {
                "ol_id":"9b761530-3620-11e7-be45-dc536017523b",
                "product_id":"8d01f204150911e7a554fa163e876164",
                "device_id":"bbddc751346311e7bc7bdc536017523b",
                "dsn":"zrgtest050901",
                "content":"固件[test]更新完成",
                "customize":"",
                "create_time":"2017-05-11T16:05:33.315000"
            }
        ]
    }
}

错误码

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

OTA任务的推送接口（Token）

POST /ota/tasks/<ot_id>/push/

测试阶段的OTA任务，仅允许通过MQTT消息推送给指定的设备。

请求参数

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

返回值

{
    "meta":{
        "message":"推送完成",
        "code":0
    },
    "data":{
        "successes":[
            "zrgtest051501"
        ],
        "errors":[
        ]
    }
}

返回值字段说明

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

错误码

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

设备用OTA接口

FOG设备通过设备ID检查OTA

PUT /v3_1/ota/device/

设备自检查OTA，可以使用http和mqtt两种方式调用。

请求参数

参数名	类型	必须	说明
device_id	string	是	设备ID(mqtt不需要传该参数)
password	string	是	设备密码
component	string	否	组件名称(适用于多组件的产品)
req_type	int	否	请求类型(mqtt不需要传该参数)
req_id	int	否	请求ID,由设备端生成，用于追踪请求

req_type:0 → 消费者程序使用

此种方式时，设备需要向api/json topic中发送mqtt消息，请求的消息格式为:

{
    "type":"ota_check",
    "data":{
        "password": "112xx...",
        "component": "xxxx"  # 可选参数
        "req_id":123...
    }
}

设备还需订阅sys/json topic用来接收云端返回的api结果，返回的消息格式为：

{
    "type": "ota_check",
    "meta":{
        "message":"ota file info",
        "code":0
    },
    "data":{
        "files":[
            {
                "file_url":"https://test.com/a.bin",
                "component":"test1",
                "md5":"1abx..",
                "version":"1.0.1",
                "customize":""
            },
            {
                "file_url":"https://test.com/a.bin",
                "component":"test2",
                "md5":"1safa...",
                "version":"1.0.1",
                "customize":""
            }
        ],
        "ot_id":25,
        "req_id": 123...
    }
}

req_type:1 → 设备端通过HTTP方式解绑

返回值

{
    "meta":{
        "message":"ota file info",
        "code":0
    },
    "data":{
        "files":[
            {
                "file_url":"https://test.com/a.bin",
                "component":"test1",
                "md5":"1abx..",
                "version":"1.0.1",
                "customize":""
            },
            {
                "file_url":"https://test.com/a.bin",
                "component":"test2",
                "md5":"1safa...",
                "version":"1.0.1",
                "customize":""
            }
        ],
        "ot_id":25
    }
}

字段说明

返回值字段	字段类型	字段说明
ot_id	int	任务ID
files	list	升级文件列表
customize	string	用户自定义字段（公版不需要）

说明

ot_id：对应该升级文件的OTA任务ID；更新完成，需调用OTA完成的通知接口，上报更新完成状态给云端，此接口参数中用到ot_id。

错误码

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

设备发送OTA完成的通知

PUT /v3_1/ota/device/log/

设备发送OTA完成的通知

请求参数

参数名	类型	必须	说明
device_id	string	是	设备ID
password	string	是	设备密码
ot_id	int	是	任务ID
update_ok	bool	否	设备固件是否全部更新完成，默认为true
components	string Array	否	本次完成更新的组件名称列表
customize	string	否	用户自定义字符串（公版不需要）
req_type	int	是	请求类型(mqtt方式调用不需要此参数)
req_id	int	否	请求ID,由设备端生成，用于追踪请求

req_type:0 → 消费者程序使用

此种方式时，设备需要向api/json topic中发送mqtt消息，请求的消息格式为:

{
    "type":"ota_log",
    "data":{
        "password": "112xx...",
        "ot_id": 1,
        "update_ok": true,
        "components": ["bbbb", "aavc"],  # 可选参数
        "req_id":123...
    }
}

设备还需订阅sys/json topic用来接收云端返回的api结果，返回的消息格式为：

{
    "type":"ota_log",
    "meta":{
        "message":"ota log ok",
        "code":0
    },
    "req_id":123，
    "data":{
    }
}

req_type:1 → 设备端通过HTTP方式上传log

返回值

{
    "meta":{
        "message":"ok",
        "code":0
    },
    "data":{
    }
}

错误码

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

OTA接口文档_复杂版（V3.1）

V3.1

版本：v3.1

前端用OTA接口

固件上传（Token）

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

单个固件信息（Token）

创建OTA任务（Token）

任务列表（Token）

单个任务详情信息（Token）

任务发布（Token）

OTA任务的设备列表（Token）

OTA设备的Log列表（Token）

获取所有产品的OTA Log（Token）

OTA任务的推送接口（Token）

设备用OTA接口

FOG设备通过设备ID检查OTA

req_type:0 → 消费者程序使用

req_type:1 → 设备端通过HTTP方式解绑

设备发送OTA完成的通知

req_type:0 → 消费者程序使用

req_type:1 → 设备端通过HTTP方式上传log

内容目录

选择主题

`V3.1`