OpticalSystem/developer-front/public/docs/backend-integrations.md

后台接入

鉴权、接口调用与回调，国内与海外域名与限速差异，日志与监控。

鉴权

所有 API 请求都需要进行身份验证。

API 密钥

在请求头中包含您的 API 密钥：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求签名

对于敏感操作，需要使用签名验证：

const crypto = require('crypto')

function generateSignature(params, secret) {
    const sortedParams = Object.keys(params)
        .sort()
        .map(key => `${key}=${params[key]}`)
        .join('&')
    
    return crypto
        .createHmac('sha256', secret)
        .update(sortedParams)
        .digest('hex')
}

接口调用

RESTful API

基础 URL：

• 国内：https://api.jueyuan.com
• 海外：https://api-global.jueyuan.com

示例请求

const axios = require('axios')

const client = axios.create({
    baseURL: 'https://api.jueyuan.com',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
})

// 获取设备列表
const devices = await client.get('/v1/devices')

// 发送消息到设备
await client.post('/v1/devices/device-id/messages', {
    type: 'text',
    content: 'Hello World'
})

限速说明

不同接口有不同的限速策略：

• 普通接口：100 次/分钟
• 高频接口：1000 次/分钟
• 批量接口：10 次/分钟

超过限速会返回 429 Too Many Requests 错误。

回调处理

Webhook 配置

在开发者平台配置 Webhook URL，系统会在事件发生时调用该 URL。

回调验证

const crypto = require('crypto')

function verifyCallback(signature, payload, secret) {
    const hash = crypto
        .createHmac('sha256', secret)
        .update(JSON.stringify(payload))
        .digest('hex')
    
    return hash === signature
}

回调事件

常见回调事件：

• device.connected - 设备连接
• device.disconnected - 设备断开
• message.received - 收到消息
• voice.recognized - 语音识别完成

日志与监控

日志查询

// 查询设备日志
const logs = await client.get('/v1/devices/device-id/logs', {
    params: {
        startTime: '2024-01-01T00:00:00Z',
        endTime: '2024-01-02T00:00:00Z',
        level: 'error'
    }
})

监控指标

• API 调用次数
• 错误率
• 响应时间
• 设备在线率