SCICALA 霜蝉云 接口使用说明 版本 :V1.01 [No.SC700003SS1] 上海霜蝉信息科技有限公司 Shanghai Scicala Information Technology Co.,Ltd 网址 : www.scicala.com Email:support@scicala.com 电话 : 021-60780743 1
免责申明和版权公告 本文中的信息, 包括供参考的 URL 地址, 如有变更, 恕不另行通知 本文档 按现状 提供, 不负任何担保责任, 包括对适销性 适用于特定用途或非侵权性的任何担保, 和任何提供 规格或样品在他处提到的任何担保 本文档不负任何责任, 包括使用本文档内信息产生的侵犯任何专利权行为的责任 本文档在此未以禁止发言或其他方式授权任何知识产权使用许可, 不管是明示许可还是暗示许可 文中提到的所有商标名称 商标和注册商标均属其各自所有者的财产, 特此声明 版权归 @2017 上海霜蝉信息科技有限公司所有 保留所有权利 2
目录 一 产品概述... 4 二 接口功能... 4 三 调用规范... 4 四 接口方法... 5 4.1.TCP 方式调用说明... 5 4.1.1. 用户订阅 Subscribe (uname,upassword)... 5 4.1.2. 取消订阅 UnSubscribe(identity,key)... 5 4.1.3. 绑定设备 DBind(deviceid, authcode,dname,compwd,key)... 6 4.1.4. 解绑设备 UnDBind(deviceid,key)... 6 4.1.5. 获取设备列表 GetDevList (deviceid,key)... 7 4.1.6. 更新设备信息 UpdateDevInfo (deviceid, dname, compwd,key)... 7 4.1.7. 发送数据 AppSend(deviceid, identity, key, message)... 8 4.1.8. 接收数据 ReceiveMessage()... 9 4.1.9. 用户注册 UseRegist (email, password, key)... 9 4.1.10. 查询设备状态 DevStatusQuery (deviceid, key)... 9 4.1.11. 查询设备信息 GetQueryInfo (deviceid, qtype, key)... 10 4.2.HTTP 方式调用说明... 11 4.2.1. 用户订阅 Subscribe (uname,upassword)... 11 4.2.2. 取消订阅 UnSubscribe(identity,key)... 11 4.2.3. 绑定设备 DBind(deviceid, authcode,dname,compwd,key)... 12 4.2.4. 解绑设备 UnDBind(deviceid,key)... 13 4.2.5. 获取设备列表 GetDevList (identity,key)... 14 4.2.6. 更新设备信息 UpdateDevInfo (deviceid, dname, compwd,key)... 14 4.2.7. 发送数据 AppSend(deviceid, identity, key, message)... 15 4.2.8. 接收数据 ReceiveMessage(deviceid,key)... 16 4.2.9. 用户注册 UseRegist (email, password, key)... 16 4.2.10. 查询设备状态 DevStatusQuery (deviceid, key)... 17 3
一 产品概述 SCloudAPI 接口 ( 简称 SCA 接口 ) 是 SCICALA 霜蝉云面向设备厂商 开发者, 解决设备与上位机 (Android IOS PC) 之间相互通信, 提供数据服务的载体 二 接口功能 该接口主要包括用户订阅 取消订阅 绑定设备 设备解绑 编辑设备信息, 获取设备状态 发送数据 接收数据 注册用户 查询设备信息等功能 三 调用规范 规范用于指导三方合作伙伴正确调用接口进行数据传输 TCP 调用 URL:net.tcp:// cloud.scicala.com:10112/mex HTTP 调用 URL:http://cloud.scicala.com:10113/ SCloudAPI HTTPS 调用 URL:https://cloud.scicala.com:10114 数据返回 : json 4
四 接口方法 4.1.TCP 方式调用说明 4.1.1. 用户订阅 Subscribe (uname,upassword) 创建连接, 申请控制密钥 输入参数 : 参数名称 参数含义 参数样例 uname 用户名 / 邮箱 Guest upassword 密码 123456 "action" : "ressubscribe ", "state" :"1", "identity":"71d029e8 0c67 407a af9f 63065d005808", "key":"0cc175b9c0f1b6a831c399e269772661" // 身份 id // 密钥 返回值 : 订阅状态 state key( 密钥 ) 1 订阅成功 0 订阅失败 4.1.2. 取消订阅 UnSubscribe(identity,key) 断开连接输入参数 : identity string 身份 ID 71d029e8 0c67 407aaf9f 63065d005808 0cc175b9c0f1b6a83 1c399e269772661 "action" : " resunsubscribe ", "state":"1" 5
返回 : 状态 state 1 取消订阅成功 0 取消订阅失败 4.1.3. 绑定设备 DBind(deviceid, authcode,dname,compwd,key) deviceid string 设备 ID WES123456789ABCD authcode string 设备授权码 A1B1C1D1 dname string 设备名称自定义 compwd string 通信密码 (8 位通信密码 ) 12345678 private_key, 通 过特殊加密算法生成 ) 0cc175b9c0f1b6a83 1c399e269772661 "action" : "resdbind", "state":"1", 返回 : 绑定状态 state 1 设备绑定成功 0 设备绑定失败 1 设备绑定关系已存在 2 授权码错误 3 非法设备 4.1.4. 解绑设备 UnDBind(deviceid,key) deviceid string 设备 ID WES123456789ABCD 0cc175b9c0f1b6a83 1c399e269772661 6
"action" : "resundbind", " state":"1", 返回 : 解绑状态 state 1 设备解绑成功 0 设备解绑失败 1 解绑设备不属于用户 2 解绑设备不存在 4.1.5. 获取设备列表 GetDevList (deviceid,key) 参数名称参数含义参数样例 identity 身份 ID 71d029e8 0c67 407a af9f 63065d005808 key 密钥 ( 由订阅产生的 0cc175b9c0f1b6a831c39 9e269772661 查询单个设备状态时, 填写需要查询的设备 ID, 查询所有设备, 设备 ID 不填 ; "action":"resgetdevlist", " state":"1", "data" : "deviceid" : "WE8SAB1647003211", // 设备 ID "name":"sc8201", // 设备名称 "state":"1" // 设备状态, 返回 : 状态 state 1 获取设备列表成功 0 获取设备列表失败 4.1.6. 更新设备信息 UpdateDevInfo (deviceid, dname, compwd,key) 参数名称参数含义参数样例 7
deviceid 设备 ID WES123456789ABCD dname 设备名称自定义 compwd 通信密码 (8 位通信密码 ) 12345678 key 密钥 ( 由订阅产生的 0cc175b9c0f1b6a831c39 9e269772661 用于更改设备名称和通讯密码等信息, " action" : " resupdatedevinfo", "state":"1", 返回 : 更新状态 state 状态值 状态信息 1 设备信息更新成功 0 设备信息更新失败 1 设备设备 ID 错误 2 密钥错误 4.1.7. 发送数据 AppSend(deviceid, identity, key, message) deviceid string 设备 ID WES123456789ABCD identity string 身份 ID 71d029e8 0c67 407aaf9f 63065d005808 private_key, 通过特殊 0cc175b9c0f1b6a83 1c399e269772661 加密算法生成 ) message string 消息数据 scicala cloud "action" : "resappsend", state : "1 ", 返回 : 发送状态 state 1 发送成功 0 发送失败, 设备离线 8
4.1.8. 接收数据 ReceiveMessage() 实现回调函数 ReceiveMessage 接收设备发来的数据, 接收查询设备信息返回的数据 "did" : "WE8SAB1647000001", "action" : "resdevsend", "data": "31 32 33 34 35 36 37 38 39", state : "1 ", // 设备 id // 消息 / / 状态 4.1.9. 用户注册 UseRegist (email, password, key) email string 邮箱 Xiaoxi@qq.com password string 密码 123456 0cc175b9c0f1b6a 831c399e2697726 61 "action" : "resuseregist", "state":"1" 返回 : 注册状态 state 1 注册成功 0 注册失败 1 邮箱已被注册 2 错误的邮箱 4.1.10. 查询设备状态 DevStatusQuery (deviceid, key) 参数名称 参数类型 参数含义 参数样例 deviceid string 设备 Id WE8SAB1647000001 9
0cc175b9c0f1b6a 831c399e2697726 61 可以用于查询设备串口信息 电量等, 如果接了 GPS 还可以查询设备当前位置信息 "action" : "resdevstatusquery", " deviceid ":" WE8SAB1647000001", // 设备 id " dstatus":1, // 设备状态 "state":"1", // 执行状态 返回 : 查询状态 state 1 查询成功 0 查询失败 1 查询失败, 设备未绑定 4.1.11. 查询设备信息 GetQueryInfo (deviceid, qtype, key) deviceid string 设备 Id WE8SAB1647000001 qtype int 查询信息类型 如串口信息 :1 0cc175b9c0f1b6a 831c399e2697726 61 可以用于查询设备串口信息 电量等, 如果接了 GPS 还可以查询设备当前位置信息 "action" : "resquery", "state":"1" 返回 : 查询状态 state 1 查询成功 0 查询失败 10
1 查询失败, 设备未绑定 2 查询失败, 设备不存在 4.2.HTTP 方式调用说明 4.2.1. 用户订阅 Subscribe (uname,upassword) 创建连接, 申请控制密钥 URL: http://cloud.scicala.com:10113/scloudapi/subscribe?uname=uname&upasswor d=upassword HTTP 方法 :GET 输入参数 : 参数名称 参数含义 参数样例 uname 用户名 / 邮箱 Guest upassword 密码 123456 注意 : 身份 id 每次请求都会变, 密钥是不会变的 ( 每个用户只能申请一个密钥 ) "action" : "ressubscribe ", "state" :"1", "identity":"71d029e8 0c67 407a af9f 63065d005808", // 身份 id "key":"0cc175b9c0f1b6a831c399e269772661" // 密钥 返回值 : 订阅状态 state key( 密钥 ) 1 订阅成功 0 订阅失败 4.2.2. 取消订阅 UnSubscribe(identity,key) 断开连接 11
URL: http://cloud.scicala.com:10113/scloudapi/unsubscribe?identity=identity&key =KEY HTTP 方法 :GET 输入参数 : identity string 身份 ID 71d029e8 0c67 407aaf9f 63065d005808 0cc175b9c0f1b6a83 1c399e269772661 "action" : " resunsubscribe ", "state":"1" 返回 : 状态 state 1 取消订阅成功 0 取消订阅失败 4.2.3. 绑定设备 DBind(deviceid, authcode,dname,compwd,key) 用于用户绑定设备 URL: http://cloud.scicala.com:10113/scloudapi/dbind?deviceid=deviceid&authcode =AUTHCODE&dname=DNAME&compwd=COMPWD&key=KEY HTTP 方法 :GET 输入参数 deviceid string 设备 ID WES123456789ABCD authcode string 设备授权码 A1B1C1D1 dname string 设备名称自定义 compwd string 通信密码 (8 位通信密码 ) 12345678 private_key, 通 过特殊加密算法生成 ) 0cc175b9c0f1b6a83 1c399e269772661 12
"action" : "resdbind", "state":"1", 返回 : 绑定状态 state 1 设备绑定成功 0 设备绑定失败 1 设备绑定关系已存在 2 授权码错误 3 非法设备 4.2.4. 解绑设备 UnDBind(deviceid,key) 用于解绑已绑定设备 URL: http://cloud.scicala.com:10113/scloudapi/undbind?deviceid=deviceid&key=k EY HTTP 方法 :GET 输入参数 deviceid string 设备 ID WES123456789ABCD 0cc175b9c0f1b6a83 1c399e269772661 "action" : "resundbind", " state":"1", 返回 : 解绑状态 state 1 设备解绑成功 0 设备解绑失败 1 解绑设备不属于用户 2 解绑设备不存在 13
4.2.5. 获取设备列表 GetDevList (identity,key) 用于获取用户绑定的设备列表 URL: http://cloud.scicala.com:10113/scloudapi/getdevlist?identity=identity&key= KEY HTTP 方法 :GET 输入参数 参数名称参数含义参数样例 identity 身份 ID 71d029e8 0c67 407a af9f 63065d005808 key 密钥 ( 由订阅产生的 0cc175b9c0f1b6a831c39 9e269772661 查询单个设备状态时, 填写需要查询的设备 ID, 查询所有设备, 设备 ID 不填 ; "action":"resgetdevlist", " state":"1", "data" : "deviceid" : "WE8SAB1647003211", // 设备 ID "name":"sc8201", // 设备名称 "state":"1", // 设备状态 0: 离线,1: 在线 "compwd":"12345678" // 设备通讯密码, 返回 : 状态 state 1 获取设备列表成功 0 获取设备列表失败 4.2.6. 更新设备信息 UpdateDevInfo (deviceid, dname, compwd,key) 用户修改设备名称, 通讯密码等信息 URL: http://cloud.scicala.com:10113/scloudapi/updatedevinfo?deviceid=deviceid& newname=newname&commpwd=commpwd&key=key HTTP 方法 :GET 14
输入参数 参数名称参数含义参数样例 deviceid 设备 ID WES123456789ABCD newname 设备名称自定义 commpwd 通信密码 (8 位通信密码 ) 12345678 key 密钥 ( 由订阅产生的 0cc175b9c0f1b6a831c39 9e269772661 " action" : " resupdatedevinfo", "state":"1", 返回 : 更新状态 state 1 设备信息更新成功 0 设备信息更新失败 1 设备设备 ID 错误 2 密钥错误 4.2.7. 发送数据 AppSend(deviceid, identity, key, message) 用于给设备发送数据 URL: http://cloud.scicala.com:10113/scloudapi/appsend HTTP 方法 :POST 注意 :Content-Type: application/json 示例 deviceid : WES123456789ABCD, identity : 订阅时返回的身份 id, key : 订阅时返回的 key 值信息, message : 您要发送的数据 输入参数 deviceid string 设备 ID WES123456789ABCD identity string 身份 ID 71d029e8 0c67 407aaf9f 63065d005808 private_key, 通过特殊 0cc175b9c0f1b6a83 1c399e269772661 加密算法生成 ) message string 消息数据 scicala cloud message 为 16 进制数据时以十六进制发送 为非十六进制时以字符串发送 15
"action" : "resappsend", state : "1 ", 返回 : 发送状态 state 1 发送成功 0 发送失败, 设备离线 4.2.8. 接收数据 ReceiveMessage(deviceid,key) 用于获取设备回传的数据 URL: http://cloud.scicala.com:10113/scloudapi/receivemessage?deviceid=deviceid &key=key HTTP 方法 :GET 输入参数 deviceid string 设备 ID WES123456789ABCD 0cc175b9c0f1b6a83 1c399e269772661 "did" : "WE8SAB1647000001", "action" : "resdevsend", "data": "31 32 33 34 35 36 37 38 39", state : "1 ", // 设备 id // 消息 / / 状态 4.2.9. 用户注册 UseRegist (email, password, key) 通过接口注册用户 URL: http://cloud.scicala.com:10113/scloudapi/useregist HTTP 方法 :POST 注意 :Content-Type: application/json 16
示例 email : xxxx@qq.com, password : 123456, key : 订阅时返回的 key 值信息 输入参数 email string 邮箱 Xiaoxi@qq.com password string 密码 123456 0cc175b9c0f1b6a 831c399e2697726 61 "action" : "resuseregist", "state":"1" 返回 : 注册状态 state 1 注册成功 0 注册失败 1 邮箱已被注册 2 错误的邮箱 4.2.10. 查询设备状态 DevStatusQuery (deviceid, key) 用于查询设备是否在线 URL: http://cloud.scicala.com:10113/scloudapi/devstatusquery?deviceid=deviceid &key=key HTTP 方法 :GET 输入参数 deviceid string 设备 Id WE8SAB1647000001 0cc175b9c0f1b6a 831c399e2697726 61 可以用于查询设备串口信息 电量等, 如果接了 GPS 还可以查询设备当前位置信息 17
"action" : "resdevstatusquery", " deviceid ":" WE8SAB1647000001", // 设备 id " dstatus":1, // 设备状态 0: 离线,1: 在线 "state":"1", // 执行状态 返回 : 查询状态 state 1 查询成功 0 查询失败 1 查询失败, 设备未绑定 18