JSON 自动化脚本定义

前提条件

在开始编写 JSON 自动化脚本前，请确保您已通过调用 QueryDeviceSupportedScriptAutomationConfigRequest 接口了解您所需的功能点信息。

标准结构

JSON 自动化脚本的标准结构如下所示，包含元数据（metadata）和自动化定义（automations）：

参数	类型	是否必需	说明
metadata	Object	✗	自动化操作的元数据，包含自动化操作的名称、说明和变量定义。
metadata.name	String	✗	自动化的名称。
metadata.description	String	✗	自动化的描述。
metadata.scope	Array of DeviceProperty	✗	定义设备的属性值变量列表。
automations	Array of Object	✓	自动化数组，包含一个或多个自动化。
automations.name	String	✗	自动化名称
automations.starters	Array of Starter	✓	触发器列表（至少包含一个）。
automations.condition	Object	✗	执行条件，详情情参考 Condition。
automations.actions	Array of Action	✓	此参数定义自动化触发后要执行的操作列表（至少包含 1 个），按顺序执行。

Starter

Starter 是用于触发自动化的条件，支持以下类型：

类型	说明
PropertyEvent	此触发器表示仅当设备属性变化并满足特定条件时触发自动化。
TimeSchedule	此触发器表示仅在指定时间触发自动化。
Manual	此触发器表示自动化由用户手动触发。

PropertyEvent

参数	类型	是否必需	说明
type	String	✓	固定为 "property.event"。
source	Datasource	✓	监听的设备属性数据源。
is	Dynamic	✗	检查数据是否等于某个值。
isNot	Dynamic	✗	检查数据是否不等于某个值。
greaterThan	Dynamic	✗	检查数据是否大于某个值。
greaterThanOrEqualTo	Dynamic	✗	检查数据是否大于等于某个值。
lessThan	Dynamic	✗	检查数据是否小于某个值。
lessThanOrEqualTo	Dynamic	✗	检查数据是否小于等于某个值。
for	Duration	✗	比较条件必须持续满足的时间长度（例如："30min"、"1hour10min20sec"）。
suppressFor	Duration	✗	在一次触发之后，必须等待该时间结束后才能再次触发。

提示

参数使用需遵循以下约束：

is 和 isNot 不能同时使用。
lessThan 和 lessThanOrEqualTo 不能同时使用。
greaterThan 和 greaterThanOrEqualTo 不能同时使用。

比较运算符的类型说明

比较运算符（is、isNot、greaterThan 等）的值支持以下三种类型：

字面量：基本数值类型，如 Boolean、Number、String。

示例如下：

// 布尔值
"is": true
"is": false

// 数值
"greaterThan": 25
"lessThanOrEqualTo": 100.5

// 字符串
"is": "on"
"isNot": "offline"

变量引用：引用在 metadata.scope 中定义的变量，类型为 DataRef。

示例如下：

"is": {
    "type": "data.ref",
    "from": "/metadata/scope",
    "select": {
        "by": "name",
        "value": "targetTemp"
    }
}

设备属性引用：直接引用另一个设备的属性值进行比较。

参数	类型	是否必需	说明
type	String	✓	固定为 "device.property"。
deviceId	String	✓	设备 ID。
functionCode	String	✓	功能代码。
endpointId	Integer	✓	端点 ID。
traitCode	String	✓	属性代码。

示例如下：

"is": {
    "type": "device.property",
    "deviceId": "sensor002",
    "endpointId": 1,
    "functionCode": "TemperatureMeasurement",
    "traitCode": "MeasuredValue"
}

TimeSchedule

参数	类型	是否必需	说明
type	String	✓	固定为 "time.schedule"。
cron	String	（与 at 二选一）	Cron 表达式。
at	String	（与 cron 二选一）	具体时刻，详情请参考 Time 说明。
timezone	String	✗	指定时区，请输入符合 IANA 标准的时区标识（如 "Asia/Shanghai"），以确保定时任务按期望时区执行。如未填写，默认使用 Aqara Studio 当前的时区信息。

Manual

参数	类型	是否必需	说明
type	String	✓	固定为 "manual"。
name	String	✓	您自定义的名称。

示例如下：

{
    "type": "manual",
    "name": "回家"
}

Condition

Condition（条件）用于在执行 Action（操作）之前进行判断。只有当 Starter（触发器）被触发后，系统才会判断 Condition 是否满足。如果 Condition 判断通过，则会继续执行后续的 Action，否则不会执行操作。

Condition 的类型包含如下：

类型	说明
AndCondition	仅当所有子条件都满足才触发操作。
OrCondition	只需任意子条件满足即可触发操作。
NotCondition	对单个子条件的结果取反。
PropertyState	检查设备属性的当前状态。
TimeBetween	检查当前时间是否在指定范围内。

AndCondition

此条件表示仅当所有子条件都满足才触发操作。

参数	类型	是否必需	说明
type	String	✓	固定为 "and"。
conditions	Array of Condition	✓	子条件列表（至少两个）。

示例如下：

{
    "type": "and",
    "conditions": [
        {
            "type": "property.state",
            "source": {
                "type": "data.ref",
                "select": {
                    "by": "name",
                    "value": "roomTemp"
                }
            },
            "greaterThan": 25
        },
        {
            "type": "property.state",
            "source": {
                "type": "data.ref",
                "select": {
                    "by": "name",
                    "value": "humidity"
                }
            },
            "lessThan": 60
        }
    ]
}

OrCondition

此条件表示只需任意子条件满足即可触发操作。

参数	类型	是否必需	说明
type	String	✓	固定为 "or"。
conditions	Array of Condition	✓	子条件列表（至少两个）。

示例如下：

{
    "type": "or",
    "conditions": [
        {
            "type": "property.state",
            "source": {
                "type": "data.ref",
                "select": {
                    "by": "name",
                    "value": "motionSensor1"
                }
            },
            "is": true
        },
        {
            "type": "property.state",
            "source": {
                "type": "data.ref",
                "select": {
                    "by": "name",
                    "value": "motionSensor2"
                }
            },
            "is": true
        }
    ]
}

NotCondition

此条件表示对单个子条件的结果取反。

字段	类型	是否必需	说明
type	String	✓	固定为 "not"。
condition	Condition	✓	要取反的条件。

示例如下：

{
    "type": "not",
    "condition": {
        "type": "property.state",
        "source": { 
            "type": "data.ref", 
            "select": { 
                "by": "name", 
                "value": "vacationMode" 
            } 
        },
        "is": true
    }
}

PropertyState

此条件用于判断设备某个属性的当前值是否满足指定的比较条件。

字段	类型	是否必需	说明
type	String	✓	固定为 "property.state"。
source	Datasource	✓	要检查的设备属性数据源。
is	Dynamic	✗	检查数据是否等于某个值。
isNot	Dynamic	✗	检查数据是否不等于某个值。
greaterThan	Dynamic	✗	检查数据是否大于某个值。
greaterThanOrEqualTo	Dynamic	✗	检查数据是否大于等于某个值。
lessThan	Dynamic	✗	检查数据是否小于某个值。
lessThanOrEqualTo	Dynamic	✗	检查数据是否小于等于某个值。
for	Duration	✗	指定需要持续满足比较条件的最长时间，例如 "30min" 或 "1hour10min20sec"。

提示

至少需要指定一个比较运算符。

示例如下：

基础判断示例 A
基础判断示例 B
带持续时长的判断

{
    "type": "property.state",
    "source": {
        "type": "device.property",
        "deviceId": "light001",
        "endpointId": 1,
        "functionCode": "OnOff",
        "traitCode": "OnOff"
    },
    "is": true
}

{
    "type": "property.state",
    "source": {
        "type": "device.property",
        "deviceId": "light001",
        "endpointId": 1,
        "functionCode": "TemperatureMeasurement",
        "traitCode": "MeasuredValue"
    },
    "greaterThan": 2800
}

{
    "type": "property.state",
    "source": {
        "type": "device.property",
        "deviceId": "sensor001",
        "endpointId": 1,
        "functionCode": "TemperatureMeasurement",
        "traitCode": "MeasuredValue"
    },
    "greaterThan": 2800,
    "for": "5min"
}

TimeBetween

此条件用于检查当前时间是否在指定范围内。

参数	类型	是否必需	说明
type	String	✓	固定为 "time.between"。
after	String	✓	开始时间，详情请参考 Time。
before	String	✓	结束时间，详情请参考 Time。

示例如下：

{
    "type": "time.between",
    "after": "08:00",
    "before": "22:00"
} 

Action

Action（操作）用于在自动化被触发且满足条件后实际执行的操作。每个 Action 描述一次具体的执行行为，如控制设备、延迟执行等。

Action 的类型包含如下：

类型	说明
TraitWrite	写入设备功能点值。
Delay	设置延迟时长。

TraitWrite

此操作为写入设备功能点值。

参数	类型	是否必需	说明
type	String	✓	固定为 "device.trait.write"
functionCode	String	✓	功能代码。
traitCode	String	✓	功能点代码。
targets	Array of Object	✓	端点 ID 列表。
targets[].deviceId	String	✓	设备 ID。
targets[].endpointIds	Array of Integer	✓	端点 ID 列表。
value	Dynamic	✓	待写入的功能点值。此参数的类型与功能点类型相关，详情请参考 Value 类型说明。

Value 类型说明

功能点类型	值类型	示例
Boolean	true / false / "toggle"	true
Numeric	Number	80 或 25.5
Enum	String / Number	"cool" 或 1
String	String	"hello"

示例如下：

打开灯光
设置亮度
设置颜色温度

{
    "type": "device.trait.write",
    "functionCode": "Switch",
    "traitCode": "OnOff",
    "targets": [
        {
            "deviceId": "light001",
            "endpointIds": [1, 2]
        },
        {
            "deviceId": "light002",
            "endpointIds": [2, 3]
        }
    ],
    "value": true
}

{
    "type": "device.trait.write",
    "functionCode": "LevelControl",
    "traitCode": "CurrentLevel",
    "targets": [
        {
            "deviceId": "light001",
            "endpointIds": [2]
        },
        {
            "deviceId": "light002",
            "endpointIds": [3]
        }
    ],
    "value": 80
}

{
    "type": "device.trait.write",
    "functionCode": "ColorControl",
    "traitCode": "ColorTemperatureMireds",
    "targets": [
        {
            "deviceId": "light001",
            "endpointIds": [1]
        }
    ],
    "value": 300
}

Delay

此操作为设置延迟时长。

参数	类型	是否必需	说明
type	String	✓	固定为 "delay"。
for	Duration	✓	延迟时长。

示例如下：

{
    "type": "delay",
    "for": "20sec"
}

Datasource

Datasource 是用于引用设备属性或变量的通用结构，分为两种类型：DeviceProperty（设备属性）和 DataRef（变量引用）。

DeviceProperty

此对象用于直接引用设备的特定属性。

参数	类型	是否必需	说明
type	String	✓	固定为 "device.property"。
deviceId	String	✓	设备 ID
functionCode	String	✓	功能代码（如 OnOff、LevelControl）。
endpointId	Integer	✓	端点 ID。
traitCode	String	✓	特性代码（如 OnOff、CurrentLevel）。
name	String	✗	变量名称，在 metadata.scope 中定义时须添加。

DataRef

此对象用于引用在 metadata.scope 中定义的变量。

参数	类型	是否必需	说明
type	String	✓	固定为 "data.ref"。
from	String	✗	目标路径，固定为 "/metadata/scope"，默认可不加。
select	Object	✓	选择表达式，用于指定要引用的变量。
select.by	Object	✓	选择方式，固定值 "name"
select.value	Object	✓	变量名称（即您在 scope.name 中定义的字符串）

Cron

Cron 表达式的结构为：秒分时日月周年（依次排列），说明如下：

位置	字段	允许值	特殊字符
1	秒	0-59	* /
2	分	0-59	* /
3	时	0-23	* /
4	日（月中天）	1-31	, * ?
5	月	1-12	, - *
6	周（周中天）	1：星期一 2：星期二 3：星期三 4：星期四 5：星期五 6：星期六 7：星期日	, * ?
7	年	四位数字	, *

特殊字符说明

符号	含义	示例说明
`*`	所有值	在分钟字段中写 `*` 表示“每一分钟”
`?`	无特定值	当你只想指定日或周中的某一字段，而不关心另一个字段。例如：日字段写 `10`，周字段写 `?` 表示每月 10 号触发，但不在意星期几
`-`	范围	小时字段写 `10-12` 表示“10 点、11 点和 12 点”
`,`	额外值	周字段写 `1,3,5` 表示“星期一、星期三和星期五”
`/`	步进（增量）	秒字段写 `0/15` 表示“第 0、15、30、45 秒”，`5/15` 表示“第 5、20、35、50 秒”；日字段写 `1/3` 表示“从每月第一天开始，每 3 天触发一次”；可与 `` 配合使用，`/15` 表示“每 15 个单位触发一次”

以下示例可帮助您更清晰地理解 Cron 表达式的用法：

Cron 表达式	含义
`0 0 2 * * ? *`	每天凌晨 2 点触发（不关心星期几）
`0 0 9 ? * 2 *`	每周二 9:00 执行（不关心日期）
`0 0 0 1 * ? *`	每月 1 号凌晨 0 点执行（不关心星期几）
`0 /5 * * ? *`	每 5 分钟执行一次
`0 0/15 9-17 * * ? *`	每天 9 点到 17 点，每小时的 0、15、30、45 分钟执行
`0 0 1 1,10,20 * ? *`	每月的 1、10、20 日凌晨 1 点执行
`0 0 9 ? * 2,4 *`	每周二和周四早上 9 点执行（不关心具体日期）
`0 0 0 1 1 ? 2026`	2026 年 1 月 1 日凌晨 0 点执行
`0 0 0/3 * * ? *`	每 3 小时执行一次，从 0 点开始

Time

Time 表示一天中的时间点，支持时钟时间和太阳时间两种类型。

时钟时间

您可以使用 24 小时格式或 AM/PM 格式。

24 小时格式：
格式示例说明
HH:mm 13:00 13 点 00 分
HH:mm:ss 13:00:01 13 点 00 分 01 秒（秒可选）
H:mm 8:30 8 点 30 分
AM/PM 格式：
格式示例说明
h:mm am/pm 0:30 am 凌晨 0 点 30 分
h:mm am/pm 7:30 pm 晚上 7 点 30分
h:mm:ss am/pm 8:00:00 am 早上 8 点整

格式	示例	说明
HH:mm	13:00	13 点 00 分
HH:mm:ss	13:00:01	13 点 00 分 01 秒（秒可选）
H:mm	8:30	8 点 30 分

格式	示例	说明
h:mm am/pm	0:30 am	凌晨 0 点 30 分
h:mm am/pm	7:30 pm	晚上 7 点 30分
h:mm:ss am/pm	8:00:00 am	早上 8 点整

太阳时间

太阳时间是指以日出或日落为基准的时间，您可以通过添加或减少偏移量（Duration），来精确设定具体的触发时刻。

格式	示例	说明
sunrise	sunrise	日出时刻
sunset	sunset	日落时刻
sunrise+Duration	sunrise+30min	日出后 30 分钟
sunrise-Duration	sunrise-1hour	日出前 1 小时
sunset+Duration	sunset+30min	日落后 30 分钟
sunset-Duration	sunset-1hour	日落前 1 小时

Duration

Duration 表示一段时间长度，用于以下字段：

delay.for：延迟控制设备的等待时间。
property.event.for：比较条件必须持续满足的时间长度。
property.event.suppressFor：在一次触发之后，必须等待该时间结束后才能再次触发。
property.state.for：检查状态是否已保持一定时长。

支持的时间单位：

时间单位	关键字	示例
小时	hour	1hour
分钟	min	30min
秒	sec	20sec

您可以组合上述多个时间单位，按 hour、min、sec 的顺序排列，如下所示：

示例	说明
1hour10min20sec	1 小时 10 分钟 20 秒
1hour30min	1 小时 30 分钟
10min30sec	10 分钟 30秒

完整示例

以下是三个 JSON 自动化脚本的示例：

空调与温度传感器联动
灯光与人体传感器联动
多条件联合场景控制

空调与温度传感器联动

以下示例表示当温度超过 28°C 且持续 5 分钟时，自动打开空调并设置为制冷模式。

{
    "metadata": {
        "name": "空调与温度传感器联动",
        "scope": [
            {
                "name": "roomTemp",
                "type": "device.property",
                "deviceId": "temp_sensor_001",
                "endpointId": 1,
                "functionCode": "TemperatureMeasurement",
                "traitCode": "MeasuredValue"
            }
        ]
    },
    "automations": [
        {
            "name": "高温开空调",
            "starters": [
                {
                    "type": "property.event",
                    "source": {
                        "type": "data.ref",
                        "select": {
                            "by": "name",
                            "value": "roomTemp"
                        }
                    },
                    "greaterThan": 2800,
                    "for": "5min",
                    "suppressFor": "1hour"
                }
            ],
            "condition": {
                "type": "time.between",
                "after": "08:00",
                "before": "23:00"
            },
            "actions": [
                {
                    "type": "device.trait.write",
                    "functionCode": "Switch",
                    "traitCode": "OnOff",
                    "targets": [
                        {
                            "deviceId": "lumi.xxxxx",
                            "endpointIds": [3]
                        }
                    ],
                    "value": true
                },
                {
                    "type": "device.trait.write",
                    "functionCode": "Thermostat",
                    "traitCode": "SystemMode",
                    "targets": [
                        {
                            "deviceId": "lumi.xxxxx",
                            "endpointIds": [1]
                        }
                    ],
                    "value": "cool"
                },
                {
                    "type": "device.trait.write",
                    "functionCode": "Thermostat",
                    "traitCode": "OccupiedCoolingSetpoint",
                    "targets": [
                        {
                            "deviceId": "ac_001",
                            "endpointIds": [1]
                        }
                    ],
                    "value": 2500
                }
            ]
        }
    ]
}

灯光与人体传感器联动

以下示例表示检测到人体时开灯，无人时 5 分钟后关灯。

{
    "metadata": {
        "name": "人体感应灯光",
        "scope": [
            {
                "name": "motion",
                "type": "device.property",
                "deviceId": "motion_001",
                "endpointId": 1,
                "functionCode": "OccupancySensing",
                "traitCode": "Occupancy"
            }
        ]
    },
    "automations": [
        {
            "name": "有人开灯",
            "starters": [
                {
                    "type": "property.event",
                    "source": { 
                        "type": "data.ref", 
                        "select": { 
                            "by": "name", 
                            "value": "motion" 
                        } 
                    },
                    "is": true
                }
            ],
            "condition": {
                "type": "time.between",
                "after": "18:00",
                "before": "06:00"
            },
            "actions": [
                {
                    "type": "device.trait.write",
                    "functionCode": "Switch",
                    "traitCode": "OnOff",
                    "targets": [
                        {
                            "deviceId": "light_001",
                            "endpointIds": [1]
                        }
                    ],
                    "value": true
                }
            ]
        },
        {
            "name": "无人关灯",
            "starters": [
                {
                    "type": "property.event",
                    "source": { 
                        "type": "data.ref", 
                        "select": { 
                            "by": "name", 
                            "value": "motion" 
                        } 
                    },
                    "is": false,
                    "for": "5min"
                }
            ],
            "actions": [
                {
                    "type": "device.trait.write",
                    "functionCode": "Switch",
                    "traitCode": "OnOff",
                    "targets": [
                        {
                            "deviceId": "light001",
                            "endpointIds": [1]
                        }
                    ],
                    "value": false
                }
            ]
        }
    ]
}

多条件联合场景控制

以下示例表示周一到周五早上 7 点，如果温度低于 20°C 且湿度大于 70%，开启除湿器和暖风机。

{
    "metadata": {
        "name": "早晨环境调节",
        "scope": [
            {
                "name": "temp",
                "type": "device.property",
                "deviceId": "sensor_001",
                "endpointId": 1,
                "functionCode": "TemperatureMeasurement",
                "traitCode": "MeasuredValue"
            },
            {
                "name": "humidity",
                "type": "device.property",
                "deviceId": "sensor_001",
                "endpointId": 1,
                "functionCode": "RelativeHumidityMeasurement",
                "traitCode": "MeasuredValue"
            }
        ]
    },
    "automations": [
        {
            "name": "早晨环境调节",
            "starters": [
                {
                    "type": "time.schedule",
                    "cron": "0 0 7 * * MON-FRI"
                }
            ],
            "condition": {
                "type": "and",
                "conditions": [
                    {
                        "type": "property.state",
                        "source": {
                            "type": "data.ref",
                            "select": {
                                "by": "name",
                                "value": "temp"
                            }
                        },
                        "lessThan": 2000
                    },
                    {
                        "type": "property.state",
                        "source": {
                            "type": "data.ref",
                            "select": {
                                "by": "name",
                                "value": "humidity"
                            }
                        },
                        "greaterThan": 7000
                    }
                ]
            },
            "actions": [
                {
                    "type": "device.trait.write",
                    "functionCode": "Switch",
                    "traitCode": "OnOff",
                    "targets": [
                        {
                            "deviceId": "light001",
                            "endpointIds": [1]
                        }
                    ],
                    "value": true
                },
                {
                    "type": "device.trait.write",
                    "functionCode": "Switch",
                    "traitCode": "OnOff",
                    "targets": [
                        {
                            "deviceId": "light001",
                            "endpointIds": [1]
                        },
                        {
                            "deviceId": "heater_001",
                            "endpointIds": [1]
                        }
                    ],
                    "value": true
                }
            ]
        }
    ]
}

前提条件​

标准结构​

Starter​

PropertyEvent​

比较运算符的类型说明​

TimeSchedule​

Manual​

Condition​

AndCondition​

OrCondition​

NotCondition​

PropertyState​

TimeBetween​

Action​

TraitWrite​

Value 类型说明​

Delay​

Datasource​

DeviceProperty​

DataRef​

Cron​

特殊字符说明​

Time​

时钟时间​

太阳时间​

Duration​

完整示例​

空调与温度传感器联动​

灯光与人体传感器联动​

多条件联合场景控制​

前提条件

标准结构

Starter

PropertyEvent

比较运算符的类型说明

TimeSchedule

Manual

Condition

AndCondition

OrCondition

NotCondition

PropertyState

TimeBetween

Action

TraitWrite

Value 类型说明

Delay

Datasource

DeviceProperty

DataRef

Cron

特殊字符说明

Time

时钟时间

太阳时间

Duration

完整示例

空调与温度传感器联动

灯光与人体传感器联动

多条件联合场景控制