度家设备管理API
1. 概述
本文档为您介绍如何通过API操作设备管理的部分功能，阅读本文当前请您先熟悉相关核心概念，并确认您已在度家AIOT语音平台的控制台上完成创建厂商、创建产品两个步骤,操作详情请参考快速入门。
2. 接口概览
目前度家AIOT语音平台提供下列设备管理接口，注意下方表格中的"ak"、"sk"是设备管理API中与fc、pk对应的参数，而不是百度云鉴权的Access Key（AK）和Secret Access Key（SK）。
| 接口类型 | 描述 |
|---|---|
| 批量（单个）设备导入 | 动态导入设备ak、sk信息，导入设备信息后可调用语音服务 |
| 删除设备（单个） | 根据ak信息删除单个设备，删除设备后已消耗的设备管理额度不返还 |
| 禁用设备（单个） | 禁止单个设备调用云端语音服务，用于管理发生异常调用的设备，避免无端消耗语音服务额度 |
| 启用设备（单个） | 恢复被禁用的设备，设备启用后可正常调用云端服务 |
| 获取设备信息（单个) | 返回单个设备的详细信息，详见具体接口 |
| 获取设备信息（列表) | 返回同一个产品下所有设备的信息，详见具体接口 |
3.通用说明
API调用遵循HTTPS协议，目前只支持BJ Region，具体域名为smarthome-bdvs.baidubce.com。 数据交换格式为JSON，所有request/response body内容均采用UTF-8编码。
3.1 实名认证
使用SHC API的用户需要实名认证，没有通过实名认证的可以前往百度智能云官网控制台中的安全认证下的实名认证中进行认证。 百度云提供个人认证、企业认证两种认证方式，您可以根据实际情况选择一种进行认证。
3.2 API认证机制
所有API的安全认证一律采用Access Key与请求签名机制。 Access Key由Access Key ID和Secret Access Key组成，均为字符串。 对于每个HTTP请求，使用下面所描述的算法生成一个认证字符串。提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。 认证字符串的格式为bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}。
- version是正整数。
- timestamp是生成签名时的UTC时间。
- expirationPeriodInSeconds表示签名有效期限。
- signedHeaders是签名算法中涉及到的头域列表。头域名之间用分号（;）分隔，如host;x-bce-date。列表按照字典序排列。（本API签名仅使用host和x-bce-date两个header）
- signature是256位签名的十六进制表示，由64个小写字母组成。
当百度云接收到用户的请求后，系统将使用相同的SK和同样的认证机制生成认证字符串，并与用户请求中包含的认证字符串进行比对。如果认证字符串相同，系统认为用户拥有指定的操作权限，并执行相关操作；如果认证字符串不同，系统将忽略该操作并返回错误码。
鉴权认证机制的详细内容请参见鉴权认证机制。
3.3 通信协议
仅支持HTTPS调用方式。
3.4 请求结构说明
数据交换格式为JSON，所有request/response body内容均采用UTF-8编码。
请求参数包括如下4种：
| 参数类型 | 说明 |
|---|---|
| URI | 通常用于指明操作实体，如:POST /v{version}/instance/{instanceId} |
| Query参数 | URL中携带的请求参数，通常用来指明要对实体进行的动作 |
| HEADER | 通过HTTP头域传入，如:x-bce-date |
| RequestBody | 通过JSON格式组织的请求数据体 |
3.5 响应结构说明
响应值分为两种形式：
| 响应内容 | 说明 |
|---|---|
| HTTP STATUS CODE | 如200,400,403,404等 |
| ResponseBody | JSON格式组织的响应数据体 |
3.6 API版本号
| 参数 | 类型 | 参数位置 | 描述 | 是否必须 |
|---|---|---|---|---|
| version | String | URI参数 | API版本号，当前值为2 | 必须 |
3.7 日期与时间规范
日期与时间的表示有多种方式。为统一起见，除非是约定俗成或者有相应规范的，凡需要日期时间表示的地方一律采用北京时间，遵循ISO 8601，并做以下约束：
- 表示日期一律采用
YYYY-MM-DD方式，例如2014-06-01表示2014年6月1日。 - 表示时间一律采用
hh:mm:ss方式，例如23:00:10表示北京时间23点0分10秒。 - 凡涉及日期和时间合并表示时，在两者中间加空格，例如
2014-06-01 23:00:10表示北京时间2014年6月1日23点0分10秒。
3.8 规范化字符串
通常一个字符串中可以包含任何Unicode字符。在编程中这种灵活性会带来不少困扰。因此引入“规范字符串”的概念。一个规范字符串只包含百分号编码字符以及URI（Uniform Resource Identifier）非保留字符（Unreserved Characters）。 RFC 3986规定URI非保留字符包括以下字符：字母（A-Z，a-z）、数字（0-9）、连字号（-）、点号（.）、下划线（_）、波浪线（~）。
将任意一个字符串转换为规范字符串的方式是:
- 将字符串转换成UTF-8编码的字节流。
- 保留所有URI非保留字符原样不变。
- 对其余字节做一次RFC 3986中规定的百分号编码（Percent-Encoding），即一个%后面跟着两个表示该字节值的十六进制字母。字母一律采用大写形式。
示例：
原字符串：this is an example for 测试,
对应的规范字符串：this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95。
3.9 度家AIOT语音平台产品编码要求
- 可解析内容，所有request/response body内容目前均使用UTF-8编码，后续会支持更多encoding类型。
-
在请求时，需要对以下做UrlEncode：
- Objectname，其中，Resource做UrlEncode的时候需要忽略“/”。
- Querystring的Value。
- x-bce-copy-source（忽略“/”）。
- 自定义Meta:Meta Value只支持可见的ASCII字符，如果需要其它的字符，推荐使用UrlEncode处理。
3.10 度家AIOT语音平台服务域名
| 区域 | 服务端点Endpoint | 协议 |
|---|---|---|
| 北京 | smarthome-bdvs.baidubce.com | HTTPS |
3.11 公共请求头与公共响应头
公共请求头
| 头域 | 说明 | 是否必须 |
|---|---|---|
| Authorization | 包含Access Key与请求签名。具体请参考鉴权认证 | 必须 |
| Content-Type | application/json; charset=utf-8 | 必须 |
| x-bce-date | 该请求创建的时间，表示日期一律采用YYYY-MM-DD方式，例如2014-06-01表示2014年6月1日。如果用户使用了标准的Date域，该头域可以不填。当两者同时存在时，以x-bce-date为准。 | 必须 |
公共响应头
| 头域 | 说明 |
|---|---|
| Content-Type | application/json; charset=utf-8 |
| x-bce-request-id | 对应请求的requestId |
3.12 错误码
错误码格式
当用户访问API出现错误时，会返回给用户相应的错误码和错误信息，便于定位问题，并做出适当的处理。请求发生错误时通过Response Body返回详细错误信息，遵循如下格式：
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | String | 表示具体错误类型。 |
| message | String | 有关该错误的详细说明。 |
| requestId | String | 导致该错误的requestId。 |
例如：
{
"code":"IllegalRequestUrl",
"message":"The requested url belongs to domain which is not under acceleration",
"requestId":" 81d0b05f-5ad4-1f22-8068-d5c9de60a1d7"
}公共错误码
| 错误码 | 错误消息 | HTTP状态码 | 描述 |
|---|---|---|---|
| AccessDenied | Access denied. | 403 Forbidden | 无权限访问对应的资源。 |
| InappropriateJSON | The JSON you provided was well-formed and valid, but not appropriate for this operation. | 400 Bad Request | 请求中的JSON格式正确，但语义上不符合要求。如缺少某个必需项，或者值类型不匹配等。出于兼容性考虑，对于所有无法识别的项应直接忽略，不应该返回这个错误。 |
| InternalError | We encountered an internal error. Please try again. | 500Internal Server Error | 所有未定义的其他错误。在有明确对应的其他类型的错误时（包括通用的和服务自定义的）不应该使用。 |
| InvalidAccessKeyId | The Access Key ID you provided does not exist in our records. | 403 Forbidden | Access Key ID不存在。 |
| InvalidHTTPAuthHeader | The HTTP authorization header is invalid. Consult the service documentation for details. | 400 Bad Request | Authorization头域格式错误。 |
| InvalidHTTPRequest | There was an error in the body of your HTTP request. | 400 Bad Request | HTTP body格式错误。例如不符合指定的Encoding等。 |
| InvalidURI | Could not parse the specified URI. | 400 Bad Request | URI形式不正确。例如一些服务定义的关键词不匹配等。对于ID不匹配等问题，应定义更加具体的错误码，例如NoSuchKey。 |
| MalformedJSON | The JSON you provided was not well-formed. | 400 Bad Request | JSON格式不合法。 |
| InvalidVersion | The API version specified was invalid. | 404 Not Found | URI的版本号不合法。 |
| OptInRequired | A subscription for the service is required. | 403 Forbidden | 没有开通对应的服务。 |
| PreconditionFailed | The specified If-Match header doesn't match the ETag header. | 412 Precondition Failed | 详见ETag。 |
| RequestExpired | Request has expired. Timestamp date is XXX. | 400 Bad Request | 请求超时。XXX要改成x-bce-date的值。如果请求中只有Date，则需要将Date转换为datetime。 |
| IdempotentParameterMismatch | The request uses the same client token as a previous, but non-identical request. | 403 Forbidden | clientToken对应的API参数不一样。 |
| SignatureDoesNotMatch | The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details. | 400 Bad Request | Authorization头域中附带的签名和服务端验证不一致。 |
度家AIOT语音平台自定义错误码说明
| 错误码 | 错误消息 | 描述 |
|---|---|---|
| 0 | OK | 正常 |
| 1 | Missing fc Parameter | 缺少fc参数 |
| 2 | Missing pk Parameter | 缺少pk参数 |
| 3 | FC Not Found | fc不存在 |
| 4 | PK Not Found | pk不存在 |
| 5 | CSV Format Error or Missing ak/sk Parameter. | csv格式错误或缺少ak/sk参数 |
| 6 | Import Device Batch Error: Max Batch Size is 1000. | 单次最大导入设备数1000 |
| 7 | AK Duplicated. | pk下存在重复ak |
| 8 | Read File Error. | 读取csv文件失败 |
| 9 | Empty File Error. | csv文件为空 |
| 10 | Insufficient Quota Error. | 设备管理额度不足 |
| 11 | Device Not Found. | 设备不存在 |
| 12 | Generate TTS Url Error. | 合成音频文件失败 |
4.设备管理API
4.1 批量（单个）导入设备
基本信息
Path： /v2/manage/device
Method： POST
请求参数
Body
| 名称 | 类型 | 是否必须 | 默认值 | 备注 | 其他信息 |
|---|---|---|---|---|---|
| fc | string | 必须 | |||
| pk | string | 必须 | |||
| devices | string [] | 必须 | item 类型: string | ||
| ├─ | 必须 | CSV字符串: ak,sk |
返回数据
| 名称 | 类型 | 默认值 | 备注 | 其他信息 |
|---|---|---|---|---|
| code | number | 见 SHC自定义code说明 | ||
| message | string |
返回示例
{
"code":0,
"message":""
}4.2 删除设备(单个)
基本信息
Path： /v2/manage/device/:fc/:pk/:ak
Method： DELETE
路径参数
| 参数名称 | 示例 | 备注 |
|---|---|---|
| fc | jagu79 | |
| pk | u2wdh3wm | |
| ak | 100000691930 |
返回数据
| 名称 | 类型 | 默认值 | 备注 | 其他信息 |
|---|---|---|---|---|
| result | string |
返回示例
{
"result":"OK"
}4.3 禁用设备(单个)
基本信息
Path： /v2/manage/device/:fc/:pk/:ak/disable
Method： PUT
路径参数
| 参数名称 | 示例 | 备注 |
|---|---|---|
| fc | jagu79 | |
| pk | u2wdh3wm | |
| ak | 100000691930 |
返回数据
| 名称 | 类型 | 是否必须 | 默认值 | 备注 | 其他信息 |
|---|---|---|---|---|---|
| result | string | 非必须 |
返回示例
{
"result": "OK"
}4.4 启用设备(单个)
基本信息
Path： /v2/manage/device/:fc/:pk/:ak/enable
Method： PUT
路径参数
| 参数名称 | 示例 | 备注 |
|---|---|---|
| fc | jagu79 | |
| pk | u2wdh3wm | |
| ak | 100000691930 |
返回数据
| 名称 | 类型 | 是否必须 | 默认值 | 备注 | 其他信息 |
|---|---|---|---|---|---|
| result | string | 非必须 |
返回示例
{
"result": "OK"
}4.5 获取设备信息(单个)
基本信息
Path： /v2/manage/device/:fc/:pk/:ak
Method： GET
路径参数
| 参数名称 | 示例 | 备注 |
|---|---|---|
| fc | simh9x | |
| pk | 84jysx5f | |
| ak | 0c572aef-3f38-4194-b347-177470873078 |
返回数据
| 名称 | 类型 | 是否必须 | 默认值 | 备注 | 其他信息 |
|---|---|---|---|---|---|
| accountUuid | string | 非必须 | |||
| fc | string | 非必须 | |||
| pk | string | 非必须 | |||
| ak | string | 非必须 | |||
| sk | string | 非必须 | |||
| state | string | 非必须 | |||
| createTime | string | 非必须 | |||
| updateTime | string | 非必须 |
返回示例
{
"accountUuid":"611f366b29f64d04ad2ed130d32835d2",
"fc":"8gt3x2",
"pk":"n806btcp",
"ak":"6bdca967-ff15-4c1c-8a1c-841269b43d27",
"sk":"mock",
"state":"ACTIVATED",
"createTime":"2020-03-23 06:39:53",
"updateTime":"2020-03-23 06:39:53"
}4.6 获取设备信息(列表)
基本信息
Path： /v2/manage/device
Method： GET
请求参数
| 参数名称 | 是否必须 | 示例 | 备注 |
|---|---|---|---|
| fc | 是 | simh9x | |
| pk | 是 | 84jysx5f | |
| state | 否 | BAN | enum: [NOT_ACTIVE, ACTIVATED, BAN] |
| order | 否 | DESC | enum: [desc, asc] |
| pageNo | 否 | 1 | |
| pageSize | 否 | 10 |
返回数据
| 名称 | 类型 | 是否必须 | 默认值 | 备注 | 其他信息 |
|---|---|---|---|---|---|
| totalCount | number | 非必须 | |||
| result | object [] | 非必须 | item 类型: object | ||
| ├─ accountUuid | string | 非必须 | |||
| ├─ fc | string | 非必须 | |||
| ├─ pk | string | 非必须 | |||
| ├─ ak | string | 非必须 | |||
| ├─ sk | string | 非必须 | |||
| ├─ state | string | 非必须 | |||
| ├─ createTime | string | 非必须 | |||
| ├─ updateTime | string | 非必须 | |||
| pageNo | number | 非必须 | |||
| pageSize | number | 非必须 | |||
| fc | string | 非必须 | |||
| fcName | string | 非必须 | |||
| pk | string | 非必须 | |||
| devSku | string | 非必须 | |||
| orderBy | string | 非必须 | |||
| order | string | 非必须 | |||
| state | string | 非必须 |
返回示例
{
"totalCount":1,
"result":[
{
"accountUuid":"611f366b29f64d04ad2ed130d32835d2",
"fc":"8gt3x2",
"pk":"n806btcp",
"ak":"6bdca967-ff15-4c1c-8a1c-841269b43d27",
"sk":"mock",
"state":"ACTIVATED",
"createTime":"2020-03-23 06:39:53",
"updateTime":"2020-03-23 06:39:53"
}
],
"pageNo":1,
"pageSize":10,
"fc":"8gt3x2",
"fcName":"hjt",
"pk":"n806btcp",
"devSku":"HB－QBT－1",
"orderBy":"createTime",
"order":"desc",
"state":"NOT_ACTIVE"
}返回示例
{
"token":"xxx.xxx.xxx"
}