数据转出 API v1

Aqara 提供数据转出 API v1 接口，帮助您访问 Studio 系统的设备数据并开展二次开发。

接口支持设备数据的查询与订阅、设备控制、设备增删事件通知及场景列表查询。

通信协议

Studio API 的接口支持 HTTP 与 WebSocket 两种通信协议。

请求说明

根据是否启用远程访问功能，请求 URL 的格式有所不同。

HTTP 请求 URL

请求方法：POST
请求 URL 格式：

未开启远程访问：http://局域网内网IP/open/api/v1
已开启远程访问：http://远程访问地址/open/api/v1

WebSocket 请求 URL

请求 URL 格式：

未开启远程访问：ws://局域网内网IP/open/ws
已开启远程访问：ws://远程访问地址/open/ws

建立连接后，可通过发送/接收 JSON 消息与服务器进行实时通信。

参数	类型	是否必须	说明
Authorization	String	HTTP 和 WebSocket 必须	授权 Token，用于用户身份验证。格式为 `Bearer <token>`，将 `<token>` 替换为您从 Aqara Studio 获取的 Token 字符串（若从 Aqara Studio 获取的令牌已带 Bearer 前缀，请直接使用，无需重复添加）。如需了解获取方式，请参考开发者指南 - 获取必要信息中对 Token 的说明。
Content-Type	String	仅适用 HTTP	默认为`application/json`。

API 列表

Aqara Studio 会依据请求体中的 type 字段，决定并响应不同的 API 功能。下表汇总了当前 Aqara Studio 支持的全部 API 及其对应的请求与响应类型：

API 功能	请求 type	响应 type
分页查询设备 ID 列表	GetDeviceInfoRequest	GetDeviceInfoResponse
全量查询设备 ID 列表	GetAllDeviceInfoRequest	GetAllDeviceInfoResponse
查询设备的 spec 配置	GetDevicesRequest	GetDevicesResponse
控制设备	ExecuteTraitRequest	ExecuteTraitResponse
查询设备的最新功能点值	GetTraitValueRequest	GetTraitValueResponse
订阅多个功能点变化	SubscribeTraitValueRequest	SubscribeTraitValueResponse
取消订阅功能点变化	UnsubscribeTraitValueRequest	UnsubscribeTraitValueResponse
订阅所有功能点变化	SubscribeAllRequest	SubscribeAllResponse
取消订阅所有功能点变化	UnsubscribeAllRequest	UnsubscribeAllResponse
对象事件消息推送	-	objectEvent
查询设备历史数据	QueryDeviceHistoryDataRequest	QueryDeviceHistoryDataResponse
创建自动化	CreateScriptAutomationRequest	CreateScriptLinkageResponse
编辑自动化脚本	UpdateScriptAutomationRequest	UpdateScriptAutomationResponse
修改自动化名称及启用状态	UpdateScriptAutomationRequest	UpdateScriptAutomationResponse
查询自动化列表	GetScriptAutomationListRequest	GetScriptAutomationListResponse
查询自动化详情	GetScriptAutomationDetailsRequest	GetScriptAutomationDetailsResponse
删除自动化	DeleteAutomationRequest	DeleteAutomationResponse

错误处理

当你发起 API 请求后，如果收到如下的错误响应，不要灰心，这其实是帮助你排查问题的重要线索。

以下通过一个示例，快速教你如何理解和修复问题：

{
    "type": "ErrorMessage",
    "version": "v1",
    "msgId": "UNKNOWN",
    "code": 1000,
    "message": "Message parsing failed: Unexpected JSON token at offset 0: Serializer for subclass 'GetDeviceInfo' is not found in the polymorphic scope of 'WebSocketMessageRequest' at path: $\nCheck if class with serial name 'GetDeviceInfo' exists and serializer is registered in a corresponding SerializersModule.\nTo be registered automatically, class 'GetDeviceInfo' has to be '@Serializable', and the base class 'WebSocketMessageRequest' has to be sealed and '@Serializable'.\nJSON input: {\n    \"type\": \"GetDeviceInfo\",....."
}

关注 type 字段

首先，查看返回结果中的 type 字段。所有失败的请求，其值均为 ErrorMessage。
核查 msgId 字段

如果请求格式有误，msgId 字段通常为 UNKNOWN，说明服务器未能识别有效的请求 ID。
仔细阅读 message 字段获取详情

message 字段会提供详细的错误信息，通常包含最关键的排查线索，如参数缺失、数据类型错误等。请认真阅读该内容，明确需要调整和修正的具体问题。

通信协议​

请求说明​

HTTP 请求 URL​

WebSocket 请求 URL​

请求头（Header）​

API 列表​

错误处理​