566 lines
14 KiB
Markdown
566 lines
14 KiB
Markdown
# V2 API 文档
|
||
|
||
V2 API 提供基于消息模板的发送接口，支持占位符替换和多实例发送。
|
||
|
||
::: tip ⭐ 推荐使用
|
||
V2 API（模板）是我们推荐的消息发送方式，相比 V1 API 具有以下优势：
|
||
- ✅ **内容复用** - 一次定义，多处使用，大幅提高开发效率
|
||
- ✅ **灵活性** - 通过占位符实现动态内容，兼顾固定格式和动态数据
|
||
- ✅ **易维护** - 修改消息内容无需改代码，运营人员可直接操作
|
||
- ✅ **版本控制** - 支持模板启用/禁用，便于灰度发布和回滚
|
||
- ✅ **团队协作** - 开发和运营分工明确，提高协作效率
|
||
|
||
适用于 90% 的消息发送场景，特别是有固定格式的通知类消息。
|
||
:::
|
||
|
||
## 接口概述
|
||
|
||
V2 API 与 V1 API 的主要区别：
|
||
|
||
| 特性 | V1 API | V2 API |
|
||
|------|--------|--------|
|
||
| 发送方式 | 基于任务 | 基于模板 |
|
||
| 内容定义 | API 调用时传递 | 模板预定义 |
|
||
| 动态内容 | 不支持 | 支持占位符 |
|
||
| 多格式 | 单一格式 | Text/HTML/Markdown |
|
||
| 安全性 | Token 加密 | Token 加密 |
|
||
|
||
## 接口地址
|
||
|
||
```
|
||
POST /api/v2/message/send
|
||
```
|
||
|
||
## 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| token | string | 是 | 加密的模板 Token |
|
||
| title | string | 是 | 消息标题 |
|
||
| placeholders | object | 否 | 占位符键值对 |
|
||
| recipients | array | 条件必填 | 动态接收者列表（群发模式）🆕 |
|
||
|
||
### 参数说明
|
||
|
||
#### token
|
||
|
||
- 模板的加密 Token，在管理后台的"消息模板"页面获取
|
||
- **注意**：V2 API 只支持加密 Token，不支持明文模板 ID
|
||
- Token 使用对称加密算法生成，确保安全性
|
||
|
||
#### title
|
||
|
||
- 消息标题，会传递给所有支持标题的渠道（如邮件）
|
||
- 必填参数，不能为空
|
||
|
||
#### placeholders
|
||
|
||
- 占位符的键值对，用于替换模板中的 `{{key}}`
|
||
- 格式为 JSON 对象：`{"key": "value"}`
|
||
- 如果模板中定义了占位符但未传递，将使用默认值
|
||
- 如果既未传递也无默认值，占位符将保持原样
|
||
|
||
#### recipients 🆕
|
||
|
||
- 动态接收者列表，用于群发场景
|
||
- 格式为字符串数组：`["user1@example.com", "user2@example.com"]`
|
||
- **条件必填**：如果模板配置了动态接收实例，此参数为必填
|
||
- **支持的渠道**：
|
||
- ✅ 邮件 - 多个收件人邮箱地址
|
||
- ✅ 微信公众号 - 多个用户 OpenID
|
||
- **使用限制**：
|
||
- 一个模板只能配置一个动态接收实例
|
||
- 动态接收实例不能与固定接收实例混合使用
|
||
- 建议控制接收者数量，避免触发渠道限流
|
||
|
||
## 请求示例
|
||
|
||
### 基本示例
|
||
|
||
```bash
|
||
curl -X POST http://your-domain/api/v2/message/send \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
|
||
"title": "系统通知",
|
||
"placeholders": {
|
||
"username": "张三",
|
||
"action": "登录",
|
||
"time": "2024-12-06 12:00:00"
|
||
}
|
||
}'
|
||
```
|
||
|
||
### Python 示例
|
||
|
||
```python
|
||
import requests
|
||
import json
|
||
|
||
url = "http://your-domain/api/v2/message/send"
|
||
headers = {"Content-Type": "application/json"}
|
||
|
||
data = {
|
||
"token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
|
||
"title": "系统通知",
|
||
"placeholders": {
|
||
"username": "张三",
|
||
"action": "登录",
|
||
"time": "2024-12-06 12:00:00"
|
||
}
|
||
}
|
||
|
||
response = requests.post(url, headers=headers, data=json.dumps(data))
|
||
print(response.json())
|
||
```
|
||
|
||
### Go 示例
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"bytes"
|
||
"encoding/json"
|
||
"fmt"
|
||
"net/http"
|
||
)
|
||
|
||
func main() {
|
||
url := "http://your-domain/api/v2/message/send"
|
||
|
||
data := map[string]interface{}{
|
||
"token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
|
||
"title": "系统通知",
|
||
"placeholders": map[string]string{
|
||
"username": "张三",
|
||
"action": "登录",
|
||
"time": "2024-12-06 12:00:00",
|
||
},
|
||
}
|
||
|
||
jsonData, _ := json.Marshal(data)
|
||
resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
|
||
if err != nil {
|
||
fmt.Println("Error:", err)
|
||
return
|
||
}
|
||
defer resp.Body.Close()
|
||
|
||
var result map[string]interface{}
|
||
json.NewDecoder(resp.Body).Decode(&result)
|
||
fmt.Println(result)
|
||
}
|
||
```
|
||
|
||
### JavaScript/Node.js 示例
|
||
|
||
```javascript
|
||
const axios = require('axios');
|
||
|
||
const url = 'http://your-domain/api/v2/message/send';
|
||
|
||
const data = {
|
||
token: 'a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b',
|
||
title: '系统通知',
|
||
placeholders: {
|
||
username: '张三',
|
||
action: '登录',
|
||
time: '2024-12-06 12:00:00'
|
||
}
|
||
};
|
||
|
||
axios.post(url, data)
|
||
.then(response => {
|
||
console.log(response.data);
|
||
})
|
||
.catch(error => {
|
||
console.error('Error:', error);
|
||
});
|
||
```
|
||
|
||
### 动态接收者示例（群发）🆕
|
||
|
||
```javascript
|
||
const axios = require('axios');
|
||
|
||
const url = 'http://your-domain/api/v2/message/send';
|
||
|
||
const data = {
|
||
token: 'a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b',
|
||
title: '活动通知',
|
||
placeholders: {
|
||
activity_name: '双十二大促',
|
||
start_time: '2024-12-12 00:00:00',
|
||
discount: '全场8折'
|
||
},
|
||
recipients: [
|
||
'user1@example.com',
|
||
'user2@example.com',
|
||
'user3@example.com'
|
||
]
|
||
};
|
||
|
||
axios.post(url, data)
|
||
.then(response => {
|
||
console.log(response.data);
|
||
console.log(`成功发送给 ${response.data.data.count} 个接收者`);
|
||
})
|
||
.catch(error => {
|
||
console.error('Error:', error);
|
||
});
|
||
```
|
||
|
||
### Java 示例
|
||
|
||
```java
|
||
import java.io.OutputStream;
|
||
import java.net.HttpURLConnection;
|
||
import java.net.URL;
|
||
import java.nio.charset.StandardCharsets;
|
||
|
||
public class MessageSender {
|
||
public static void main(String[] args) throws Exception {
|
||
String url = "http://your-domain/api/v2/message/send";
|
||
|
||
String jsonData = """
|
||
{
|
||
"token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
|
||
"title": "系统通知",
|
||
"placeholders": {
|
||
"username": "张三",
|
||
"action": "登录",
|
||
"time": "2024-12-06 12:00:00"
|
||
}
|
||
}
|
||
""";
|
||
|
||
HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
|
||
conn.setRequestMethod("POST");
|
||
conn.setRequestProperty("Content-Type", "application/json");
|
||
conn.setDoOutput(true);
|
||
|
||
try (OutputStream os = conn.getOutputStream()) {
|
||
byte[] input = jsonData.getBytes(StandardCharsets.UTF_8);
|
||
os.write(input, 0, input.length);
|
||
}
|
||
|
||
int responseCode = conn.getResponseCode();
|
||
System.out.println("Response Code: " + responseCode);
|
||
}
|
||
}
|
||
```
|
||
|
||
## 响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
|
||
"count": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应字段说明：**
|
||
|
||
- `code` - 状态码，200 表示成功
|
||
- `msg` - 响应消息
|
||
- `data.token` - 使用的模板 Token
|
||
- `data.count` - 成功发送的实例数量
|
||
|
||
### 失败响应
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "token解析失败：invalid token format",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 工作流程
|
||
|
||
1. **Token 解析** - 解密 Token 获取模板 ID
|
||
2. **模板查询** - 根据模板 ID 查询模板信息
|
||
3. **状态检查** - 检查模板是否启用
|
||
4. **占位符替换** - 使用传入的 placeholders 替换模板中的占位符
|
||
5. **实例遍历** - 获取模板关联的所有启用实例
|
||
6. **格式匹配** - 根据实例的 ContentType 选择对应格式的内容
|
||
7. **消息发送** - 向每个实例发送消息
|
||
8. **返回结果** - 返回发送成功的实例数量
|
||
|
||
## 占位符替换规则
|
||
|
||
### 基本规则
|
||
|
||
模板中使用 `{{key}}` 定义占位符，API 调用时通过 `placeholders` 参数传递替换值。
|
||
|
||
**模板内容：**
|
||
```text
|
||
您好，{{username}}！
|
||
您的订单 {{order_id}} 已经 {{status}}。
|
||
```
|
||
|
||
**API 调用：**
|
||
```json
|
||
{
|
||
"placeholders": {
|
||
"username": "张三",
|
||
"order_id": "20241206001",
|
||
"status": "发货"
|
||
}
|
||
}
|
||
```
|
||
|
||
**替换结果：**
|
||
```text
|
||
您好，张三！
|
||
您的订单 20241206001 已经发货。
|
||
```
|
||
|
||
### 默认值处理
|
||
|
||
如果占位符定义了默认值，未传递时使用默认值：
|
||
|
||
**占位符定义：**
|
||
```json
|
||
[
|
||
{
|
||
"key": "username",
|
||
"label": "用户名",
|
||
"default": "Guest"
|
||
}
|
||
]
|
||
```
|
||
|
||
**API 调用（未传递 username）：**
|
||
```json
|
||
{
|
||
"placeholders": {}
|
||
}
|
||
```
|
||
|
||
**替换结果：**
|
||
```text
|
||
您好，Guest！
|
||
```
|
||
|
||
### 未定义占位符
|
||
|
||
如果占位符既未传递也无默认值，将保持原样：
|
||
|
||
```text
|
||
您好，{{username}}！ // username 未传递且无默认值
|
||
```
|
||
|
||
## 内容格式选择
|
||
|
||
V2 API 支持三种内容格式，系统会根据实例配置自动选择：
|
||
|
||
| 格式 | 适用渠道 | 说明 |
|
||
|------|---------|------|
|
||
| Text | 所有渠道 | 纯文本格式，兼容性最好 |
|
||
| HTML | 邮件 | 富文本格式，支持样式 |
|
||
| Markdown | 钉钉、企业微信 | Markdown 格式，支持格式化 |
|
||
|
||
**示例：**
|
||
|
||
假设模板定义了三种格式的内容：
|
||
|
||
- Text: `您好，{{username}}！`
|
||
- HTML: `<h2>您好，{{username}}！</h2>`
|
||
- Markdown: `## 您好，{{username}}！`
|
||
|
||
当发送到不同实例时：
|
||
|
||
- **邮件实例（ContentType=html）** → 使用 HTML 格式
|
||
- **钉钉实例（ContentType=markdown）** → 使用 Markdown 格式
|
||
- **其他实例（ContentType=text）** → 使用 Text 格式
|
||
|
||
## @提醒功能
|
||
|
||
如果模板配置了@提醒，会自动应用到支持的渠道（钉钉、企业微信）。
|
||
|
||
**模板配置：**
|
||
- @手机号：`13800138000,13900139000`
|
||
- @用户ID：`user001,user002`
|
||
- @所有人：是
|
||
|
||
**发送效果：**
|
||
- 钉钉/企业微信会@指定的手机号或用户
|
||
- 如果启用@所有人，会@群内所有成员
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 | 解决方案 |
|
||
|--------|------|---------|
|
||
| 200 | 成功 | - |
|
||
| 400 | 请求参数错误 | 检查请求参数格式 |
|
||
| 400 | token解析失败 | 检查 Token 是否正确 |
|
||
| 400 | 模板不存在 | 检查模板 ID 是否有效 |
|
||
| 400 | 模板已禁用 | 在管理后台启用模板 |
|
||
| 400 | 模板没有配置发送实例 | 为模板添加发送实例 |
|
||
| 400 | 模板没有启用的发送实例 | 启用至少一个实例 |
|
||
| 500 | 服务器内部错误 | 联系管理员 |
|
||
|
||
## 获取模板 Token
|
||
|
||
### 方式一：管理后台查看
|
||
|
||
1. 登录 Message Nest 管理后台
|
||
2. 进入"消息模板"页面
|
||
3. 点击模板的"接口"按钮
|
||
4. 查看并复制加密的 Token
|
||
|
||
### 方式二：API 代码示例
|
||
|
||
管理后台提供多种语言的 API 调用示例，包含真实的加密 Token。
|
||
|
||
## 安全性说明
|
||
|
||
### Token 加密
|
||
|
||
- V2 API 使用对称加密算法保护模板 ID
|
||
- Token 是确定性加密，相同的模板 ID 生成相同的 Token
|
||
- 加密密钥存储在服务器端，客户端无需关心加密细节
|
||
|
||
### 最佳实践
|
||
|
||
1. **Token 保护**
|
||
- 不要在公开代码中硬编码 Token
|
||
- 使用环境变量或配置文件存储 Token
|
||
- 定期检查 Token 的使用情况
|
||
|
||
2. **权限控制**
|
||
- 合理设置模板的启用/禁用状态
|
||
- 及时禁用不再使用的模板
|
||
- 定期审查模板配置
|
||
|
||
3. **内容安全**
|
||
- 注意模板内容的合规性
|
||
- 避免在模板中包含敏感信息
|
||
- 对用户输入进行验证和过滤
|
||
|
||
## 使用场景
|
||
|
||
### 1. 用户通知
|
||
|
||
```json
|
||
{
|
||
"token": "...",
|
||
"title": "账号安全提醒",
|
||
"placeholders": {
|
||
"username": "张三",
|
||
"action": "登录",
|
||
"ip": "192.168.1.100",
|
||
"time": "2024-12-06 12:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 订单通知
|
||
|
||
```json
|
||
{
|
||
"token": "...",
|
||
"title": "订单状态更新",
|
||
"placeholders": {
|
||
"order_id": "20241206001",
|
||
"status": "已发货",
|
||
"tracking_number": "SF1234567890",
|
||
"estimated_delivery": "2024-12-08"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 系统告警
|
||
|
||
```json
|
||
{
|
||
"token": "...",
|
||
"title": "系统告警",
|
||
"placeholders": {
|
||
"service": "API Server",
|
||
"level": "严重",
|
||
"message": "CPU使用率超过90%",
|
||
"time": "2024-12-06 12:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 营销推广
|
||
|
||
```json
|
||
{
|
||
"token": "...",
|
||
"title": "优惠活动通知",
|
||
"placeholders": {
|
||
"username": "张三",
|
||
"product": "VIP会员",
|
||
"discount": "8折",
|
||
"expire_date": "2024-12-31"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
### 异步发送
|
||
|
||
V2 API 采用异步发送机制，API 调用立即返回，实际发送在后台进行。
|
||
|
||
**优点：**
|
||
- 快速响应，不阻塞调用方
|
||
- 支持批量发送多个实例
|
||
- 自动重试失败的发送
|
||
|
||
### 批量发送
|
||
|
||
一次 API 调用可以发送到多个实例（渠道），系统自动遍历所有启用的实例。
|
||
|
||
**示例：**
|
||
|
||
模板配置了 3 个实例：
|
||
- 邮件实例（启用）
|
||
- 钉钉实例（启用）
|
||
- 企业微信实例（禁用）
|
||
|
||
调用 API 后，消息会发送到邮件和钉钉，企业微信实例被跳过。
|
||
|
||
## 常见问题
|
||
|
||
### Q: V1 和 V2 API 可以同时使用吗？
|
||
|
||
**A:** 可以。V1 和 V2 API 是独立的，可以根据需求选择使用。
|
||
|
||
### Q: 如何从 V1 迁移到 V2？
|
||
|
||
**A:**
|
||
1. 创建消息模板，定义占位符
|
||
2. 为模板配置发送实例
|
||
3. 获取模板 Token
|
||
4. 修改 API 调用代码，使用 V2 接口
|
||
|
||
### Q: 占位符可以嵌套吗？
|
||
|
||
**A:** 不支持。占位符只支持一级替换，不支持嵌套或递归。
|
||
|
||
### Q: 可以动态添加占位符吗？
|
||
|
||
**A:** 不可以。占位符必须在模板中预先定义，API 调用时只能传递已定义的占位符。
|
||
|
||
### Q: 如何调试模板？
|
||
|
||
**A:** 使用管理后台的"预览"功能，可以填写测试数据查看替换效果。
|
||
|
||
## 下一步
|
||
|
||
- 查看 [消息模板文档](/guide/template) 了解如何创建和管理模板
|
||
- 查看 [V1 API 文档](/api/usage) 了解传统的发送方式
|
||
- 查看 [API 示例](/api/examples) 了解更多调用示例
|