edit

第三方设备

第三方设备是指不是在氦氪云平台定制协议而生产的设备,比如萤石摄像头,小白机器人等。这些设备加入氦氪云,可以丰富操控设备的操作方式,增加互动体验,或者功能增强。比如小白机器人的接入,使得我们可以通过语音控制设备和场景,同时可以进行娱乐;萤石摄像头可以实时监控,同时配合氦氪云可以实现联动,比如开启外出模式,自动设防等等。

错误说明

所有错误都是http status code 非2xx,并可能包含了简要错误说明,这里简要重复介绍一下,其他错误参见 错误码。 注意,所有2xx的http status 都认为是成功的。

http status code code 说明
405 请求方法不允许,请使用正确的http method提交请求
400 缺失参数或者参数不正确
409 冲突,已经被绑定(自己或者别人)

第三方设备功能列表

设备类型

设备类型 说明
YS_CAMERA 萤石摄像头
GOWILD_ROBOT 机器人小白

功能类型

功能类型 说明
NORMAL 可以调用hekr云平台接口控制设备,也可以作为联动或者场景动作,但不能作为触发条件
ACTION 只可以作为联动或者场景动作
TRIGGER 只可以作为联动条件

功能列表

作用

主要是为了提供对场景和联动的支持,比如条件触发了,摄像头应该做什么动作,这些动作需要从列表中获取functionType为 ACTION的,然后将对应参数放到联动动作里面,具体参见联动。另外的功能是提供简单的控制接口,可以直接通过hekr云平台调用第三方设备的相关 控制接口,实现操作,而不需要调用sdk的功能。(暂时还没提供相应接口) 这列只列举 了常用功能,如果要获取所有功能列表,请使用下面的获取功能列表接口

设备类型 功能能名称 功能类型 中文说明 英文说明 参数
YS_CAMERA YS_CAMERA_CAPTURE NORMAL 捕捉图像 capture quality : STANDARD 标清, HIGH 高清
YS_CAMERA YS_CAMERA_DEFENCE_SET NORMAL 设置布防 set defence
YS_CAMERA YS_CAMERA_DEFENCE_UNSET NORMAL 撤销布防 unset defence
YS_CAMERA YS_CAMERA_PRESET_MOVE_CAPTURE NORMAL 调用预设点并拍照 invoke preset and capture index:预设点 1-12, quality : STANDARD 标清, HIGH 高清
YS_CAMERA YS_CAMERA_PRESET_MOVE NORMAL 调用预设点 invoke preset index:预设点 1-12

绑定萤石摄像头到hekr云平台

Request

POST https://user-openapi.hekr.me/device/third HTTP/1.1
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

{
    "devType":"YS_CAMERA",
    "params" :{
        "deviceSerial":"xxx",
        "validateCode":"xxx"
    }
}

参数

参数 必填 类型 说明
devType string enum (YS_CAMERA) 现在只有这一种 ,参见设备类型
params.deviceSerial string 萤石摄像头的序列号,在标签上
params.validateCode string 萤石摄像头的验证码,在标签上
params 的其他值 any 可以是任意类型数据

Response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

{
    "firstLoginTime": 1111111111,
    "devTid": "xxx", 
    "ctrlKey": "xxx", 
    "devType": "YS_CAMERA", 
    "params": { 
        "deviceSerial": "xxx",
        "validateCode": "xxx"
    },
    "ownerUid": "xxx"
}

参数

参数 类型 说明
firstLoginTime long 绑定时间
devTid string 跟常规设备含义一样
ctrlKey string 跟常规设备含义一样
owerUid string 设备绑定用户,也就是用户本身

其他参数参考上面 Request 中的说明

从hekr云平台解绑

Request

DELETE https://user-openapi.hekr.me/device/third/{devTid}?ctrlKey=xxx&randomToken=xxx HTTP/1.1
Authorization: Bearer {{JWT_TOKEN}}

参数

参数 必填 类型 说明
devTid string 设备id
ctrlKey string
randomToken string 强制删除标记

第一次的话,肯定是没有randomToken的,发起请求后,云端会进行校验,检查是否有联动和场景的绑定,如果没有,那么会直接进行删除,如果检查到有关联到场景或者联动的话,会返回一个randomToken,强制删除的话,需要携带这个标志。

直接删除 Response

HTTP/1.1 204 No Content
Content-Type: application/json;charset=UTF-8

如果检查到有关联到场景或者联动的话,会返回一个randomToken,强制删除的话,需要携带这个标志:

返回确认标识 Response

参见一般设备的删除返回信息

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8


{
    "randomToken":"1qazxsw23edcvfr4"
    "scenes":[
      {
        "sceneId":"222222222",
        "sceneName":"睡觉"
      }
    ]
    "ifttts":[
      {
        "ruleId":"1111111",
        "ruleName":"看电视"
      }
    ]
  }

根据 devTid 和 ctrlKey 获取设备(暂时不包括小白)

Request

GET https://user-openapi.hekr.me/device/third/{devTid} HTTP/1.1
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/x-www-form-urlencoded

参数

参数 必填 类型 说明
devTid string
ctrlKey string

Response

找不到则返回 404 ,错误码 6400004

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

    {
        "firstLoginTime": 1111111,
        "devTid": "xxxxx",
        "ctrlKey": "xxxx",
        "devType": "YS_CAMERA",
        "params": {
            "deviceSerial": "xxx",
            "validateCode": "xxx"
        },
        "ownerUid": "xxx"
    }

获取所有第三方设备列表

Request

GET https://user-openapi.hekr.me/device/third?devType=xx HTTP/1.1
Authorization: Bearer {{JWT_TOKEN}}

参数

参数 必填 类型 说明
devType string enum (YS_CAMERA,GOWILD_ROBOT) 如果填写,只返回匹配类型的设备列表,否则返回所有类型设备列表
devTid string 设备id
ctrlKey string 设备ctrlKey

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
    {
        "ownerUid": "18261814543",
        "name": "萤石测试用",
        "desc": null,
        "ctrlKey": "xxxx",
        "firstLoginTime": 1502264563348,
        "lastLoginTime": 1502264563345,
        "updateTime": 1506305448774,
        "devTid": "xx",
        "devType": "YS_CAMERA",
        "params": {
            "deviceSerial": "xx",
            "validateCode": "xx",
            "channelNo": 1,
            "channelName": "xx",
            "status": 1,
            "isShared": "0",
            "picUrl": "https://i.ys7.com/assets/imgs/public/homeDevice.jpeg",
            "isEncrypt": 1,
            "videoLevel": 2,
            "deviceName": "设备名字",
            "model": "CS-C2C-31WFR-B",
            "defence": 0,
            "alarmSoundMode": 0,
            "offlineNotify": 0,
            "pass": "xx"
        },
        "grantor": null,
        "authTime": null,
        "expireAt": null,
        "granted": true,
        "authType": "AUTH"
    }
]

萤石

parms 必定会有 deviceSerial 和 validateCode 这两个字段

小白

parms 必定会有 robotSN 这个字段

授权参数

参数 说明
grantor 授权者,如果该用户是设备的被授权者,那么这个字段就是设备属主的 uid
granted 如果设备被授权了,那么这个字段就是 true,否则 false
authType 如果设备跟当前用户的关系是属主,且该设备被授权了,那么就是 AUTH,如果是被授权,那么是 AUTHORIZED,否则是 null

获取第三方功能列表

Request

GET https://user-openapi.hekr.me/device/third/functions?devType=xx&functionType=xx HTTP/1.1
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/x-www-form-urlencoded

参数

参数 必填 类型 说明
devType string enum 参见上面设备类型 如果填写,只返回匹配类型的设备功能列表,否则返回所有类型设备列表
functionType string enum 参见上面功能类型,如果填写,只返回匹配类型的功能列表,否则返回所有类型设备列表

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
    {
        "name": "YS_CAMERA_CAPTURE",
        "devType": {
            "name": "YS_CAMERA",
            "lang": {
                "zh": "萤石摄像头",
                "en": "ezviz camera"
            }
        },
        "functionType": "ACTION",
        "lang": {
            "zh": "捕捉图像",
            "en": "capture"
        }
    }
]

参数

参数 类型 说明
name string enum 功能名字
devType string enum 参见上面设备类型
language.zh string 中文说明
langue.en string 英文说明
functionType string enum 参见上面功能类型

获取萤石(子账号的)token

Request

GET https://uaa-openapi.hekr.me/third/yingshi/token HTTP/1.1
Authorization: Bearer {{JWT_TOKEN}}

参数

无参

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "accessToken": "xxx",
    "expireTime": 1500432395798
}

参数

参数 类型 说明
accessToken string token
expireTime long 过期时间

控制第三方设备

Request

POST https://user-openapi.hekr.me/device/third/send HTTP/1.1
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

{
    "function":"xxxx",
    "data":{
        "a":"xx",
        "b":111
    }
}

参数

参数 必填 类型 说明
function string enum 功能名称,参见功能列表
data object 控制参数,比如要调用预设点,那么需要传递预设点的值,参见功能列表中的参数

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "success": true,
    "code":"200",
    "msg":"成功",
    "data":{
        "a":"xxxx"
    }
}

参数

参数 类型 说明
success bool 成功 true,否则false
code string 参见各个平台的接口返回
data object 参见各个平台的接口返回,参见第三方控制返回数据参数说明,这里是直接用的萤石返回结果

修改第三方设备信息

这个跟常规设备改名字基本一致,但是多了两个参数 paramsthirdDeviceType

Request

PATCH https://user-openapi.hekr.me/device/{devTid} HTTP/1.1
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

{
    "deviceName": "新的设备1",
    "desc": "新的设备描述",
    "thirdDeviceType": "YS_CAMERA",
    "params": {
        "a":"xxx",
        "b":122
    }
}

参数

参数 必填 类型 说明
devTid string
ctrlKey string
deviceName string 设备名字
thirdDeviceType string 设备类型,参见设备类型,如果不填写,则退化为常规设备的更新接口功能,如果要修改的是第三方设备,那么是必填。
params object 其他自定义参数,可以是数字,字符串类型。

Response

HTTP/1.1 204 No Content

联动支持

联动详细信息见这里

到目前为止,不支持萤石设备作为触发条件,只可以作为动作调用,动作支持列表参见上面的功能列表中ACTION标识的功能。

如果要创建第三方联动,那么需要在 iftttTasks 列表中的参数中增加 type 参数,并且为固定值 THIRD_SENDparams 参数中要增加function参数,值为功能列表中的ACTION类型的值。举例: 例子中的任务是当调用摄像头转动到指定预设点1,并且拍照。

{
    "devTid": "1_04b1d11b46ce9cc130af4c13f86d3",
    "ctrlKey": "6c4fc7fd146643668b2f204c1d8d04d0",
    "ruleName": "云台c6门磁关123",
    "iftttType": "CUSTOM",
    "condition": {
        "triggerType": "REPORT",
        "conDesc": "触发描述",
        "triggerParams": [
            {
                "left": "cmdId",
                "operator": "==",
                "right": 1
            },{
                "left": "power",
                "operator": "==",
                "right": 0
            }
        ]
    },
    "iftttTasks": [
        {
            "type": "THIRD_SEND",
            "desc":"测试拍照",  
            "params": {
                "ctrlKey": "f0f16e89b03d48fa9b39311eeef6a07e",
                "devTid":"fa5f146af9d74e5784340a3f929e6c65",
                "function": "YS_CAMERA_PRESET_MOVE_CAPTURE",
                "index":1
            }
        }
    ]
}

场景支持

如果要创建第三方场景,那么需要在 sceneTaskList 列表中的参数中增加 function 参数,值为功能列表中的ACTION类型的值。如果有其他参数,需要放到customParam 中,举例: 例子中的任务是当调用摄像头转动到指定预设点1,并且拍照。

{
    "sceneName": "测试",
    "sceneTaskList": [
        {
            "desc": "摄像头转动到预置点:门口",
            "function": "YS_CAMERA_PRESET_MOVE_CAPTURE",
            "devTid":"xx",
            "ctrlKey":"xx",
            "customParam":{
                "index":2
            }
        }
    ]
}

获取萤石摄像头拍照照片

hekr平台现在支持查看过往30天历史的照片。 注意:图片url在获取后5分钟内有效,失效后需要重新获取,以防止url泄露造成隐私泄露。

Request

GET https://user-openapi.hekr.me//device/third/ys/camera/images HTTP/1.1
Authorization: Bearer {{JWT_TOKEN}}

参数

参数 必填 类型 说明
devTid string 如果填写则ctrlKey也必填
ctrlKey string 如果devTid填写则ctrlKey也必填
startTime long 开始时间,timestamp(包含)
endTime long 结束时间时间,timestamp(不包含)
page int 当前页,[0,+)
size int 分页大小

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "content": [
        {
            "id": "5979cd8020133f7470e43ffd",
            "uid": "67527702614",
            "devTid": "e7bd5d32497c5aca3eae37b76d7864cb",
            "ctrlKey": "48779264489276d223a0a444fe199a6c",
            "url": "http://stage-allinone-ufile.hekr.me/ys-camera/51a65128-db2a-475f-ae0e-41e3faf69d9f.jpg",
            "createTime": 1501154688620
        }
    ],
    "last": true,
    "totalPages": 1,
    "totalElements": 1,
    "size": 20,
    "first": true,
    "number": 0,
    "sort": null,
    "numberOfElements": 1
}
参数 类型 说明
uid string 当前用户id
url string 图片地址,有效时间为5分钟
createTime long 拍照时间

分页信息和其他接口一样

录像存储到云端

授权

授权接口还是用独立设备授权的接口,详细说明如下。

正向授权(主动授权)

正向授权(主动授权)Request

POST https://user-openapi.hekr.me/authorization HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

{
"ctrlKey": [
    "89f089..."
],
"grantee": "3399...",
"expireAt": 1503479651538,
}

正向授权(主动授权)Reslonse

和独立设备授权一样

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "results": [
        {
            "ctrlKey": "89f089...",
            "result": "success"
        }
    ],
    "success": 1,
    "failure": 0
}

反向授权(请求授权)

反向授权(请求授权)创建授权链接(二维码) Request

POST https://user-openapi.hekr.me/authorization/reverse/authUrl HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

{
  "ctrlKey": [
      "89f089..."
  ],
  "expireAt": 1503479651538,
}

反向授权(请求授权)创建授权链接(二维码) Response

和独立设备一样

{
  "reverseAuthorizationTemplateId": "a48555e9e865424f9e5be1a8b2c618a0"
}

反向授权(请求授权)申请设备授权 Request

POST https://user-openapi.hekr.me/authorization/reverse/register?reverseTemplateId={reverseTemplateId} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

反向授权(请求授权)申请设备授权 Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

错误码表

错误码 提示信息 中文释义 可能造成的原因
5200000, 620000 Success 成功
5400000 Error 未知错误 该行下面的以5400、6400开头的错误码需要单独处理
5400002 App repeat login error app重复登录 同一个appTid的app重复登录
5400003 appTid can not be empty appTid不能为空 appTid不能为空
5400004 Authorization already exists 授权关系已存在 授权关系已存在
5400005 Authorization does not exist 授权关系不存在 授权关系不存在
5400006 Bind failed due to network error 因网络原因绑定失败 因网络原因绑定失败
5400007 Bind failed due to timeout error 因超时原因绑定失败 因超时原因绑定失败
5400008 Can not bind other manufacture's device 无法绑定其他厂商设备 非公版用户无法绑定非该pid设备
5400009 Modified user profile failed 修改用户档案失败 修改用户档案失败
5400010 Check verify code error 校验code失败 校验code失败
5400011 You have reached your device's authorization limits 设备授权次数达到上限 设备授权次数达到上限,无法再次授权
5400012 Bind failed due to internal error 因内部错误绑定失败 因内部错误绑定失败,一般是因为bindKey不对或者是devTid不对
5400013 Bind failed due to repeat bind 因重复绑定绑定失败 因重复绑定绑定失败
5400014 Device does not belong to user 设备不属于用户 设备不再属于该用户
5400015 No such instruction error 没有这样的指令 没有这样的指令
5400016 Device can not repeat login 设备无法重复登录 设备无法同时登录
5400017 devTid can not be empty devTid不能为空 devTid不能为空
5400018 Create timer task failed due to counts reach limit 创建定时预约次数达到上限 创建定时预约次数达到上限
5400019 Instruction expired 授权的指令已过期 授权的指令已过期
5400020 Instruction not support 不支持该指令 不支持该指令,可能是指令填错了
5400021 Invalid email token 不合法的邮件token 不合法的邮件token
5400022 Invalid old password 不合法的旧密码 不合法的旧密码
5400023 Invalid verify code 不合法的校验code 不合法的校验code
5400024 Device does not found due to internal error, please reconnect 由于内部错误设备无法找到,请重连
5400025 No such manufacture id 不存在该pid 不存在该pid
5400026 No permission to access the instruction 没有对该指令的权限 没有对该指令的权限
5400027 Template with given id does not exist 指定模板不存在 指定模板不存在
5400028 Device does not found due to incorrect status 由于内部不正确的状态导致设备无法被找到
5400035 TaskId does not exist 指定任务不存在 指定任务不存在
5400036 Can not create duplicate template 无法创建重复模板 无法创建重复模板
5400037 devTid not match 设备id 不匹配 报文填写的devTid与登录设备的devTid不一致
5400039 User does not exist 用户不存在 用户不存在
5400043 Device can not force bind 设备无法强制绑定 设备无法强制绑定
5500000 Internal error 内部错误 内部服务错误
6400001 Reverse auth template with given id does not exist 指定id的反向注册申请不存在 请求已经被同意或拒绝
6400002 Invalid reverse authorization request 不合法的反向授权请求 设备此时已经不属于该授权者;调用者不是授权者;反向授权请求id错误
6400003 Only owner can authorize 只有属主可以授权设备给其他人 非属主尝试授权设备给其他人
6400004 Device with given devTid does not exist 指定devTid的设备不存在 操作不存在的设备
6400005 Reached the maximum number of device the folder can hold 达到文件夹所能容纳设备数量的上限 达到文件夹所能容纳设备数量的上限
6400006 Can not create duplicate template folder 无法创建同名文件夹 创建同名文件夹
6400007 Folder with given id does not exist 指定id的文件夹不存在 操作不存在的文件夹
6400008 Reached the maximum number of folder the user can create 达到创建文件夹数量上限 达到创建文件夹数量上限
6400009 Can not remove root folder 无法删除根目录 删除根目录
6400010 Can not rename root folder 无法给根目录改名 给根目录改名
6400011 Rule with given id does not exist 指定的规则不存在 操作不存在的规则
6400012 Scheduler task with given id does not exist 指定的定时预约任务不存在 操作不存在的定时预约任务
6400013 Can not create duplicate rule 无法创建相同的规则 创建相同的规则
6400014 Can not create duplicate scheduler task 无法创建相同的定时预约 创建相同的定时预约
6400015 Invalid prodPubKey 不合法的产品公共秘钥 不合法的产品公共秘钥
6400016 Has no privilege do that 没有权限这样做 操作没有权限
6400017 Invalid Param {0} 参数错误 请求参数错误
6400018 Cloud storage file with given name does not exist 指定的网盘文件不存在 操作不存在的网盘文件
6400020 Can not find this infrared code 找不到这个红外码 操作不存在的红外码
6400021 Infrared code request without response 红外服务请求出错
6400022 Can not find instruction set 无法找到指令集 操作不存在的指令集
6400023 Request params not supported 参数不支持 请求参数错误
6400024 Translating Json to String failure 解析json失败
6400025 Scheduler not supported 不支持定时预约 该设备不支持定时预约功能
6500001 Delete cloud storage file failed 删除网盘文件失败 网盘操作失败
6500002 Upload cloud storage file failed 上传网盘文件失败 网盘操作失败
6500003 Server use httpClient invoke failed http网络调用失败 http调用失败