@soszrg 2018-03-28T02:30:45.000000Z 字数 6782 阅读 494

OTA接口文档_简单版（V3.1）

`V3.1`

版本：v3.1

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

前端用OTA接口

创建OTA任务（Token）

POST /ota/tasks/

创建OTA任务，将导致旧的线上任务失效。

请求参数

参数名	类型	必须	说明
product_id	string	是	产品ID
file_url	string	是	固件地址
version	string	是	固件版本（同一产品下不可重复）
md5	string	是	固件的MD5值
size	string	是	固件大小
ug_type	int	否	OTA类型
file_name	string	否	固件名
description	string	否	任务描述
mac_range	string list	否	要升级的MAC地址范围

ug_type说明

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

返回值

{
    "meta":{
        "message":"任务创建成功",
        "code":0
    },
    "data":{
        "ot_id":16,
        "product":{
            "product_id":"d927a33cf7...",
            "name":"测试1"
        },
        "ota_files":[
            {
                "of_id":11,
                "file_name":"",
                "component":"",
                "description":"",
                "version":"1.0.1",
                "upload_time":"2018-02-02 18:06:18",
                "size":"10kb"
            }
        ],
        "status":0,
        "description":"",
        "ug_type":0,
        "mac_range":[
        ],
        "update_time":"2018-02-02 18:06:18",
        "create_time":"2018-02-02 18:06:18",
        "extend":null
    }
}

返回值说明

字段	类型	说明
ot_id	int	任务ID，任务唯一标识，用于后续任务的修改和删除等
ug_type	int	OTA任务类型
status	int	任务当前状态：0 测试，1 上线，2 无效

错误码

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

任务列表（Token）

GET /ota/tasks/

任务列表

请求参数

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

返回值

{
    "meta":{
        "message":"OTA任务列表",
        "code":0
    },
    "data":{
        "count":2,
        "next":null,
        "previous":null,
        "results":[
            {
                "ot_id":17,
                "product":{
                    "product_id":"d927a33c...",
                    "name":"测试1"
                },
                "ota_files":[
                    {
                        "of_id":12,
                        "file_name":"",
                        "component":"",
                        "description":"",
                        "version":"1.0.1",
                        "upload_time":"2018-02-02 18:33:10",
                        "size":"10size"
                    }
                ],
                "status":0,
                "description":"",
                "ug_type":0,
                "mac_range":[
                ],
                "update_time":"2018-02-02 18:33:10",
                "create_time":"2018-02-02 18:33:10",
                "extend":null
            },
            {
                "ot_id":16,
                "product":{
                    "product_id":"d927a33cf...",
                    "name":"测试1"
                },
                "ota_files":[
                    {
                        "of_id":11,
                        "file_name":"",
                        "component":"",
                        "description":"",
                        "version":"1.0.1",
                        "upload_time":"2018-02-02 18:06:18",
                        "size":"10size"
                    }
                ],
                "status":0,
                "description":"",
                "ug_type":0,
                "mac_range":[
                ],
                "update_time":"2018-02-02 18:06:18",
                "create_time":"2018-02-02 18:06:18",
                "extend":null
            }
        ]
    }
}

错误码

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

单个任务信息（Token）

GET /ota/tasks/<ot_id>/

获取单个任务的详细信息

请求参数

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

返回值

{
    "meta":{
        "message":"任务信息",
        "code":0
    },
    "data":{
        "ot_id":2,
        "product":{
            "product_id":"d927a33cf...",
            "name":"测试1"
        },
        "ota_files":[
            {
                "of_id":1,
                "file_name":"test",
                "component":"",
                "description":"",
                "version":"ota_version_v0.3",
                "upload_time":"2018-01-22 10:17:59",
                "size":""
            }
        ],
        "status":1,
        "description":"",
        "ug_type":0,
        "mac_range":null,
        "update_time":"2018-01-22 10:31:31",
        "create_time":"2018-01-22 10:31:31",
        "extend":null
    }
}

错误码

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

删除单个任务（Token）

DELETE /ota/tasks/<ot_id>/

删除某个任务

请求参数

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

返回值

{
    "meta":{
        "message":"任务删除成功",
        "code":0
    },
    "data":{
        "ot_id":null
    }
}

错误码

错误代码	错误说明
10000	参数错误：参考Response中的message
10500	ot_id错误，找不到任务
10501	任务状态错误：仅有测试中的任务可以删除

修改任务（Token）

PUT /ota/tasks/<ot_id>/

修改指定任务的信息

请求参数

参数名	类型	必须	说明
ot_id	int	是	任务ID（拼接于url中）
file_url	string	是	固件地址
version	string	是	固件版本（同一产品下不可重复）
md5	string	是	固件的MD5值
size	string	是	固件大小
file_name	string	否	固件名
description	string	否	任务描述
mac_range	string list	否	要升级的MAC地址范围

返回值

{
    "meta":{
        "message":"æ´æ°ä»»å¡æå",
        "code":0
    },
    "data":{
        "ot_id":10,
        "product":{
            "product_id":"d927a33...",
            "name":"更新任务成功"
        },
        "ota_files":[
            {
                "of_id":5,
                "file_name":"fn",
                "component":"",
                "description":"12qwe",
                "version":"1.0.5",
                "upload_time":"2018-01-31 17:44:30",
                "size":"101kb",
                "file_url":"https://ota.com/firmware.bin",
                "md5":"AAVDWCSSSAAA..."
            }
        ],
        "status":0,
        "description":"123456",
        "ug_type":0,
        "mac_range":[
            "a...",
            "b...",
            "c..."
        ],
        "update_time":"2018-01-31 17:44:30",
        "create_time":"2018-01-31 17:44:30",
        "extend":null
    }
}

错误码

错误代码	错误说明
10000	参数错误：参考Response中的message
10500	ot_id错误，找不到任务
10501	任务状态错误：仅有测试中的任务可以修改

任务发布（Token）

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

发布某个任务。注意：任务发布后，同产品下之前上线的任务将失效。

请求参数

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

返回值

{
    "meta":{
        "message":"发布成功",
        "code":0
    },
    "data":{
        "ot_id":10,
        "product":{
            "product_id":"d91fa...",
            "name":"测试1"
        },
        "ota_files":[
            {
                "of_id":5,
                "file_name":"fn",
                "component":"",
                "description":"12qwe",
                "version":"1.0.5",
                "upload_time":"2018-01-31 17:44:30",
                "size":"101kb",
                "file_url":"https://ota.com/1.bin",
                "md5":"AAVDWCSSSAAA"
            }
        ],
        "status":1,
        "description":"123456",
        "ug_type":0,
        "mac_range":[
            "a",
            "b",
            "c"
        ],
        "update_time":"2018-02-05 15:49:48",
        "create_time":"2018-01-31 17:44:30",
        "extend":null
    }
}

错误码

错误代码	错误说明
10000	ot_id错误，找不到任务

推送OTA到设备（Token）

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

推送固件信息给设备。

请求参数

参数名	类型	必须	说明
ot_id	int	是	任务ID
dsn_list	string array	是	MAC地址数组

返回值

{
    "meta":{
        "message":"推送完成",
        "code":0
    },
    "data":{
        "errors": ["ACX...", "BESF..."],
        "successes": ["FBXX...", "AAACC..."]
    }
}

字段说明

字段	类型	说明
successes	list	推送成功的设备
errors	list	推送失败的设备

错误码

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

获取设备的OTA日志（Token）

GET /ota/tasks/logs/

获取某个设备的OTA日志。

请求参数

参数名	类型	必须	说明
device_id	string	是	设备ID

返回值

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

错误码

错误代码	错误说明
10500	ot_id错误，找不到任务
10501	任务状态错误：仅有测试中的任务可以删除

设备用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
    }
}

字段说明

返回值字段	字段类型	字段说明
need_upgrade	bool	是否需要升级
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接口

创建OTA任务（Token）

任务列表（Token）

单个任务信息（Token）

删除单个任务（Token）

修改任务（Token）

任务发布（Token）

推送OTA到设备（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`