场景

场景操作，通俗来说就是一键操控多个设备，这种操控是极其有用的，比如：

我们可以定义一个 回卧室睡觉场景，回卧室的时候客厅内的电器都关闭，卧室灯打开并且调节到柔和低亮度模式，这样，我们就可以通过app一键操控所有电器设备，方便至极。

创建场景创建¶

场景内的任务是按照顺序执行的。每个app创建的场景模板不能超过20个。

请求¶

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

{
    "sceneName": "回家场景",
    "sceneTaskList": []
}

参数	必填	类型	说明
sceneName	是	string	场景名字
sceneTaskList	是	array	执行的任务，详细信息见下面内容

sceneTaskList 列表中通用参数说明：

参数	必填	类型	说明
desc	是	string	描述
cmsArgs	是	object	里面填写指令，比如 "raw":""，或者 "cmdId":1

场景支持以下操作，也就是 sceneTaskList 参数支持的内容：

WIFI 设备¶

可以针对不同设备进行配置，示例参数格式：

{
    "desc": "开电视",
    "cmdArgs": {
        "raw": "48070200010153"
    },
    "devTid": "third test-14-47-15",
    "ctrlKey": "xxz"
}

参数	必填	类型	说明
devTid	是	string	设备id
ctrlKey	是	string	设备ctrlKey

群组¶

要配置群组控制，首先要定义群组，参见设备分组，示例参数：

{
    "desc": "开客厅所有灯",
    "cmdArgs": {
        "cmdId": 1,
        "key1": "value"
    },
    "groupId": "123456789"
}

参数	必填	类型	说明
groupId	是	string	群组id

子设备¶

示例参数：

{
    "desc": "打开窗帘",
    "cmdArgs": {
        "cmdId": 1,
        "key1": "value"
    },
    "subDevTid": "sub-2016-08-17T20-21-42",
    "devTid": "third test-14-47-15",
    "ctrlKey": "xxx"
}

参数	必填	类型	说明
subDevTid	是	string	子设备id
devTid	是	string	网关设备id
ctrlKey	是	string	网关设备ctrlKey

延时¶

上面提到过，场景任务执行是按照顺序执行的，所以可以支持任务之间的延时操作，比如：延时4s再关闭灯泡，示例如下：

{
    "desc": "延时3s",
    "time": 3
}

参数	必填	类型	说明
time	是	int	要延时的时间，单位秒，最大支持1小时，范围也就是 [0-3600]

联动¶

联动说明，请参考联动设置。可以设置某个联动使其打开，或者关闭。比如：

定义了一个联动，打开卧室门则打开客厅灯；定义一个场景叫起夜模式，当执行起夜场景，才执行这个联动，因为白天我们不需要打开灯。示例如下：

{
    "desc": "联动",
    "iftttId": "123123123123",
    "enable": "ENABLE"
}

参数	必填	类型	说明
enable	是	string	ENABLE：启用，DISABLE：禁用

上面的任务类型可以组合起来，下面是一个组合起来的示例：

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

{
    "sceneName" : "回家场景",
    "sceneTaskList" : [
        // 组控操作
        {
            "desc":"开客厅所有灯",
            "cmdArgs" : {
                "cmdId" : 1,
                "key1" : "value"
            },
            "groupId":"123456789"
        },

        // 设备操作
        {
            "desc":"开电视",
            "cmdArgs" : {
                "raw": "48070200010153"
        },
            "devTid":"third test-14-47-15",
            "ctrlKey":"xxz"
        },

        // 子设备操作
        {
            "desc":"打开窗帘",
            "cmdArgs" : {
                "cmdId" : 1,
                "key1" : "value"
            },
            "subDevTid":"sub-2016-08-17T20-21-42",
            "devTid":"third test-14-47-15",
            "ctrlKey":"xxx"
        },

        // 延迟时间
        {
            "desc":"延时3s",
            "time": 3
        },

        // 联动使能
        {
            "desc":"联动",
            "iftttId" : "123123123123",
            "enable": "ENABLE"
        }
    ]
}

返回


< 201
   < {
    "sceneId" : "98e8b004-f288-4e81-ae31-fefec8457732",
    "sceneName" : "scene_fivth",
    "uid" : "10894587829",
    "sceneTaskList" : [
        {
            "devTid" : "2016-08-17T20-21-42",
            "ctrlKey" : "xxx",
            "taskId" :  "bc5a900a-195b-430c-94",
            "desc" : "开门",
            "cmdArgs" : {
                "cmdId" : 1,
                "power" : 1
            }
        },
        {
            "iftttId" : "effdd6a0-5b67-486b-8e14-fe6606d10c7d",
            "enable" : "ENABLE",
            "taskId" : "51658b37-c35a-437c-b5ae-24ddc011ed11",
            "desc" : "开启联动"
        },
        {
            "time" : 3,
            "taskId" : "148de23b-f528-4352-b814-9510c446a86b",
            "desc" : "延迟时间"
        }
    ],
    "createTime" : ISODate("2016-12-22T08:22:57.230Z")
  }

获取场景列表（包括系统默认）¶


curl -v -X GET \
        -H "Authorization: Bearer {JWT_TOKEN}" \
        -H "Accept: application/json" \
        "https://user-openapi.hekr.me/scene?scenceId=2b4df4b2-fd7b-4a7a-a519-6ecf7ced9ab9&sceneName=场景"

参数

参数名	是否可选	参数类型	取值范围	说明
sceneId	可选	String		场景ID ，多个用都好分隔
sceneName	可选	String		场景名称，完全匹配

sceneId和sceneName如果都填写，那么都会参与过滤，可能没法返回预期，建议只选择一个填写

返回



< 200
  < [
      {
        "sceneId":"2b4df4b2-fd7b-4a7a-a519-6ecf7ced9ab9"
        "uid" : xxx,
        "name" : "场景",
        "sceneTaskList": [
                {
                    "taskId": "7440ba09-2969-4303-86f6ed0",
                    "desc": "开客厅所有灯",
                    "cmdArgs": {
                        "cmdId": 2,
                        "power": 0,
                        "groupId": "123456789" // 如果是群组
                    },
                }
              ],
        "desc": 描述,
        "createTime": 1482135729797,
        "updateTime": null
      },
      ......
  ]

删除场景¶


curl -v -X DELETE \
        -H "Authorization: Bearer {JWT_TOKEN}" \
        "https://user-openapi.hekr.me/scene/{sceneId}"

参数

参数名	是否可选	参数类型	取值范围	说明
sceneId	必选	String		场景ID

返回


< 204
< No Content

场景更新¶


curl -v -X PATCH \
        -H "Authorization: Bearer {JWT_TOKEN}" \
        -H "Accept: application/json" \
        "https://user-openapi.hekr.me/scene/{sceneId}"
        -d '{
            "sceneName" : "回家场景",
            "sceneTaskList" : []
        }'

参数

参数名	是否可选	参数类型	说明
sceneId	必选	String	场景ID
sceneName	可选	String	场景名称,不能修改成除本身外已有的名称
sceneTaskList	必选	List	场景中需要执行的任务列表，参照创建场景说明

返回


< 204
< No Content

执行场景¶

执行场景需要通过 websocket 或者 tcp发送指令到云端，指令如下：

{
    "msgId": 112,
    "params": {
        "sceneId": "xxxxx",
        "action": "sceneTriggerSend"
    },
    "appTid": "xxxxxx"
}

参数	必填	类型	说明
sceneId	是	string	场景id
action	是	string	固定为 sceneTriggerSend
appTid	是	string	和app登录的时候传递的一样

返回：

{
    "msgId": 112,
    "action": "sceneTriggerSendResp",
    "code": 200,
    "desc": "success"
}

参数	类型	说明
code	int	200 正常，否则请查阅错误码
action	string	固定为 sceneTriggerSendResp
desc	string	错误描述

查询场景执行结果历史记录¶


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/sceneExecuteHistory?sceneId=xxx&sceneName=回家&result=true&startTime=2016-01-01T09:45:00.000+0800&endTime=2017-01-01T09:45:00.000+0800"

参数

参数名	是否可选	参数类型	取值范围	说明
sceneId	可选	String		场景ID
sceneName	可选	String		场景name
result	可选	Boolean	true/false	执行结果
startTime	必选	String	yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700	查询起始时间
endTime	可选	String	yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700	查询结束时间
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 20]	分页参数，默认为20

返回


< 200
< {
    "content": [
        {
        "objectId": {
            "time": 1490003369000,
            "timestamp": 1490003369,
            "date": 1490003369000,
            "timeSecond": 1490003369,
            "machine": -458185787,
            "inc": -1003867645,
            "new": false
        },
        "sceneId": "cc27ec7b-21a7-404c-b930-5da131",
        "uid": "xxxx",
        "origin": "DIRECT",
        "sceneTaskExecuteDetails": [
            {
            "sceneExecuteAck": "PENDING",
            "sceneId": "cc27ec7b-21a7-404c-b930-5da131",
            "sceneTaskId": "b7731ef7-7eef-4a71-b67f-49242225e219"
            },
            {
            "sceneExecuteAck": "PENDING",
            "sceneId": "cc27ec7b-21a7-404c-b930-5da19c66e331",
            "sceneTaskId": "2bd42bd9-6bac-4017-8bd2-3b49041ef17e"
            },
            ......
        ],
        "sceneName": "外出场景",
        "result": true,
        "executeTime": 1490003369443,
        "desc": "[scene execute Succeed]"
        }
    ],
    "last": false,
    "totalElements": 769,
    "totalPages": 769,
    "numberOfElements": 1,
    "sort": [
        {
        "direction": "DESC",
        "property": "executeTime",
        "ignoreCase": false,
        "nullHandling": "NATIVE",
        "ascending": false
        }
    ],
    "first": true,
    "size": 20,
    "number": 0
  }

场景触发¶

调用改接口执行场景。

GET https://user-openapi.hekr.me/sceneTrigger?sceneId=xxxxxxx HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

接口参数

参数	说明
sceneId	场景Id

HTTP/1.1 200 OK

错误码表¶

错误码	提示信息	中文释义	可能造成的原因
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	用户不存在	用户不存在
5400045		短码或者短码密码错误
5400046		短码不足（系统错误）
5400047		无权修改其他用户绑定设备
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调用失败