跳至主要內容

5. 插件定时预约功能开发指引

插件页定时预约接口

本节主要介绍美的IoT提供云端定时预约相关接口的实现方式。

概念说明：

通过实现定时预约功能的相关接口，可在插件上实现精准时间点或多时间点的设备预约控制。

p1

1. APP插件页新增预约任务

接口说明： APP插件页新增预约任务

URL： https://{domain}/v1/scene/pluginpage/timer/creation

支持格式： 仅限JSON

HTTP请求格式： POST

请求参数：

header参数：

参数必选类型说明
uidtrueString用户UID，移动中台传入
versiontrueString美居App版本号

body参数：

参数必选类型说明
reqIdtrueString请求唯一标识，如uuid
stamptrueString时间戳，格式为：yyyyMMddHHmmss
appIdtrueintappId 美居 900
uidtrueStringC4A账户的id（中台鉴权后传入）
homegroupIdtruelong家庭组ID
nametrueString预约名称
iconUrlfalseStringlogo标识图片
timerTypetrueint定时类型：1-仅执行一次（给出具体的执行时间的cron表达式），2-周期可重复执行
startTimetrueString执行时间，自动化类型为定时必输，格式为hh:mm，时分形式，例如：08:30
weeklytrueString有效天，7位字符，每一位表示一周中的一天，从周一开始，到周日结束； 0表示无效，1表示有效 ， 例如： 0011111 表示周三、四、五、六、天是有效天；定时：weekly 和 startTime 配合使用；
enabletrueint启用状态，0-禁用，1-启用
cronExpressiontrueString标准的Cron表达式, 选择仅一次执行的时候，需要给定下次执行的具体时间如：2021-08-10 08:15:00 执行 的 cron： 00 15 08 10 8 ? 2021
applianceCodetruelong设备code
commandNametrueString下发命令的中文组合，展示用, 必须按照规则填写，不能随便填写。 例如：command: {"power":"on","mode":"cool"}commandName： 电源：开机、模式：制冷
commandtrueJsonObjectlua控制：按照设备profile定义的下发的命令,如:{"mode":"heat","temperature":25,"power":"on"}物模型2.0：按照物模型实例定义下发命令，如：properties为属性控制，格式为："{moduleCode}.{属性名}":{属性值}actions 为物模型操作控制，格式为：module值为模块命令，actionCode值为操作定义的code，data为操作参数。
{
"properties": {
"light.power": true,
"light.colorTemperature": 3000},
"actions": [ {
"module":"light",
"actionCode":"togglePower",
"data": {
"power":true
}} ] }
subscribeGrouptrueString订阅Group , 默认 cronschedulegroup
controlTypetrueint控制类型：1-lua，3-物模型2.0

返回字段：

字段类型说明
codeint业务错误码
msgString返回码说明信息，如错误信息等
dataJSONObject返回结果

请求参数示例：

{
  "uid": "fa94a3d50677f6c2430403357a72ea6f",
  "reqId": "fa94a3d50677f6c2430403357a72ea6ftest",
  "stamp": "202106231700",
  "appId": 900,
  "homegroupId": 9522498,
  "name": "测试",
  "iconUrl": "",
  "timerType": 1,
  "startTime": "07:00",
  "weekly": "1111100",
  "enable": 1,
  "cronExpression": "0 0 7 0 0 1,2,3,4,5 *",
  "applianceCode": 17592186044428,
  "commandName": "",
  "command": {
    "mode": "heat",
    "temperature": 25,
    "power": "on"
  },
  "version": "7.7.0",
  "subscribeGroup":"cronschedulegroup",
  "controlType":1
}

返回：

{
  "code": 0,
  "msg": null,
  "data": {
    "timerId": 10097
  }
}

错误声明：

code说明
1000未知系统错误
1001参数格式错误
1002参数为空

2. APP插件页查询定时任务

接口说明：APP插件页查询定时任务

URL： https://{domain}/v1/scene/pluginpage/timers

支持格式： URL参数

URL示例：

https://{domain}/v1/scene/pluginpage/timers?applianceCode=124448766&reqId=9f9638d4670bf3f7f1adbf9970ef6524 &homegroupId=5678732

HTTP请求格式： GET

请求参数：

header参数：

参数必选类型说明
uidtrueString用户UID，移动中台传入
versiontrueString美居App版本号

URL参数：

参数必选类型说明
reqIdtrueString请求唯一标识
applianceCodetrueLong设备CODE
homegroupIdtrueLong家庭Id

正常返回字段：

字段类型说明
codeint返回码
msgString返回码说明信息，如错误信息等
dataJSONObject返回结果
listJSONArray列表，list 为空，表示没有查询到场景
idlong定时任务id
appIdintappId 美居 900
applianceCodelong设备code
homegroupIdlong家庭组ID
commandNameString下发命令的中文组合，展示用
nameString预约名称
iconUrlStringlogo标识图片
timerTypeint定时类型：1-仅执行一次，2-周期可重复执行
startTimeString执行时间，自动化类型为定时必输，格式为hh:mm，时分形式，例如：08:30
weeklyString有效天，7位字符，每一位表示一周中的一天， 0表示无效，1表示有效 ， 例如： 0011111 ；定时：weekly 和 startTime 配合使用；
enableint启用状态，0-禁用，1-启用，其他值 为无效数据
cronExpressionString标准的Cron表达式
commandjsonStringlua控制：按照设备profile定义的下发的命令,如:{"mode":"heat","temperature":25,"power":"on"}物模型2.0：按照物模型实例定义下发命令，如：properties为属性控制，格式为："{moduleCode}.{属性名}":{属性值}actions 为物模型操作控制，格式为：module值为模块命令，actionCode值为操作定义的code，data为操作参数。
{
"properties": {
"light.power": true, "light.colorTemperature": 3000 },
"actions": [ {
"module": "light",
"actionCode": "togglePower",
"data": {
"power": true } } ] }
versionString版本号
subscribeGroupString订阅Group
controlTypeint控制类型：1-lua ，3-物模型2.0

异常返回字段：

字段类型说明
codeString业务错误码
messageString返回码说明信息，如错误信息等

示例：

请求参数：http://{domain}/v1/scene/pluginpage/timers?applianceCode=3298544976391&reqId=175921860444288887442abc

返回：

{
  "code": 0,
  "msg": null,
  "data": {
    "list": [
      {
        "id": 10043,
        "appId": 900,
        "applianceCode": 3298544976391,
        "homegroupId": 1038369,
        "commandName": "开机",
        "name": "测试",
        "weekly": "1111111",
        "timerType": 1,
        "startTime": "17:10",
        "cronExpression": "0 10 17 ? * 1,2,3,4,5,6,7 *",
        "iconUrl": null,
        "enable": 1,
        "version": "7.7.0",
        "subscribeGroup":"cronschedulegroup",  
        "command": "{\"mode\":\"heat\",\"temperature\":25,\"power\":\"on\"}",
        "controlType":1
      },
      {
        "id": 10049,
        "appId": 900,
        "applianceCode": 3298544976391,
        "homegroupId": 1038369,
        "commandName": "开机",
        "name": "测试",
        "weekly": "1111100",
        "timerType": 1,
        "startTime": "10:28",
        "cronExpression": "0 28 10 ? * 2,3,4,5,6 *",
        "iconUrl": null,
        "enable": 1,
        "version": "7.7.0",
        "subscribeGroup":"cronschedulegroup",  
        "command": "{\"mode\":\"heat\",\"temperature\":25,\"power\":\"on\"}",
        "controlType":1
      }
    ]
  }
}

错误码声明：

code说明
1000未知系统错误
1001参数格式错误
1002参数为空

3. APP插件页修改定时任务

接口说明: APP插件页修改定时任务

URL： https://{domain}/v1/scene/pluginpage/timer/updation

支持格式： 仅限JSON

HTTP请求格式： POST

请求参数：

header参数：

参数必选类型说明
uidtrueString用户UID，移动中台传入
versiontrueString美居App版本号

body参数：

参数必选类型说明
reqIdtrueString请求唯一标识
stamptrueString时间戳，格式为：yyyyMMddHHmmss
appIdtrueintappId 美居 900
uidtrueStringC4A账户的id（中台鉴权后传入）
idtruelong定时任务的id
homegroupIdtruelong家庭组ID
nametrueString预约名称
iconUrlfalseStringlogo标识图片
timerTypetrueint定时类型：1-仅执行一次(给出具体的执行时间的cron表达式)，2-周期可重复执行
startTimetrueString执行时间，自动化类型为定时必输，格式为hh:mm，时分形式，例如：08:30
weeklytrueString有效天，7位字符，每一位表示一周中的一天， 0表示无效，1表示有效 ， 例如： 0011111 ；定时：weekly 和 startTime 配合使用；
enabletrueint启用状态，0-禁用，1-启用
cronExpressiontrueString标准的Cron表达式, 选择仅一次执行的时候，需要给定下次执行的具体时间如：2021-08-10 08:15:00 执行 的cron： 00 15 08 10 8 ? 2021
applianceCodetruelong设备code
commandNametrueString下发命令的中文组合，展示用, 必须按照规则填写，不能随便填写。 例如：command: {"power":"on","mode":"cool"} commandName： 电源：开机、模式：制冷
commandtrueJsonObjectlua控制：按照设备profile定义的下发的命令,如:{"mode":"heat","temperature":25,"power":"on"}物模型2.0：按照物模型实例定义下发命令，如：properties为属性控制，格式为："{moduleCode}.{属性名}":{属性值}actions 为物模型操作控制，格式为：module值为模块命令，actionCode值为操作定义的code，data为操作参数。
{
"properties": {
"light.power": true,
"light.colorTemperature": 3000 },
"actions": [ {
"module": "light",
"actionCode": "togglePower",
"data": {
"power": true } } ] }
subscribeGrouptrueString订阅Group ，默认 cronschedulegroup
controlTypetrueint控制类型：1-lua，3-物模型2.0

返回字段：

字段类型说明
codeint业务错误码
msgString返回码说明信息，如错误信息等
dataJSONObject返回结果

请求示例：

请求参数：

{
 ``"uid"``: ``"fa94a3d50677f6c2430403357a72ea6f"``,
 ``"reqId"``: ``"fa94a3d50677f6c2430403357a72ea6ftest"``,
 ``"stamp"``: ``"202106231700"``,
 ``"appId"``: ``900``,
 ``"homegroupId"``: ``9522498``,
 ``"name"``: ``"测试"``,
 ``"image"``: ``""``,
 ``"id"``:``1008``,
 ``"timerType"``: ``1``,
 ``"startTime"``: ``"07:00"``,
 ``"weekly"``: ``"1111100"``,
 ``"enable"``: ``1``,
 ``"cronExpression"``: ``"0 0 7 0 0 1,2,3,4,5 *"``,
 ``"applianceCode"``: ``17592186044428``,
 ``"commandName"``: ``""``,
 ``"command"``: {
  ``"mode"``: ``"heat"``,
  ``"temperature"``: ``25``,
  ``"power"``: ``"on"
 ``},
 ``"version"``: ``"7.7.0"``,
 ``"subscribeGroup"``:``"cronschedulegroup"``,
 ``"controlType"``:``1
}

返回：

{
  "code": 0,
  "msg": null,
  "data": null
}

错误码声明：

code说明
1000未知系统错误
1001参数格式错误
1002参数为空

4. APP插件页删除定时任务

接口说明： APP插件页删除定时任务

URL：https://{domain}/v1/scene/pluginpage/timer/deletion

支持格式： 仅限JSON

HTTP请求格式： POST

请求参数：

header参数：

参数必选类型说明
uidtrueString用户UID，移动中台传入
versiontrueString美居App版本号

body参数：

参数必选类型说明
reqIdtrueString请求唯一标识
idtruelong定时任务ID
homegroupIdtruelong家庭ID
stamptrueString时间戳，格式为：yyyyMMddHHmmss

返回字段：

字段类型说明
codeint业务错误码
msgString返回码说明信息，如错误信息等
dataJSONObject返回结果

示例：

请求参数：

{
  "reqId": "fa94a3d50677f6c2430403357a72ea6ftest",
  "id": 1008,
  "homegroupId": 156677,
  "stamp": "202106231700"
}

返回：

{
  "code": 0,
  "msg": null,
  "data": null
}

错误码声明：

code说明
1000未知系统错误
1001参数格式错误
1002参数为空

5. APP插件页启用/禁用定时任务

接口说明： APP插件页启用/禁用定时任务

URL： https://{domain}/v1/scene/pluginpage/timer/switch

支持格式： 仅限JSON

HTTP请求格式： POST

请求参数：

参数必选类型说明
uidtrueString用户UID，移动中台传入
versiontrueString美居App版本号

body参数：

参数必选类型说明
reqIdtrueString请求唯一标识
idtruelong定时任务ID
stamptrueString时间
enabletrueint启用状态，0-禁用，1-启用
homegroupIdturelong家庭id

返回字段：

字段类型说明
codeint业务错误码
msgString返回码说明信息，如错误信息等
dataJSONObject返回结果

示例：

请求参数：

{
  "reqId": "fa94a3d50677f6c2430403357a72ea6ftest",
  "id": 1008,
  "enable": 1,
  "stamp": "202106231700"
}

返回：

{
  "code": 0,
  "msg": null,
  "data": null
}

错误码声明：

code说明
1000未知系统错误
1001参数格式错误
1002参数为空

6. 插件页定时预约执行结果查询接口

接口说明： 查询设备预约执行的日志

URL： https://{domain}/v1/scene/pluginpage/timer/actionresult

支持格式： URL参数

URL示例：

https://{domain}/v1/scene/pluginpage/timer/actionresult?&leftTime=2022-01-23&rightTime=2022-03-22&homegroupId=156725&uid=07a49b90aeec4f8fb7e8bd77f80b802a&reqId=fa94a3d50677f6c2430403357a72ea6ftest&applianceCode=177021372072786&pageindex=6&pagesize=10

HTTP请求格式： GET

请求参数：

参数必选类型说明
leftTimetrueString起始时间（注意：不能2022-1-3，需要2022-01-03）
rightTimetrueString结束时间（如上，时间间隔不能超过一个月）
uidtrueString用户id
reqIdtrueString请求唯一标识
homegroupIdtrueLong家庭Id
applianceCodetrueLong设备id
pageindextrueInteger索引页
pagesizetrueInteger页大小

返回字段：

字段类型说明
codeString业务错误码
msgString返回码说明信息，如错误信息等
dataJSONObject返回结果
listJSONObject列表
idString定时任务id
applianceCodeString设备code
homegroupIdlong家庭组ID
commandNameString下发命令中文组合，展示用command: {"power":"on","mode":"cool"}commandName： 电源：开机、模式：制冷
commandStringlua控制：按照设备profile定义的下发的命令,如:{"mode":"heat","temperature":25,"power":"on"}物模型2.0：按照物模型实例定义下发命令，如：properties为属性控制，格式为："{moduleCode}.{属性名}":{属性值}actions 为物模型操作控制，格式为：module值为模块命令，actionCode值为操作定义的code，data为操作参数。
{
"properties":
{"light.power": true,
"light.colorTemperature": 3000},
"actions":
[{"module": "light",
"actionCode": "togglePower",
"data":
{
"power": true
}}]
}
nameString预约名称
iconUrlString预约展示图片
cuidString创建人
cdateData创建时间
mdateData更新时间
actionResultCodeint预约执行的错误码
actionResultMsgString预约执行的错误信息
docIdString执行日志ID

错误码声明：

code说明
1000未知系统错误
1001参数格式错误
1002参数为空