131 lines
2.4 KiB
Markdown
131 lines
2.4 KiB
Markdown
# 后台接入
|
||
|
||
鉴权、接口调用与回调，国内与海外域名与限速差异，日志与监控。
|
||
|
||
## 鉴权
|
||
|
||
所有 API 请求都需要进行身份验证。
|
||
|
||
### API 密钥
|
||
|
||
在请求头中包含您的 API 密钥：
|
||
|
||
```http
|
||
Authorization: Bearer YOUR_API_KEY
|
||
Content-Type: application/json
|
||
```
|
||
|
||
### 请求签名
|
||
|
||
对于敏感操作，需要使用签名验证：
|
||
|
||
```javascript
|
||
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`
|
||
|
||
### 示例请求
|
||
|
||
```javascript
|
||
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。
|
||
|
||
### 回调验证
|
||
|
||
```javascript
|
||
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` - 语音识别完成
|
||
|
||
## 日志与监控
|
||
|
||
### 日志查询
|
||
|
||
```javascript
|
||
// 查询设备日志
|
||
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 调用次数
|
||
- 错误率
|
||
- 响应时间
|
||
- 设备在线率
|
||
|