设备管理接口
更新时间：2019-12-11
概述
欢迎使用百度智能云车联网车载设备、分组数据管理服务。
- 设备服务是一套车载设备管理服务，提供WebAPI供开发者便捷接入，对设备进行绑定、解绑、激活等操作。开发者可以迅速构建一套完全属于您自己的完整、精准且高性能的设备管理服务系统。
- 分组服务是一套对车载设备进行分组的服务，提供WebAPI供开发者便捷接入，对设备相应的分组进行创建、编辑、删除等操作。开发者可以迅速构建一套完全属于您的完整、精准且高性能的分组管理服务系统，可应用于其他硬件设备管理等领域。
您可以使用本文档介绍的API对设备服务、分组服务进行灵活的操作。
接口概览
车联网设备、分组服务提供下列接口类型：
| 接口类型 | 描述 |
|---|---|
| 设备管理接口 | 设备服务支持设备的增删改查操作。该组接口包括批量绑定、激活设备、解绑设备、更新设备别名 |
| 分组管理接口 | 分组服务支持对设备进行分组操作。该组接口包括创建分组、编辑分组、删除分组、修改所属分组 |
设备、分组管理错误码
| 错误码 | 错误消息 | HTTP状态码 | 描述 |
|---|---|---|---|
| InvalidParam | 传入参数不符合规范 | 400 | 传入参数不符合规范 |
| DeviceAlreadyBinded | 有设备已经被绑定 | 400 | 有设备已经被绑定 |
| InvalidRequestParam | 请求参数有误：{message} | 400 | 请求参数有误：{message} |
| BatchSizeExceeded | 批量操作有限，请减少数量重试 | 400 | 批量操作有限，请减少数量重试 |
| DuplicateDevice | 包含重复的设备信息 | 400 | 包含重复的设备信息 |
| SomeDeviceNotAuthorized | 包含未授权的设备 | 400 | 包含未授权的设备 |
| DugoDeviceProjectNotFound | 尚未创建DUGO自有硬件项目，请联系相关支持人员创建后重试 | 400 | 尚未创建DUGO自有硬件项目，请联系相关支持人员创建后重试 |
| duplicateVehicleId | 该设备ID在您的项目中已存在，请勿重复绑定 | 400 | 该车辆ID在您的项目中已存在，请勿重复绑定 |
| SimultaneousBind | 您当前存在一个正在进行中任务，请稍后再试 | 400 | 您当前存在一个正在进行中任务，请稍后再试 |
| instanceCountInsufficient | 该项目可用实例数量不足 | 403 | 该项目可用实例数量不足 |
| concurrentUpdateError | 当前操作速率太快，请稍等片刻后重试；操作失败，请重试 | 400 | 当前操作速率太快，请稍等片刻后重试；操作失败，请重试 |
| vehicleInBindingUnbindFailed | 车辆处于绑定中不支持解绑，请稍后重试 | 403 | 车辆处于绑定中不支持解绑，请稍后重试 |
| NotAuthorizedException | 授权不足 | 403 | 授权不足 |
| protocolTypeNotSupport | 协议类型暂不支持 | 403 | 协议类型暂不支持 |
| deviceNotExist | 该设备不存在 | 400 | 该设备不存在 |
| groupAlreadyExist | 分组名已存在 | 400 | 分组名已存在 |
| notAllowedDeleteDefaultGroup | 默认分组不支持删除 | 400 | 默认分组不支持删除 |
| ServerInternalError | 服务内部错误，分组数据异常，设备数据异常 | 500 | 服务内部错误，分组数据异常，设备数据异常 |
| activatingDeviceNotAllowedDeleteGroup | 有设备正在激活中，不允许删除分组 | 400 | 有设备正在激活中，不允许删除分组 |
| groupNotExist | 分组不存在 | 400 | 分组不存在 |
| vehicleNotExist | 车辆id不存在，请确认是否已经绑定成功 | 400 | 车辆id不存在，请确认是否已经绑定成功 |
| activatingDeviceNotAllowedDeleteGroup | 有设备正在激活中，不允许删除分组 | 400 | 有设备正在激活中，不允许删除分组 |
设备管理接口
批量绑定设备
接口描述：本接口用于批量绑定设备
- 请求参数中需要选定设备的型号、设备名以及设备的校验码。
注意事项
本接口用于批量绑定设备
- 请求参数均不能为空，否则绑定设备失败
- 批量绑定设备数至少为1台
请求结构
POST /v1/device/batchbind
Host: ivc.gz.baidubce.com
Authorization: authorization string
Content-Type: application/json
x-bce-console-rpc-id: de9468eb-a30b-477e-a98a-b1bb14836e7e
x-bce-date: 2019-11-28T09:02:05Z
{
"deviceBindInfoList":{[
"pk":pk,
"dn":dn,
"sign":sign
]}
}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| pk | String | 是 | RequestBody参数 | 设备型号 |
| dn | String | 是 | RequestBody参数 | 设备名称 |
| sign | String | 是 | RequestBody参数 | 校验码 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
无参数。
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| InvalidParam | 传入参数不符合规范 | 400 | 传入参数不符合规范 |
| DeviceAlreadyBinded | 有设备已经被绑定 | 400 | 有设备已经被绑定 |
| InvalidRequestParam | 上传的设备列表中包含重复设备 | 400 | 上传的设备列表中包含重复设备 |
| BatchSizeExceeded | 批量操作有限，请减少数量重试 | 400 | 批量操作有限，请减少数量重试 |
| DuplicateDevice | 包含重复的设备信息 | 400 | 包含重复的设备信息 |
| ServerInternalError | 无默认分组 | 500 | 无默认分组 |
请求示例
POST /v1/device/batchbind
Host: ivc.gz.baidubce.com
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
Content-Type: application/json
x-bce-date: 2019-11-25T404:02:05Z
{
"deviceBindInfoList" : [
{
"pk":"QGON",
"dn":"10000",
"sign":"291ndo"
},
{
"pk":"QPOS",
"dn":"10103",
"sign": "2lsy71"
}
]
}响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Tus, 28 Nov 2019 03:28:11 GMT
X-Bce-Request-Id: d8752367-38e8-45e4-b4c7-e53be3137ce5
Server: BWS激活设备
接口描述：本接口用于批量激活设备
- 请求参数中需要选定需要被激活的设备，1台以上
注意事项
本接口用于批量激活设备
- 若设备尚未被授权，是无法进行激活
- 批量操作是有上限的
请求结构
POST /v1/device/activate
Host: ivc.gz.baidubce.com
Authorization: authorization string
Content-Type: application/json
x-bce-console-rpc-id: de9468eb-a30b-477e-a98a-b1bb14836e7e
x-bce-date: 2019-11-28T09:02:05Z
{
"deviceIds":deviceIds
}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| deviceIds | List<String> | 是 | RequestBody参数 | 设备ID列表 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
无参数。
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| BatchSizeExceeded | 批量操作有限，请减少数量重试 | 400 | 批量操作有限，请减少数量重试 |
| SomeDeviceNotAuthorized | 包含未授权的设备 | 400 | 包含未授权的设备 |
| DugoDeviceProjectNotFound | 尚未创建DUGO自有硬件项目，请联系相关支持人员创建后重试 | 400 | 尚未创建DUGO自有硬件项目，请联系相关支持人员创建后重试 |
| duplicateVehicleId | 该设备ID在您的项目中已存在，请勿重复绑定 | 400 | 该车辆ID在您的项目中已存在，请勿重复绑定 |
| SimultaneousBind | 您当前存在一个正在进行中任务，请稍后再试 | 400 | 您当前存在一个正在进行中任务，请稍后再试 |
| instanceCountInsufficient | 该项目可用实例数量不足 | 403 | 该项目可用实例数量不足 |
| concurrentUpdateError | 当前操作速率太快，请稍等片刻后重试；操作失败，请重试 | 400 | 当前操作速率太快，请稍等片刻后重试；操作失败，请重试 |
请求示例
POST /v1/device/activate
Host: ivc.gz.baidubce.com
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
Content-Type: application/json
x-bce-date: 2019-11-25T404:02:05Z
{
"deviceIds" : [
"QGON_100123",
"QSON_138200",
"QGEN_199126"
]
}响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Tus, 28 Nov 2019 03:28:11 GMT
X-Bce-Request-Id: d8752367-38e8-45e4-b4c7-e53be3137ce5
Server: BWS解绑设备
接口描述：本接口用于批量解绑设备
- 请求参数中选取需要解绑的设备ID。
注意事项
本接口用于批量解绑设备
- 请求参数均不能为空，否则绑定设备失败
- 被解绑的设备必须为已授权的设备，未授权的设备无法进行解绑
请求结构
POST /v1/device/batchunbind
Host: ivc.gz.baidubce.com
Authorization: authorization string
Content-Type: application/json
x-bce-console-rpc-id: de9468eb-a30b-477e-a98a-b1bb14836e7e
x-bce-date: 2019-11-28T09:02:05Z
{
"deviceIds" : deviceIds
}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| deviceIds | List<String> | 是 | RequestBody参数 | 设备ID列表，设备ID由设备的型号以及名称组成即：pk_dn |
响应头域
除公共头域外，无其它特殊头域。
响应参数
无参数。
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| BatchSizeExceeded | 批量操作有上限，请减少数量重试 | 400 | 批量操作有限，请减少数量重试 |
| SomeDeviceNotAuthorized | 包含未授权的设备 | 400 | 包含未授权的设备 |
| DugoDeviceProjectNotFound | 尚未创建DUGO自有硬件设备，请联系相关支持人员创建后重试 | 400 | 尚未创建DUGO自有硬件设备，请联系相关支持人员创建后重试 |
| vehicleInBindingUnbindFailed | 车辆处于绑定中不支持解绑，请稍后重试 | 403 | 车辆处于绑定中不支持解绑，请稍后重试 |
| InvalidRequestParam | ID格式不合法 | 400 | ID格式不合法 |
| NotAuthorizedException | 授权不足 | 403 | 授权不足 |
| protocolTypeNotSupport | 协议类型暂不支持 | 403 | 协议类型暂不支持 |
| concurrentUpdateError | 当前操作速率太快，可稍等片刻后继续 | 400 | 当前操作速率太快，可稍等片刻后继续 |
请求示例
POST /v1/device/batchunbind
Host: ivc.gz.baidubce.com
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
Content-Type: application/json
x-bce-date: 2019-11-25T404:02:05Z
{
"deviceIds": [
"QGON_100123",
"QSON_138200",
"QGEN_199126"
]
}响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Tus, 28 Nov 2019 03:28:11 GMT
X-Bce-Request-Id: d8752367-38e8-45e4-b4c7-e53be3137ce5
Server: BWS更新设备别名
接口描述：本接口用于更新设备别名
注意事项
本接口用于更新设备别名
- 本接口只更新已存在的设备的别名，若设备不存在更新失败
- 设备别名长度为1~128
请求结构
PUT /v1/device/{deviceId}
Host: ivc.gz.baidubce.com
Authorization: authorization string
Content-Type: application/json;charset=utf-8
x-bce-console-rpc-id: de9468eb-a30b-477e-a98a-b1bb14836e7e
x-bce-date: 2019-03-06T03:39:34Z
{
"aliasName": aliasName
}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| deviceId | String | 是 | URL参数 | 设备ID |
| aliasName | String | 是 | RequestBody参数 | 设备别名，长度为1~128 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
无参数。
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| deviceNotExist | 该设备不存在 | 400 | 该设备不存在 |
请求示例
PUT /v1/device/QGON_10000
Host: ivc.gz.baidubce.com
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
Content-Type: application/json;charset=utf-8
x-bce-request-id: 074c5c9a-36c3-4558-9fa1-0b3b27813af3
x-bce-date: 2019-11-25T404:02:05Z
{
"aliasName": "erg"
}响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tus, 28 Nov 2019 03:28:11 GMT
X-Bce-Request-Id:7eb57c78-6d0f-4770-96ca-7013ee5d20ca
Server: BWS分组管理接口
创建分组
接口描述：本接口用于创建一个设备分组
注意事项
本接口用于创建分组
- 输入的分组名称若已存在，则创建分组失败
请求结构
POST /v1/group
Host: ivc.gz.baidubce.com
Authorization: authorization string
Content-Type: application/json;charset=utf-8
x-bce-console-rpc-id: de9468eb-a30b-477e-a98a-b1bb14836e7e
x-bce-date: 2019-03-06T03:39:34Z
{
"groupName": groupName
}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| groupName | String | 是 | RequestBody参数 | 分组名称，@Size(min = 1, max = 128) |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| groupId | String | 分组ID |
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| groupAlreadyExist | 分组名已存在 | 400 | 分组名已存在 |
请求示例
POST /v1/group
Host: ivc.gz.baidubce.com
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
Content-Type: application/json;charset=utf-8
x-bce-request-id: 074c5c9a-36c3-4558-9fa1-0b3b27813af3
x-bce-date: 2019-11-25T404:02:05Z
{
"groupName" : "77c39b92d94549f38872e0f3bb4a8cda"
}响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tus, 28 Nov 2019 03:28:11 GMT
X-Bce-Request-Id:7eb57c78-6d0f-4770-96ca-7013ee5d20ca
Server: BWS
{
"groupId":"31174db30b624fb7b54d1585c22b168a"
}编辑分组
接口描述：本接口用于编辑分组
注意事项
本接口用于编辑分组名称
- 输入的分组名称若已存在，则编辑分组失败
- 分组名不能为空
请求结构
PUT /v1/group
Host: ivc.gz.baidubce.com
Authorization: authorization string
Content-Type: application/json;charset=utf-8
x-bce-console-rpc-id: de9468eb-a30b-477e-a98a-b1bb14836e7e
x-bce-date: 2019-03-06T03:39:34Z
{
"groupId": groupId,
"groupName": groupName
}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| groupId | String | 是 | RequestBody参数 | 分组ID |
| groupName | String | 是 | RequestBody参数 | 分组名称，@Size(min = 1, max = 128) |
响应头域
除公共头域外，无其它特殊头域。
响应参数
无参数。
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| groupAlreadyExist | 分组名已存在 | 400 | 分组名已存在 |
请求示例
PUT /v1/group
Host: ivc.gz.baidubce.com
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
Content-Type: application/json;charset=utf-8
x-bce-request-id: 074c5c9a-36c3-4558-9fa1-0b3b27813af3
x-bce-date: 2019-11-25T404:02:05Z
{
"groupId" : "54c83a0138ce4c7887dcedb17e25811e",
"groupName" : "50bb81103f0e496c9f50015b04a6f9ac"
}响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tus, 28 Nov 2019 03:28:11 GMT
X-Bce-Request-Id:7eb57c78-6d0f-4770-96ca-7013ee5d20ca
Server: BWS删除分组
接口描述：本接口用于删除分组
注意事项
本接口用于根据分组ID删除分组
- 若分组中存在设备处于激活状态中，则无法删除分组
- 默认分组不支持删除
- 等某一删除操作完成后再去做其他操作
请求结构
DELETE /v1/group/{groupId}
Host: ivc.gz.baidubce.com
Authorization: authorization string
Content-Type: application/json;charset=utf-8
x-bce-console-rpc-id: de9468eb-a30b-477e-a98a-b1bb14836e7e
x-bce-date: 2019-03-06T03:39:34Z请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| groupId | String | 必须 | URL参数 | 分组ID |
响应头域
除公共头域外，无其它特殊头域。
响应参数
无参数。
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| groupNotExist | 分组不存在 | 400 | 分组不存在 |
| notAllowedDeleteDefaultGroup | 默认分组不支持删除 | 400 | 默认分组不支持删除 |
| ServerInternalError | 服务内部错误，分组数据异常，设备数据异常 | 500 | 服务内部错误，分组数据异常，设备数据异常 |
| activatingDeviceNotAllowedDeleteGroup | 有设备正在激活中，不允许删除分组 | 400 | 有设备正在激活中，不允许删除分组 |
| SimultaneousBind | 当前存在一个正在进行中任务，请稍后再试 | 400 | 当前存在一个正在进行中任务，请稍后再试 |
| concurrentUpdateError | 当前操作速率太快，请稍等片刻后重试 | 400 | 当前操作速率太快，请稍等片刻后重试 |
请求示例
DELETE /v1/group/51c72f043e16404e9b64e77cfd3f5d96
Host: ivc.gz.baidubce.com
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
Content-Type: application/json;charset=utf-8
x-bce-request-id: 074c5c9a-36c3-4558-9fa1-0b3b27813af3响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tus, 28 Nov 2019 03:28:11 GMT
X-Bce-Request-Id:6c2ba51d-6916-4906-b18e-f14a9d1c6c54
Server: BWS修改所属分组
接口描述：本接口用于修改设备所属分组
注意事项
本接口用于修改指定设备所属分组
- 指定的分组若不存在则无法修改设备的分组
请求结构
PUT /v1/group/vehicle
Host: ivc.gz.baidubce.com
Authorization: authorization string
Content-Type: application/json;charset=utf-8
x-bce-console-rpc-id: de9468eb-a30b-477e-a98a-b1bb14836e7e
x-bce-date: 2019-03-06T03:39:34Z
{
"vehicleId":vehicleId,
"groupId": groupId
}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| vehicleId | String | 必须 | RequestBody参数 | 车辆（设备）ID |
| groupId | String | 必须 | RequestBody参数 | 分组ID |
响应头域
除公共头域外，无其它特殊头域。
响应参数
无参数。
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| deviceNotExist | 设备不存在 | 400 | 设备不存在 |
| groupNotExist | 分组不存在 | 400 | 分组不存在 |
| vehicleNotExist | 车辆id不存在，请确认是否已经绑定成功 | 400 | 车辆id不存在，请确认是否已经绑定成功 |
| ServerInternalError | 服务内部错误，分组数据异常，设备数据异常 | 400 | 服务内部错误，分组数据异常，设备数据异常 |
| SimultaneousBind | 当前存在一个正在进行中任务，请稍后再试 | 400 | 当前存在一个正在进行中任务，请稍后再试 |
| concurrentUpdateError | 当前操作速率太快，请稍等片刻后重试 | 400 | 当前操作速率太快，请稍等片刻后重试 |
| activatingDeviceNotAllowedDeleteGroup | 有设备正在激活中，不允许删除分组 | 400 | 有设备正在激活中，不允许删除分组 |
请求示例
PUT /v1/group/vehicle
Host: ivc.gz.baidubce.com
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
Content-Type: application/json;charset=utf-8
x-bce-request-id: 074c5c9a-36c3-4558-9fa1-0b3b27813af3
{
"vehicleId" : "QGON_10000",
"groupId" : "8baf6f9264604031bae16740e15d17fc"
}响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tus, 28 Nov 2019 03:28:11 GMT
X-Bce-Request-Id:6c2ba51d-6916-4906-b18e-f14a9d1c6c54
Server: BWS数据类型
设备管理对象定义
Device
| 参数名称 | 类型 | 描述 |
|---|---|---|
| deviceId | String | 设备ID |
| pk | String | 设备型号 |
| dn | String | 设备名称 |
| aliasName | String | 设备别名 |
| groupId | String | 分组ID |
| groupName | String | 分组名称 |
| status | String | 设备状态，非激活 INACTIVE 激活 ACTIVE |
| batchId | String | 批量处理ID |
| createTime | Date | 设备添加时间 |
| expireTime | Date | 设备有效时间 |