edit

联动

联动,又称联动规则或者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": ""
 }
注意

  • 开始时间为必选参数