联动

联动，又称联动规则或者IFTTT（IF-THIS-THEN-THAT）。通俗的讲就是可以设置触发条件，然后当满足这个条件的时候，就执行一系列动作。比如：光线弱的情况下打开客厅门的时候，自动打开客厅的灯，有没有感觉非常方便。

氦氪云提供的IFTTT服务则结合了软服务和硬件服务。用户可以对自己的设备添加IFTTT规则，扩展了硬件设备原来单一的功能，同时增加生活中的便捷和乐趣。

添加IFTTT规则¶

IFTTT 功能执行需要两个核心组件：触发条件 和 执行任务

请求参数基本格式：

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

{
        "ruleName" : "新建联动",
        "conditionList" : [
        {
            "devTid" : "xxx",
            "ctrlKey" : "xxx",
            "subDevTid": "xxx"
            "conDesc" : "触发条件描述"
            "triggerParams" : [
              {
                "left" : "_cmdId",
                "operator" : "==",
                "right": 10
              },
              {
                "left" : "_cloudTime",
                "operator" : "==",
                "right" : "0 15 10 * * ? 2016"
              },
              ......      
            ]
        },
        .....
        ],
        "conditionLogic": "OR",
        "triggerType" : REPORT,
        "iftttTasks" : [],
        "desc" : "xxxxxx"
        "pushMsg": {
            "pushEnable": true,
            "isAlarm": true,
            "pushTemplateId": "00000000012"
        },
        "iftttType":"CUSTOM",
        "cronExpr" : "0 15 10 * * ? 2016",
        "timeZoneOffset" : 480
    }

触发条件¶

设备上报¶

WIFI，网关和子设备上报相关数据作为条件

时间¶

可以使用定时器作为触发条件。

执行任务¶

执行任务的参数只能是下发帧。

curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttRule" \
    -d '{
        "ruleName" : "新建联动",
        "conditionList": [
            {
                "devTid": "bd6ff14367ec44e8a2a408bff9b333aa",
                "ctrlKey": "a729a084e7014f8cb47c192fb95cf886",
                "subDevTid": "005043c903375c3f",
                "triggerParams": [
                    {
                        "left": "cmdId",
                        "right": 1,
                        "operator": "=="
                    },
                    {
                        "left": "devStatus",
                        "right": "0",
                        "operator": "=="
                    }
                ],
                "conDesc": "检测状态:未检测到人",
                "customFields": {
                    "mid": "xxxxx",
                    "devName": "xxxxxx",
                    "devLogo": "xxxxx"
                }
            },
            {
                "devTid": "bd6ff14367ec44e8a2a408bff9b333aa",
                "ctrlKey": "a729a084e7014f8cb47c192fb95cf886",
                "subDevTid": "005043c90336828e",
                "triggerParams": [
                    {
                        "left": "cmdId",
                        "right": 1,
                        "operator": "=="
                    },
                    {
                        "left": "devStatus",
                        "right": "0",
                        "operator": "=="
                    }
                ],
                "conDesc": "检测状态:未检测到人",
                "customFields": {

                }
            }
        ],
        "triggerType": "REPORT",
        "conditionLogic": "AND",
        "iftttTasks" : [
            {
                "type": "APPSEND",
                "params": {
                    "devTid": "2016-08-17T20-21-42",
                    "ctrlKey": "54308a73b0b34911a14206b8baaba57f",
                    "desc" : "开灯"
                    "data": {
                        "raw": "48070200010153"
                    }
                },
                "desc":"",
                "customParam": {}
            },
            {
                "type": "APPSUBSEND",
                "params": {
                    "devTid": "2016-08-17T20-21-42",
                    "ctrlKey": "54308a73b0b34911a14206b8baaba57f",
                    "desc" : "开灯"
                    "data"：{
                        "cmdId" : 1,
                        "key1" : "value"
                    }
                },
                "desc":"",
                "customParam": {}

            },
            {
                "type": "APPGROUPSEND",
                "params": {
                    "groupId":"123123",
                    "desc" : "开客厅灯"
                    "data"：{
                        "cmdId" : 1,
                        "key1" : "value"
                    }
                },
                "desc":"",
                "customParam": {}
            },
            {
                "type": "SCENETRIGGERSEND",
                "params": {
                    "sceneId":"123123",
                    "desc" : "执行场景"
                    "data"：{
                        "cmdId" : 1,
                        "key1" : "value"
                    }
                },
                "desc":"",
                "customParam": {}
            },
            {
                "type": "ENABLEIFTTT",
                "desc" : "开启联动"
                "params": {
                    "iftttId":"123123123",
                    "enable":"enable\disable"
                },
                "customParam": {}
            },
            {
                "type": "DALAYTIME",
                "desc" : "延时执行"
                "params": {
                    "time":"10"
                },
                "customParam": {}
            }
        ],
        "desc" : "xxxxxx"
        "pushMsg": {
            "pushEnable": true,
            "isAlarm": true,
            "pushTemplateId": "00000000012"
        },
        "iftttType":"CUSTOM",
        "cronExpr" : "0 15 10 * * ? 2016",
        "timeZoneOffset" : 480
    }'

参数

参数名	是否可选	参数类型	取值范围	说明
ruleName	必选	String	长度[1, 128]	规则名称
conditionList	必选	List		联动触发条件集合
triggerType	enum	SCHEDULER, REPORT	触发类型（定时触发，上行指令触发）
conditionLogic	enum	AND, OR	多条件触发时，多条件之间的逻辑关系
iftttTasks	必选	List		联动执行action列表
desc	可选	String	长度[1, 128]	联动描述
pushMsg	可选	PushMessage		推送信息
iftttType	必选	enum	SECURITY_ALARM,DEPLOY,MORNING_ALARM,DOOR_BELL,CUSTOM	联动类型
cronExpr	可选	cron_expr		启动时间cron表达式,联动执行时间段
timeZoneOffset	必选	String	[-720, 720]	时区偏移，请注意javascript中获取的东八区时区偏移为-480，该处需要填写480

TriggerCondition参数说明

参数名	参数类型	取值范围	说明
devTid	必选	String
ctrlKey	必选	String
subdevTid	可选	String
triggerParams	List		触发表达式参数列表
conDesc	String	长度[1, 128]	触发条件描述
customFields	Map		自定义参数集合，可以插入自定义key-value

TriggerParam 参数说明

参数名	参数类型	取值范围	说明
left	String		条件表达式左边参数
right	String		条件表达式右边参数
operator	String	">", "<", "==", "in"	条件表达式运算符

PushMessage 参数说明
目前联动推送暂不支持自定推送内容，故只需填入是否推送参数即可

参数名	参数类型	说明
pushEnable	boolean	是否推送
isAlarm	boolean	是否是告警推送（推送无需参数）
pushTemplateId	String	推送模板ID（推送无需参数）
pushParams	List	推送模板参数（推送无需参数）

参数提交说明

触发条件参数为定时触发，则参数right必须为cron表达式且云端会对cron表达式触发频率进行校验，触发过于频繁的表达式会被禁止创建(每5分钟触发一次为阈值)
IFTTTTask参数说明:
1> type : 为字符串String 取值 [appSend(设备控制),appSubSend（子设备控制）,appGroupSend（组控）,sceneTriggerSend（场景）,enableIFTTT（联动使能开关）,delayTime（延时时间）]
2> params: 根据type的不同所传参数也不一样，对应关系如，上边创建参数所示
PushMessage参数说明： 1> pushParams推送基本参数已添加，故录入时暂时不用添加该参数.

返回

< 201
< {
        "uid": "1111111111",
        "pid": "00000000000",
        "ruleId": "fdbe4a9c5a91464393342c63119ec028",
        "ruleName": "禁用灯",
        "iftttType": "CUSTOM",
        "conditionList": [
            {
                "devTid": "xxxxxxxxxx",
                "ctrlKey": "xxxxxxxxxx",
                "subDevTid": "xxxxxxxxx",
                "triggerParams": [
                    {
                        "left": "cmdId",
                        "right": "1",
                        "operator": "=="
                    },
                    {
                        "left": "devStatus",
                        "right": "1",
                        "operator": ">"
                    }
                ],
                "conDesc": "检测状态:检测到人",
                "customFields": {
                    "devName": "xxxxx",
                    "devPpk": "xxx+xx+xx",
                    "mid": "xxxxxx"
                }
            },
            {
                "devTid": "ESP_2M_xxxxxxxx",
                "ctrlKey": "01xxxxxxxxxxxxx",
                "subDevTid": "xxxxxxxxxx",
                "triggerParams": [
                    {
                        "left": "cmdId",
                        "right": "1",
                        "operator": "=="
                    },
                    {
                        "left": "devStatus",
                        "right": "1",
                        "operator": "=="
                    }
                ],
                "conDesc": "检测状态:检测到人",
                "customFields": {}
            }
        ],
        "triggerType": "REPORT",
        "conditionLogic": "OR",
        "iftttTasks": [
            {
                "type": "SCENETRIGGERSEND",
                "params": {
                    "ctrlKey": "SCENETRIGGERSEND",
                    "devTid": "SCENETRIGGERSEND",
                    "sceneId": "xxxxxxxx"
                },
                "desc": "执行场景",
                "customParam": {
                    "devLogo": "",
                    "devName": "禁用无人关灯251709",
                    "devPpk": ""
                },
                "taskId": "00a0efa00c69445aa25d633f813aca78"
            }
        ],
        "pushMsg": {
            "pushEnable": false,
            "pushTemplateId": "00000000013",
            "pushParams": [],
            "alarm": false
        },
        "smsPushMsg": null,
        "cronExpr": null,
        "timeZoneOffset": 480,
        "setRing": null,
        "undoRing": null,
        "desc": null,
        "ruleSort": 3,
        "createTime": 1502526364702,
        "updateTime": 1508128075342,
        "enabled": true
    }

调用说明

当前联动如果包含多个触发条件，支持以逻辑"与" 和 "或"的关系操作
联动名称不可重复，且数量不超过20个
请注意接口中的参数形式及名称
联动已支持排序

列举IFTTT规则¶

支持通过联动名称模糊查询

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttRule?devTid=1234&ruleName=xxxx&ruleId=1234&ruleType=CUSTOM"

参数

参数名	是否可选	参数类型	取值范围	说明
devTid	可选	String		设备ID，多个使用逗号分隔
ruleName	可选	String		联动名称，支持模糊查询
ruleId	可选	String		联动ID，多个使用逗号分隔
ruleType	可选	String	SECURITY_ALARM,DEPLOY,MORNING_ALARM,DOOR_BELL,CUSTOM	联动类型

返回

< 200
< [
    同4.4.1
    ...
]

编辑IFTTT规则¶

更新为全参提交，参数与4.4.1方法相同

curl -v -X PUT \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttRule?ruleId=123"
       -d '{
        "ruleName" : "新建联动",
        "conditionList": [
            {
                "devTid": "bd6ff14367ec44e8a2a408bff9b333aa",
                "ctrlKey": "a729a084e7014f8cb47c192fb95cf886",
                "subDevTid": "005043c903375c3f",
                "triggerParams": [
                    {
                        "left": "cmdId",
                        "right": 1,
                        "operator": "=="
                    },
                    {
                        "left": "devStatus",
                        "right": "0",
                        "operator": "=="
                    }
                ],
                "conDesc": "检测状态:未检测到人",
                "customFields": {
                    "mid": "xxxxx",
                    "devName": "xxxxxx",
                    "devLogo": "xxxxx"
                }
            },
            {
                "devTid": "bd6ff14367ec44e8a2a408bff9b333aa",
                "ctrlKey": "a729a084e7014f8cb47c192fb95cf886",
                "subDevTid": "005043c90336828e",
                "triggerParams": [
                    {
                        "left": "cmdId",
                        "right": 1,
                        "operator": "=="
                    },
                    {
                        "left": "devStatus",
                        "right": "0",
                        "operator": "=="
                    }
                ],
                "conDesc": "检测状态:未检测到人",
                "customFields": {

                }
            }
        ],
        "triggerType": "REPORT",
        "conditionLogic": "AND",
        "iftttTasks" : [
            {
                "type": "APPSEND",
                "params": {
                    "devTid": "2016-08-17T20-21-42",
                    "ctrlKey": "54308a73b0b34911a14206b8baaba57f",
                    "data": {
                        "raw": "48070200010153"
                    }
                }
            },
            ......
        ],
        "desc" : "xxxxxx"
        "pushMsg": {
            "pushEnable": true,
            "isAlarm": true,
            "pushTemplateId": "00000000012"
        },
        "isEnabled" : true,
        "iftttType":"CUSTOM",
        "cronExpr" : "0 15 10 * * ? 2016",
        "timeZoneOffset" : 480
    }'

参数

参数名	是否可选	参数类型	取值范围	说明
ruleName	必选	String	长度[1, 128]	规则名称
conditionList	必选	List		联动触发条件集合
triggerType	enum	SCHEDULER, REPORT	触发类型（定时触发，上行指令触发）
conditionLogic	enum	AND, OR	多条件触发时，多条件之间的逻辑关系
iftttTasks	必选	List		联动执行action列表
desc	可选	String	长度[1, 128]	联动描述
pushMsg	可选	PushMessage		推送信息
iftttType	必选	enum	SECURITY_ALARM,DEPLOY,MORNING_ALARM,DOOR_BELL,CUSTOM	联动类型
cronExpr	可选	cron_expr		启动时间cron表达式,联动执行时间段
timeZoneOffset	必选	String	[-720, 720]	时区偏移，请注意javascript中获取的东八区时区偏移为-480，该处需要填写480
enabled	可选	Boolean		联动开关

返回

< 204
< No Content

调用说明

修改联动是enabled参数如果没有输入，则不会修改联动当前的isEnabled

删除IFTTT规则¶

curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttRule?ruleId=xxx,xxx,xxx"

参数

参数名	是否可选	参数类型	取值范围	说明
ruleId	必选	String		联动ID，多个使用逗号分隔
randomToken	可选	String

返回

没有返回值时

< 204
< No Content

有返回值时

< 202
< {
    "randomToken"："1qazxsw23edcvfr4"
    "scene":[
      {
        "sceneId":"222222222",
        "sceneName":"睡觉"
      },
      {
        "sceneId":"333333"
        "sceneName":"会家"
      }
      ...
    ]
    "ifttt":[
      {
        "ruleId":"1111111",
        "ruleName":"看电视"
      }，
      {
        "ruleId":"666666",
        "ruleName":"开门"
      },
      .....
    ]
  }

修改IFTTT顺序¶

curl -v -X PATCH \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttRuleSort" \
    -d:'{
        "requestList":[
          {
            "ruleId":"11111",
            "ruleSort": 1
          },
          {
            "ruleId":"222222",
            "ruleSort": 3
          },
          {
            "ruleId":"333333",
            "ruleSort": 2
          }
        ]
      }'

参数

参数名	是否可选	参数类型	取值范围	说明
ruleId	必选	String		联动ID
ruleSort	必选	int		当前联动顺序

返回

没有返回值时

< 204
< [
  {
    "ruleId":"333333",
    "ruleSort": 2
  }
]

注意：
有返回值，返回的参数是修改顺序失败的联动信息

查询联动执行历史记录¶

curl -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttExecuteHistory?page=0&size=20"

参数

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

返回

< 201
< {
  "ruleId": "f81eef1d-5a88-4e5c-bd9c-623f39434c0a",
  "uid": "31009181856",
  "ruleName": "test",
  "iftttExecuteDetails": [
    {
      "iftttExecuteAck": "SUCCESS",
      "desc": "开关3:关闭",
      "iftttTaskId": "c069e96dccd84ef7aa6578e663e2fa2a"
    },
    {
      "iftttExecuteAck": "SUCCESS",
      "desc": " 开关1:打开",
      "iftttTaskId": "ed1981c3b12944ba9ebacdf8cff4df4f"
    },
    {
      "iftttExecuteAck": "FAILURE",
      "desc": "红色:0 绿色:0 蓝色:0 白光:0 RGB亮度系数:0",
      "iftttTaskId": "d90eebe551574f1fbccb6bb786ca21bc"
    }
  ],
  "result": true,
  "executeTime": 1493050660080,
  "desc": ""
 }

注意

开始时间为必选参数