飞阳网关HTTP接口协议文档

2024-06-01 约 1961 字预计阅读 4 分钟次阅读

🔌 飞阳智控云平台提供完整的开放能力接口，通过标准化的HTTPS协议实现与智能网关设备的安全通信。本文档详细阐述了接口协议规范、API定义及典型应用场景，帮助开发者快速集成飞阳智能家居解决方案。

📋 接口清单

👤 用户接口

接口名称	请求方法	路径	说明
获取网关设备列表	GET	`/mcp/user/gateway/devices`	获取用户网关设备列表
设备控制	POST	`/mcp/user/device/control`	控制设备执行特定命令
TTS服务	POST	`/mcp/user/device/tts`	文本转语音或播放音频

📝 接口详细说明

1️⃣ 获取网关设备列表

接口路径: GET /mcp/user/gateway/devices

请求参数:

参数名	类型	必填	位置	说明
auth	String	是	Query	网关设备密钥

响应数据:

        
        
        
    
{
  "code": 0,
  "message": "成功获取设备响应",
  "data": {
    "homelist": [
      {
        "id": "224001002695",
        "name": "我的家",
        "address": "上地6号",
        "roomlist": [
          {
            "id": "224001002696",
            "name": "客厅",
            "dids": [
              {
                "did": "1",
                "name": "客厅台灯",
                "model": "mi.switch",
                "isOnline": true
              }
            ]
          }
        ]
      }
    ]
  }
}

错误码说明:

0: 成功获取设备响应
40000: 系统错误/获取设备列表失败

2️⃣ 设备控制

接口路径: POST /mcp/user/device/control

请求体:

        
{
  "auth": "网关设备密钥",
  "command": "控制指令",
  "silence": false
}

请求参数:

参数名	类型	必填	说明
auth	String	是	网关设备密钥
command	String	是	控制指令
silence	Boolean	否	是否静默模式，默认为false

响应数据:

        
        
        
    
{
  "code": 0,
  "message": "设备控制成功",
  "data": {
    "requestId": "app_ios_abc123def456",
    "response": {
      "cmd": "902",
      "status": "success",
      "result": {...}
    },
    "timestamp": 1719834567,
    "cmd": "902"
  }
}

错误码说明:

0: 设备控制成功
10002: 控制指令不能为空
40000: 设备控制失败

3️⃣ TTS服务

接口路径: POST /mcp/user/device/tts

请求体:

        
        
        
    
{
  "auth": "网关设备密钥",
  "text": "你好小爱",
  "audio_url": "https://oneapi.sooncore.com/ota/tts/audio/test_xiaoai_tts.mp3",
  "volume": 5,
  "silence": false,
  "execute": false
}

请求参数:

参数名	类型	必填	说明
auth	String	是	网关设备密钥
text	String	否*	要转换为语音的文本
audio_url	String	否*	音频URL
volume	Integer	否	音量大小，默认为5
silence	Boolean	否	是否静默模式，默认为false
execute	Boolean	否	是否执行，默认为false

*注意：text和audio_url至少需要提供一个

响应数据:

        
        
        
    
{
  "code": 0,
  "message": "TTS执行成功",
  "data": {
    "requestId": "app_ios_abc123def456",
    "response": {
      "cmd": "902",
      "status": "success",
      "result": {...}
    },
    "timestamp": 1719834567,
    "cmd": "902"
  }
}

错误码说明:

0: TTS执行成功
10002: 文本或音频URL不能同时为空
40000: TTS执行失败
40001: 必须提供文本或音频URL

📡 通信协议说明

飞阳智控平台使用标准HTTPS协议与智能网关设备进行安全通信。在实现架构中，系统支持两种核心消息类型：

控制消息: 从云平台发送到智能网关的指令数据
状态消息: 从智能网关回传到云平台的设备状态更新

📝 注意: 所有通信数据采用JSON格式，支持加密传输和完整的错误处理机制

🧪 示例代码

📋 多语言调用示例

cURL 示例

        
        
        
    
# 获取设备列表
curl -X GET "https://oneapi.sooncore.com/weilaiapi/mcp/user/gateway/devices?auth=您的设备密钥"

# 控制设备
curl -X POST "https://oneapi.sooncore.com/weilaiapi/mcp/user/device/control" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": "您的设备密钥",
    "command": "控制指令",
    "silence": false
  }'

# TTS 服务
curl -X POST "https://oneapi.sooncore.com/weilaiapi/mcp/user/device/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": "您的设备密钥",
    "text": "你好小爱",
    "audio_url": "https://oneapi.sooncore.com/ota/tts/audio/test_xiaoai_tts.mp3",
    "volume": 5,
    "silence": false,
    "execute": false
  }'

JavaScript (Fetch API)

        
        
        
    
// 获取设备列表示例
async function getDevices(authKey) {
  try {
    const response = await fetch(
      `https://oneapi.sooncore.com/weilaiapi/mcp/user/gateway/devices?auth=${authKey}`,
      { method: 'GET' }
    );
    const data = await response.json();
    console.log('设备列表:', data);
    return data;
  } catch (error) {
    console.error('获取设备失败:', error);
  }
}

// 控制设备示例
async function controlDevice(authKey, command) {
  try {
    const response = await fetch(
      'https://oneapi.sooncore.com/weilaiapi/mcp/user/device/control',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          auth: authKey,
          command: command,
          silence: false
        })
      }
    );
    const result = await response.json();
    console.log('控制结果:', result);
    return result;
  } catch (error) {
    console.error('控制设备失败:', error);
  }
}

Python 示例

        
        
        
    
import requests

# 设置基本参数
BASE_URL = "https://oneapi.sooncore.com/weilaiapi"
AUTH_KEY = "您的设备密钥"

# 获取设备列表
def get_devices():
    url = f"{BASE_URL}/mcp/user/gateway/devices"
    params = {"auth": AUTH_KEY}
    
    response = requests.get(url, params=params)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"获取设备失败: {response.status_code}")
        return None

# 控制设备
def control_device(command):
    url = f"{BASE_URL}/mcp/user/device/control"
    payload = {
        "auth": AUTH_KEY,
        "command": command,
        "silence": False
    }
    
    response = requests.post(url, json=payload)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"控制设备失败: {response.status_code}")
        return None

# 使用TTS服务
def tts_service(text=None, audio_url=None):
    url = f"{BASE_URL}/mcp/user/device/tts"
    payload = {
        "auth": AUTH_KEY,
        "volume": 5,
        "silence": False,
        "execute": False
    }
    
    # 至少需要提供text或audio_url之一
    if text:
        payload["text"] = text
    if audio_url:
        payload["audio_url"] = audio_url
        
    response = requests.post(url, json=payload)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"TTS服务调用失败: {response.status_code}")
        return None

# 使用示例
if __name__ == "__main__":
    # 获取设备列表
    devices = get_devices()
    print("设备列表:", devices)
    
    # 控制设备
    result = control_device("打开客厅灯")
    print("控制结果:", result)

⚠️ 错误码说明

错误码	说明
0	成功
10002	参数错误
40000	系统错误/操作失败
40001	参数校验失败
40002	网络连接失败
40003	设备响应超时

🔐 安全考虑

API认证: 所有接口都需要提供网关设备密钥（auth参数）进行身份验证
HTTPS加密: 采用TLS 1.2+协议确保传输层数据安全
超时保护: 服务端设置了30秒的请求超时时间，有效防止资源耗尽
访问控制: 基于设备ID和密钥的细粒度权限控制
日志审计: 所有API调用都有完整的访问日志记录，支持安全审计

🔄 相关资源

📦 项目仓库: https://gitee.com/panzuji/ha-esp32
📚 完整技术文档: https://bxk64web49.feishu.cn/docx/XAVJdha5FoI5bjxKELqcz3rJnwg
💾 固件下载: https://gitee.com/panzuji/ha-esp32/releases

目录

飞阳网关HTTP接口协议文档

📋 接口清单

👤 用户接口

📝 接口详细说明

1️⃣ 获取网关设备列表

请求参数:

响应数据:

错误码说明:

2️⃣ 设备控制

请求体:

请求参数:

响应数据:

错误码说明:

3️⃣ TTS服务

请求体:

请求参数:

响应数据:

错误码说明:

📡 通信协议说明

🧪 示例代码

📋 多语言调用示例

cURL 示例

JavaScript (Fetch API)

Python 示例

⚠️ 错误码说明

🔐 安全考虑

🔄 相关资源