coal/doc/notifyClient-debugPush-api.md

通知客户端调试接口文档

接口说明

手动发送通知给指定的客户端，用于测试和调试通知功能。

接口地址

POST /notifyClient/debugPush

请求参数

{
  "targetAccessKey": "ak-xxxx-xxxx-xxxx",  // 必填：目标客户端的 AccessKey
  "content": "这是一条测试消息",           // 必填：消息内容
  "metadata": {                            // 可选：元数据
    "title": "测试通知",
    "priority": "high",
    "category": "system"
  },
  "deadline": 1737859200                   // 可选：截止时间（Unix时间戳，秒），不填默认为1小时后
}

参数说明

参数名	类型	必填	说明
targetAccessKey	String	是	目标客户端的 AccessKey，可以从客户端列表中获取
content	String	是	消息内容，支持纯文本或 Markdown 格式
metadata	Object	否	元数据键值对，用于传递额外信息
deadline	Long	否	消息截止时间（Unix时间戳，秒），超过这个时间的消息不会被投递。不填默认为当前时间+1小时

响应结果

成功响应

{
  "success": true,
  "messageId": "msg-xxxx-xxxx-xxxx",
  "targetAccessKey": "ak-xxxx-xxxx-xxxx",
  "targetClientName": "测试客户端",
  "serverUrl": "grpc://localhost:50051",
  "timestamp": 1737859200000
}

失败响应

{
  "success": false,
  "error": "目标客户端不存在: ak-xxxx-xxxx-xxxx",
  "targetAccessKey": "ak-xxxx-xxxx-xxxx",
  "timestamp": 1737859200000
}

使用示例

cURL 示例

curl -X POST http://localhost:8080/notifyClient/debugPush \
  -H "Content-Type: application/json" \
  -d '{
    "targetAccessKey": "ak-123e4567-e89b-12d3-a456-426614174000",
    "content": "这是一条测试消息",
    "metadata": {
      "title": "系统通知",
      "priority": "high"
    }
  }'

JavaScript 示例

fetch('http://localhost:8080/notifyClient/debugPush', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    targetAccessKey: 'ak-123e4567-e89b-12d3-a456-426614174000',
    content: '这是一条测试消息',
    metadata: {
      title: '系统通知',
      priority: 'high'
    }
  })
})
.then(response => response.json())
.then(data => console.log('推送结果:', data))
.catch(error => console.error('推送失败:', error));

Python 示例

import requests
import time

url = 'http://localhost:8080/notifyClient/debugPush'
payload = {
    'targetAccessKey': 'ak-123e4567-e89b-12d3-a456-426614174000',
    'content': '这是一条测试消息',
    'metadata': {
        'title': '系统通知',
        'priority': 'high'
    },
    'deadline': int(time.time()) + 3600  # 1小时后过期
}

response = requests.post(url, json=payload)
print('推送结果:', response.json())

常见问题

Q1: 如何获取客户端的 AccessKey？

A: 通过 /notifyClient/list 接口查询客户端列表，返回结果中包含每个客户端的 ak 字段。

Q2: 消息推送失败怎么办？

A: 检查以下几点：

1. 目标客户端的 AccessKey 是否正确
2. 通知服务器地址是否正确配置
3. 目标客户端是否在线并已连接到通知服务器
4. 查看服务器日志获取详细错误信息

Q3: deadline 参数应该填什么值？

A: deadline 是 Unix 时间戳（秒），表示消息的截止时间。可以使用：

• JavaScript: Math.floor(Date.now() / 1000) + 3600 // 1小时后
• Python: int(time.time()) + 3600 // 1小时后
• 不填则默认为当前时间+1小时

Q4: metadata 可以放什么数据？

A: metadata 是一个键值对对象，所有的 key 和 value 都必须是字符串类型。常用的字段有：

• title: 消息标题
• priority: 优先级（low/normal/high）
• category: 分类（system/business/alert等）
• 其他自定义字段

注意事项

1. 此接口仅用于调试和测试，生产环境中应该通过正常的业务流程发送通知
2. 消息内容建议不超过 10KB
3. 如果目标客户端不在线，消息会在客户端下次连接时投递（deadline 未过期的情况下）
4. 建议在调用前先通过 /notifyClient/getById 接口确认目标客户端存在