自动化 API

获取可用于自动化的所有功能点信息

通过调用本接口，您可获取所有设备中可用于自动化配置的功能点信息。返回内容包括各功能点的值类型、单位，以及其在自动化流程中的适用环节（如可作为触发器、条件或操作）。

请求参数

参数	类型	是否必需	说明
type	String	✓	请求的消息类型，必需为 `QueryAutomationCapabilitiesRequest`。
version	String	✓	请求接口版本号，必需为 `v1`。
msgId	String	✓	由您定义的请求 ID。
data	Object	✗	此处传空对象。

请求参数示例

以下为 QueryAutomationCapabilitiesRequest 的请求体示例：

{
    "type": "QueryAutomationCapabilitiesRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {}
}

响应数据

字段	类型	说明
type	String	响应的消息类型，固定为 `QueryAutomationCapabilitiesResponse`。
version	String	响应接口版本号，与请求接口版本号一致。
msgId	String	请求时传入的 `msgId`。
code	Number	返回码，0 表示成功，非 0 表示失败。
data.devices	Array of Object	设备信息列表。
data.devices[].deviceId	String	设备 ID。
data.devices[].deviceName	String	设备名称。
data.devices[].endpoints	Array of Object	设备的端点信息列表。
data.devices[].endpoints[].endpointName	String	端点名称。
data.devices[].endpoints[].endpointId	Number	端点 ID。
data.devices[].endpoints[].properties	Array of Object	功能点列表。
data.devices[].endpoints[].properties[].functionCode	String	功能代码。
data.devices[].endpoints[].properties[].functionName	String	功能名称。
data.devices[].endpoints[].properties[].traitCode	String	功能点代码。
data.devices[].endpoints[].properties[].traitName	String	功能点名称。
data.devices[].endpoints[].properties[].valueType	String	功能点值的类型（如 boolean、number 等）。
data.devices[].endpoints[].properties[].semanticRole	Array of String	查询到该功能点在自动化中可用的环节范围，包括 starter（可作为触发器）、condition（可作为条件判断）、action（可作为操作）等，具体以返回的数组内容为准。
data.devices[].endpoints[].properties[].unit	String/null	单位，若无单位则为 null。

响应数据示例

以下为 QueryAutomationCapabilitiesResponse 的响应示例：

{
    "type": "QueryAutomationCapabilitiesResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "devices": [
            {
                "deviceId": "9f3e3632068ff047",
                "deviceName": "Door and Window Magnet Sensor",
                "endpoints": [
                    {
                        "endpointName": "Endpoint_2",
                        "endpointId": 2,
                        "properties": [
                            {
                                "functionCode": "OnOffSensor",
                                "functionName": "OnOff Sensor",
                                "traitCode": "BooleanState",
                                "traitName": "Boolean State",
                                "valueType": "boolean",
                                "semanticRole": [
                                    "starter",
                                    "condition"
                                ],
                                "unit": null
                            }
                        ]
                    }
                ]
            },
            {
                "deviceId": "af9e93b709de1fd9",
                "deviceName": "Motion Sensor",
                "endpoints": [
                    {
                        "endpointName": "Endpoint_2",
                        "endpointId": 2,
                        "properties": [
                            {
                                "functionCode": "OnOffSensor",
                                "functionName": "OnOff Sensor",
                                "traitCode": "BooleanState",
                                "traitName": "Boolean State",
                                "valueType": "boolean",
                                "semanticRole": [
                                    "starter",
                                    "condition"
                                ],
                                "unit": null
                            }
                        ]
                    }
                ]
            },
            {
                "deviceId": "947793560f5b2fbd",
                "deviceName": "Flood Detector",
                "endpoints": [
                    {
                        "endpointName": "Endpoint_2",
                        "endpointId": 2,
                        "properties": [
                            {
                                "functionCode": "OnOffSensor",
                                "functionName": "OnOff Sensor",
                                "traitCode": "BooleanState",
                                "traitName": "Boolean State",
                                "valueType": "boolean",
                                "semanticRole": [
                                    "starter",
                                    "condition"
                                ],
                                "unit": null
                            }
                        ]
                    }
                ]
            },
            ...
        ]
    },
    "code": 0
}

创建自动化

调用本接口，您可以创建并启用一个 Flow 自动化。

创建成功后，您可以在 Aqara Studio 的自动化列表中查看并管理该 Flow。

请求参数

参数	类型	是否必需	说明
type	String	✓	请求的消息类型，必需为 `CreateAutomationRequest`。
version	String	✓	请求接口版本号，必需为 `v1`。
msgId	String	✓	由您定义的请求 ID。
data	Object	✓	请求数据。
data.definitionType	String	✓	自动化类型。当前仅支持 `"SCRIPT_JSON"`。
data.config	Object	✓	JSON 自动化脚本，详情请参考 JSON 自动化脚本定义。

请求参数示例

以下为 CreateAutomationRequest 的请求体示例：

{
    "type": "CreateAutomationRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "definitionType": "SCRIPT_JSON",
        "config": {
            "metadata": {
                "name": "智能灯光控制",
                "description": "当开关打开时，自动打开两盏灯",
                "scope": [
                    {
                        "name": "switchState",
                        "type": "device.property",
                        "deviceId": "switch001",
                        "endpointId": 1,
                        "functionCode": "OnOff",
                        "traitCode": "OnOff"
                    },
                    {
                        "name": "tempSensor",
                        "type": "device.property",
                        "deviceId": "sensor001",
                        "endpointId": 1,
                        "functionCode": "TemperatureMeasurement",
                        "traitCode": "MeasuredValue"
                    }
                ]
            },
            "automations": [
                {
                    "name": "开关联动灯光",
                    "starters": [
                        {
                            "type": "property.event",
                            "source": {
                                "type": "data.ref",
                                "from": "/metadata/scope",
                                "select": {
                                    "by": "name",
                                    "value": "switchState"
                                }
                            },
                            "is": true,
                            "for": "5sec",
                            "suppressFor": "10sec"
                        }
                    ],
                    "condition": {
                        "type": "and",
                        "conditions": [
                            {
                                "type": "property.state",
                                "source": {
                                    "type": "data.ref",
                                    "from": "/metadata/scope",
                                    "select": {
                                        "by": "name",
                                        "value": "tempSensor"
                                    }
                                },
                                "greaterThan": 20
                            },
                            {
                                "type": "time.between",
                                "after": "08:00",
                                "before": "22:00"
                            }
                        ]
                    },
                    "actions": [
                        {
                            "type": "device.trait.write",
                            "functionCode": "Switch",
                            "traitCode": "OnOff",
                            "targets": [
                                {
                                    "deviceId": "light001",
                                    "endpointIds": [1]
                                }
                            ],
                            "value": true
                        },
                        {
                            "type": "delay",
                            "for": "2sec"
                        },
                        {
                            "type": "device.trait.write",
                            "functionCode": "LevelControl",
                            "traitCode": "CurrentLevel",
                            "targets": [
                                {
                                    "deviceId": "light001",
                                    "endpointIds": [1]
                                }
                            ],
                            "value": 100
                        }
                    ]
                }
            ]
        }
    }
}

响应数据

参数	类型	说明
type	String	响应的消息类型，固定为 `CreateAutomationResponse`。
version	String	响应版本号，与请求接口版本号一致。
msgId	String	您发起请求时传入的 `msgId`。
code	Number	请求是否成功。0 表示成功，非 0 表示失败。
message	String	请求结果描述。
data	String	创建成功的自动化 ID（`automationId`）

响应数据示例

以下为 CreateAutomationResponse 的响应示例：

{
    "type": "CreateAutomationResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "code": 0,
    "message": "",
    "data": "auto_15b0cde_127312348967862272"
}

编辑自动化

通过调用本接口，您可以修改已有自动化的名称与启用状态。若该自动化的 definitionType 为 "SCRIPT_JSON"，还可同时更新其自动化脚本内容。

请求参数

参数	类型	是否必需	说明
type	String	✓	请求的消息类型，必需为 `UpdateAutomationRequest`。
version	String	✓	请求接口版本号，必需为 `v1`。
msgId	String	✓	由您定义的请求 ID。
data	Object	✓	请求数据对象。
data.automationId	String	✓	编辑目标的的自动化 ID。
data.definitionType	String	✓	编辑目标的的自动化类型。
data.name	String	✗	新的名称。
data.enabled	Boolean	✗	新的启用状态。`true` 表示启用，`false` 表示禁用。
data.config	Object	✗	新的 JSON 自动化脚本。
data.updateMask	Array of String	✓	需更新的参数名称列表，仅支持以下字段： `"name"` `"enabled"` `"config"` 请确保 `updateMask` 中的每一项都已在 data 对象中正确提供新值。

请求参数示例

以下为 UpdateAutomationRequest 的请求体示例：

{
    "type": "UpdateAutomationRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "automationId":"auto_15b0cde_127312348967862272",
        "definitionType": "SCRIPT_JSON",
        "name": "New Name",
        "updateMask": [
            "name"
        ]
    }
}

响应数据

参数	类型	说明
type	String	响应的消息类型，固定为 `UpdateAutomationResponse`。
version	String	响应版本号，与请求接口版本号一致。
msgId	String	您发起请求时传入的 `msgId`。
code	Number	请求是否成功，0 表示成功，非 0 表示失败。
message	String	请求结果描述。
data	String	空字符串。

响应数据示例

以下为 UpdateAutomationResponse 的响应示例：

{
    "type": "UpdateAutomationResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "code": 0,
    "message": "",
    "data": ""
}

批量更新自动化状态

调用本接口，您可以一次性更新多个自动化的启用状态。

请求参数

参数	类型	是否必需	说明
type	String	✓	请求的消息类型，必需为 `UpdateAutomationStatusRequest`。
version	String	✓	请求接口版本号，必需为 `v1`。
msgId	String	✓	由您定义的请求 ID。
data	Object	✓	请求数据对象。
data.automationIds	Array of String	✓	需要更新状态的自动化 ID 列表。
data.enabled	Boolean	✓	需要设置的启用状态，`true` 表示启用，`false` 表示禁用。

请求参数示例

以下为 UpdateAutomationStatusRequest 的请求体示例：

{
    "type": "UpdateAutomationStatusRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "automationIds": [
            "auto_15b0cde_127312348967862272"
        ],
        "enabled": false
    }
}

响应数据

字段名	类型	说明
type	String	响应消息类型，固定为 `UpdateAutomationStatusResponse`
version	String	响应接口版本号，固定为 `v1`
msgId	String	您发起请求时传入的 `msgId`。
code	Number	请求是否成功，0 表示成功，非 0 表示失败。
message	String	请求结果描述。
data	Object	响应数据对象。
data.successIds	Array of String	成功的自动化 ID 列表。
data.failedItems	Array of Object	失败的自动化对象。
data.failedItems.automationId	String	自动化 ID。
data.failedItems.code	String	错误码。
data.failedItems.message	String	失败描述。

响应数据示例

以下为 UpdateAutomationStatusResponse 的响应示例：

{
    "type": "UpdateAutomationStatusResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "successIds": [
            "auto_15b0cde_127312348967862272"
        ]
    }
}

查询自动化列表

调用本接口，您可以分页获取一个自动化简介列表，了解每个自动化的 ID、名称、启用状态和创建时间。

请求参数

参数	类型	是否必需	说明
type	String	✓	请求的消息类型，必需为 `GetAutomationListRequest`。
version	String	✓	请求接口版本号，必需为 `v1`。
msgId	String	✓	由您定义的请求 ID。
data	Object	✓	请求数据对象。
data.definitionTypes	Array of String	✗	查询目标类型，可选值：`"SCRIPT_JSON"`、`"SCRIPT_TEXT"`、`"WHEN_IF_THEN"`。不传或为空时查询全部类型。
data.orderBy	String	✗	排序字段。 `"createTime asc"`：（默认）按创建时间升序 `"createTime desc"`：按创建时间降序
data.pageNum	Number	✓	页码，从 1 开始。
data.pageSize	Number	✓	每页数据条数。

请求参数示例

以下为 GetAutomationListRequest 的请求体示例：

{
    "type": "GetAutomationListRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "definitionTypes": ["SCRIPT_JSON"],
        "pageNum":1,
        "pageSize":2
    }
}

响应数据

字段名	类型	说明
type	String	响应消息类型，固定为 `GetAutomationListResponse`
version	String	响应接口版本号，固定为 `v1`
msgId	String	您发起请求时传入的 `msgId`。
data	Object	响应数据对象，包含自动化列表及分页信息
data.totalCount	Number	总自动化数量。
data.pageNum	Number	当前页码。
data.pageSize	Number	每页数量。
data.data	Array of Object	自动化列表。
data.data[].automationId	String	自动化 ID。
data.data[].definitionType	String	自动化类型。
data.data[].name	String	自动化名称。
data.data[].enabled	Boolean	启用状态： true：已启用 false：禁用
data.data[].createTime	Number	自动化创建时间，单位为毫秒的 UTC 时间戳。
code	Number	请求是否成功。0 表示成功，非 0 表示失败。
message	String 或 null	响应描述消息。为空字符串或 null 时表示请求成功。

响应数据示例

以下为 GetAutomationListResponse 的响应示例：

{
    "type": "GetAutomationListResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "totalCount": 6,
        "pageNum": 1,
        "pageSize": 2,
        "data": [
            {
                "automationId": "auto_15b0cde_127312348967862272",
                "definitionType": "SCRIPT_JSON",
                "name": "a3-1",
                "enabled": false,
                "createTime": 1766043229326
            },
            {
                "automationId": "auto_15b0ceb_127312523723538432",
                "definitionType": "SCRIPT_JSON",
                "name": "b2",
                "enabled": true,
                "createTime": 1766043270999
            }
        ]
    },
    "code": 0,
    "message": null
}

查询自动化详情

通过调用本接口并传入自动化 ID，您可以获取指定自动化的详细信息（如 JSON 自动化脚本）。

提示

仅支持查询 definitionType 等于 "SCRIPT_JSON" 的自动化的详情。

请求参数

参数	类型	是否必需	说明
type	String	✓	请求消息类型，固定为 `GetAutomationDetailsRequest`
version	String	✓	接口版本号，固定为 `v1`
msgId	String	✓	由您定义的请求 ID。
data	String	✓	查询目标的自动化 ID。

请求参数示例

以下为 GetAutomationDetailsRequest 的请求体示例：

{
    "type": "GetAutomationDetailsRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": "auto_15b0cde_127312348967862272"
}

响应数据

字段	类型	说明
type	String	响应消息类型，固定为 `GetAutomationDetailsResponse`。
version	String	接口版本号，固定为 `v1`。
msgId	String	您发起请求时传入的 `msgId`。
data	Object	返回的自动化详情数据对象。
data.automationId	String	自动化ID。
data.definitionType	String	自动化类型。当前固定为 `"SCRIPT_JSON"`。
data.name	String	自动化名称。
data.enabled	Boolean	自动化的启用状态。
data.config	Object	JSON 自动化脚本。
data.createTime	Number	自动化创建时间，单位为毫秒的 UTC 时间戳。
code	Number	响应码。0表示成功，其他为错误码。
message	String 或 null	响应描述消息。为空字符串或 null 时表示请求成功。

响应数据示例

以下为 GetAutomationDetailsResponse 的响应示例：

{
    "type": "GetAutomationDetailsResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "automationId": "auto_15b0cde_127312348967862272",
        "definitionType": "SCRIPT_JSON",
        "name": "a3-1",
        "enabled": false,
        "config": {
            ...
        },
        "createTime": 1766043229326
    },
    "code": 0,
    "message": null
}

删除自动化

调用本接口，您可以删除多个自动化。

请求参数

参数	类型	是否必需	说明
type	String	✓	请求消息类型，固定为 `DeleteAutomationRequest`。
version	String	✓	接口版本号，固定为 `v1`。
msgId	String	✓	由您定义的请求 ID。
data	Array of String	✓	待删除的自动化 ID 数组，每个元素为对应的 automationId。

请求参数示例

以下为 DeleteAutomationRequest 的请求体示例：

{
    "type": "DeleteAutomationRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": ["auto_15b0b4d_1273030749213163"]
}

响应数据

字段	类型	说明
type	String	响应消息类型，固定为 `DeleteAutomationResponse`
version	String	接口版本号，固定为 `v1`
msgId	String	您发起请求时传入的 `msgId`。
code	Number	响应状态码，0 表示成功。非 0 表示失败。
message	String	响应描述信息。
data	Object	响应对象。
data.successIds	Array of String	删除成功的自动化 ID。
data.failedItems	Array of Object	删除失败的自动化对象。
data.failedItems.automationId	String	自动化 ID。
data.failedItems.code	Number	错误码。
data.failedItems.message	String	失败描述。

响应数据示例

{
    "type": "DeleteAutomationResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "code": 0,
    "message": "",
    "data": {
        "successIds": [
            "auto_15b0b4d_1273030749213163"
        ]
    }
}

获取可用于自动化的所有功能点信息​

请求参数​

请求参数示例​

响应数据​

响应数据示例​

创建自动化​

请求参数​

请求参数示例​

响应数据​

响应数据示例​

编辑自动化​

请求参数​

请求参数示例​

响应数据​

响应数据示例​

批量更新自动化状态​

请求参数​

请求参数示例​

响应数据​

响应数据示例​

查询自动化列表​

请求参数​

请求参数示例​

响应数据​

响应数据示例​

查询自动化详情​

请求参数​

请求参数示例​

响应数据​

响应数据示例​

删除自动化​

请求参数​

请求参数示例​

响应数据​

响应数据示例​

获取可用于自动化的所有功能点信息

请求参数

请求参数示例

响应数据

响应数据示例

创建自动化

请求参数

请求参数示例

响应数据

响应数据示例

编辑自动化

请求参数

请求参数示例

响应数据

响应数据示例

批量更新自动化状态

请求参数

请求参数示例

响应数据

响应数据示例

查询自动化列表

请求参数

请求参数示例

响应数据

响应数据示例

查询自动化详情

请求参数

请求参数示例

响应数据

响应数据示例

删除自动化

请求参数

请求参数示例

响应数据

响应数据示例