PDF《深思云》

1 深思云 开发者中心 [开放接口 V2.

0] 北京深思数盾科技股份有限公司

2 更新历史 版本/状态 日期 备注 2.0.0 beta 2017.05.17 初稿 2.0.1 beta 2017.06.13 添加用户成功后,可区分出是否之前已在用户中心注册过 添加用户的接口修改支持使用手机号作为用户名 2.0.2 beta 2017.09.07 添加查询某用户已发许可的 API 添加发布软锁许可的 API 2.0.3 beta 2017.09.21 添加不依赖模板发布云锁或软锁许可的 API 添加用于更新(修改)已发的云锁或软锁许可的 API 2.0.4 beta 2017.09.28 添加标签管理相关 API 2.0.5 beta 2017.10.25 添加软锁查询相关 API 许可计次限制统一使用 counter 2.0.6 2018.11.15 添加授权码管理相关 API 2.0.7 2018.12.12 授权码生成、更新 API 支持高级属性设置 2.0.8 2019.01.10 云锁许可新增计费相关参数设置 2.0.9 2019.01.25 新增获取账号许可使用情况接口 2.0.10 2019.04.26 支持按照套餐发布许可,部分描述和限制更新(红色字体) 2.0.11 2019.05.29 新增授权码兑换接口

3 目录

一、 约定.5

1、 术语.5

2、 接口概述.5

3、 签名机制.6

4、 接口限制.9

二、 API 概览.9

三、 用户管理接口.10

1、 添加普通用户.10

2、 添加影子账号.11

3、 修改影子账号密码

12

4、 修改用户备注信息

13

5、 删除用户.13

6、 查找用户.14

四、 产品管理接口.15

1、 添加产品.15

2、 修改产品.16

3、 按照产品许可 ID 查找产品

17

4、 按照产品名称查找产品.18

5、 删除产品.19

五、 模板管理接口.20

1、 添加模板.20

2、 修改模板.22

3、 按照产品许可 ID 枚举模板

24

4、 按照模板编号查找模板信息.26

5、 删除模板.27

六、 套餐接口

28

1、 获取可用的许可套餐.28

七、 云许可(云锁/软锁许可)管理接口

29

1、 不依赖模板发布许可.29

2、 可修改许可策略的发布许可(不推荐使用,后续可能删除)31

3、 不可修改许可策略的发布许可

33

4、 更新(修改)已发许可.33

5、 删除许可.38

6、 搜索许可(许可颁发时的状态,并非当前使用中的状态)38

7、 获取指定的软锁许可的信息.41

8、 获取软锁许可的绑定机器信息

43

9、 获取指定的软锁许可的绑定历史信息(包含解绑信息)45

4

10、 获取具体机器的软锁许可的最新绑定(解绑)信息.46

11、 获取具体机器的软锁许可的绑定历史信息(包含解绑信息)48

12、 解绑软锁许可.49

13、 获取指定许可的当前使用状态

50

14、 获取账号许可使用情况.52

八、 硬件锁许可管理接口

55

1、 签发添加许可升级包.55

2、 签发更新许可升级包.57

3、 删除硬件许可升级包.60

4、 签发控制许可升级包.61

九、 授权码管理接口.63

15、 生成授权码

63

16、 更新授权码

66

17、 删除授权码

71

18、 搜索授权码

71

19、 获取授权码详情.74

20、 获取授权码的绑定列表.77

21、 兑换授权码

78

十、 标签管理接口.80

1、 添加标签.80

2、 修改标签.80

3、 删除标签.81

4、 按标签名称查找标签.81 十

一、 附录

82

1、 接口授权类 CODE 码.82

2、 产品及模板相关错误码.82

3、 用户错误码

82

4、 许可错误码

83 5

一、 约定

1、 术语 ? 普通用户:必须用邮箱或手机号作为登录账号,云平台全局可用,可使用不同开发者发布 的许可,此类账号可以在终端自助登录云平台的中间件来使用许可软件;

? 影子账号:账号由创建该账号的开发者管理,仅用于跟开发者自己的账号系统建立关联, 此类账号由开发者应用自己管理登录过程;

? licenseId:产品在深思云平台的产品许可 ID,取值范围为[1-(2^32-1)];

? 三区数据: 为开发者提供三个数据存储区域,可以存储任意数据: rom:在建产品或模板时可以写进去,在许可使用过程中不能修改,最大

65535 byte;

raw:在建产品或模板时可以写进去,在许可使用过程中可以修改,最大

65535 byte;

pub:在建产品或模板时可以写进去,在许可使用过程中不能修改,最大

65535 byte;

2、 接口概述 ? 请求结构: 服务接口地址为:https://openapi.senseyun.com/v2/sv/{$请求操作} 通信协议:HTTPS. 请求方法:仅支持HTTP POST 方法,接口调用时ContentType 必须设置成 application/json . 请求参数:每个接口地址中服务接入地址后边的代表请求的操作,以及每个操作都需要包 含的公共请求参数和指定操作所特有的请求参数. 字符编码:请求及返回结果都使用 UTF-8 字符集进行编码. 请求结构:JSON 返回结构:JSON 成功结果:HTTP 请求返回 2xx, 同时返回 json 中code 属性值为 0. 错误结果:当调用出现异常,HTTP 请求返回 4xx 或5xx,返回结构内容忽略. 如果为业务逻辑方面的错误, HTTP 请求仍返回 2xx,但返回 json 中code 属性值 为非

0 值,desc 属性值为错误说明. ? 公共参数: 公共请求参数: 需要将所有的公共请求参数放在 HTTP header 中: 参数名称 参数类型 是否必填 描述 SenseAppID 字符串 Y 在开发者网站登录后可以查看到 SenseAppID SenseTimestamp 字符串 Y

1970 年01 月01 日00 时00 分00 秒 起至现在的总毫秒数,和服务器相差 时间超过

30 分钟, API 将返回授权失 败;

SenseNonce 字符串 Y 唯一识别码,用于一段时间内防重放 ( 每次需传入不重复的值,例如UUID);

SenseSign 字符串 Y 用于安全验证的签名值,签名过程参 见

第三节

6 图一:查看 SenseAppID 和SecretID

3、 签名机制 ? 说明 用于验证调用者合法性,同时实现防重放、防篡改的安全机制. ? 签名过程 ResourceURI:请求地址中不包含参数部分,如/v2/sv/addUser;

BodyContent:请求中 POST 的JSON 格式内容: { userAccount : [email protected] , nickname : 张三 , passwd :

123456 } SenseSign = base64(hmac-sha256(SecretID,SenseTimestamp + +SenseNonce + + ResourceURI+ +BodyContent));

在以上 SenseSign 的表达式中: hmac-sha256:参见 RFC2104 定义,为了更安全,HASH 算法采用 sha256;

SecretID:表示 SecretID字符串的 UTF-8 字节数组;

SenseTimestamp:UTC 时间戳毫秒数字符串 UTF-8 字节数组;

SenseNonce:唯一随机数的 UTF-8 编码字节数组;

ResourceURI:表示 HTTP 所请求资源的 URI(统一资源标识符, 例如:/v2/sv/addUser)UTF-8 编码的字节数组;

BodyContent: POST 时BODY 中内容的 UTF-8 编码字节数组;

代码实例(以java 语言描述): 假设调用 addUser 接口,HTTP 请求内容如下: POST https://openapi.senseyun.com/v2/sv/addUser Header: SenseAppID = ab73d14ec3ab4a3a8275c90200f6e5d7 SenseTimestamp =

1490950471521 SenseNonce = 4a3a8275c90200fab73d14ec3ab6e5d7 SenseSign = rrkEBbMf8DaIrefRAcnDoDG/5lXmmBFE05rlopXAU4c= Body: { userAccount : [email protected] , nickname : 张三 , passwd :

123456 }

7 发起 HTTP 请求的具体代码示例: //SenseTimestampUTC 时间戳........