一、接口总览
| 接口名称 | 功能描述 | 请求方式 | 授权方式 | 接口版本 |
|---|---|---|---|---|
| 获取通知列表（getNotifications） | 获取当前用户相关的通知信息，支持按需返回字段及全部通知查询 | GET / POST | JWT / Bearer Token 授权 | v1 |
二、获取通知列表接口（getNotifications）
用于获取当前授权用户相关的通知信息，支持通过
all参数控制是否获取全部通知，支持 GraphQL 按需指定返回字段，未指定字段不会出现在响应中。（一）请求说明
1. 请求URL
GET: /vsaas/api/v1/be?query={getNotifications(all:Boolean) {字段1,字段2,...}}
POST: /vsaas/api/v1/be/
说明：支持GET和POST两种请求方式，推荐使用POST方式
说明：
all为可选参数，用于控制是否返回全部通知数据。2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
all | Boolean | 否 | GraphQL参数 QUERY | 是否获取全部通知，默认值：false（按系统规则返回，如仅返回未读通知） |
4. 请求体（POST 方式专用）
{
"query": "query {getNotifications(all:true) {sender,senderName,receiver,type,pk,purpose,purposeDetail,description}}"
}
说明：查询语句中可按需指定返回字段（字段列表见「Notification 对象字段说明」），未指定的字段不会出现在响应数据中。
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回通知列表数据 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、参数格式不合法） |
| 401 | 授权失败 | 授权令牌无效或过期 |
| 500 | 服务器错误 | 服务器内部错误，请联系技术支持排查 |
2. 响应数据结构
{
"data": {
"getNotifications": [
{
"pk": "String", // 通知唯一ID（主键）
"sender": "String", // 通知创建者ID
"senderName": "String", // 通知创建者名称（需指定返回）
"senderEmail": "String", // 通知创建者邮箱（需指定返回）
"senderPhone": "String", // 通知创建者手机号（需指定返回）
"receiver": "String", // 通知接收者ID
"receiverName": "String", // 通知接收者名称（需指定返回）
"receiverEmail": "String", // 通知接收者邮箱（需指定返回）
"receiverPhone": "String", // 通知接收者手机号（需指定返回）
"purpose": "String", // 通知用途标识（如设备UDID）（需指定返回）
"purposeDetail": "String", // 通知用途详情（需指定返回）
"description": "String", // 通知描述信息（需指定返回）
"type": "String", // 通知类型（需指定返回）
"data": "String" // 附加凭证数据（需指定返回）
}
// 更多通知...
]
}
}
3. 响应参数说明
| 字段名 | 类型 | 说明 | 返回规则 |
|---|---|---|---|
pk | String | 通知唯一ID（主键） | 必返回（无需额外指定） |
sender | String | 通知创建者ID | 必返回（无需额外指定） |
senderName | String | 通知创建者名称 | 可选返回（需在查询中指定） |
senderEmail | String | 通知创建者邮箱 | 可选返回（需在查询中指定） |
senderPhone | String | 通知创建者手机号 | 可选返回（需在查询中指定） |
receiver | String | 通知接收者ID | 必返回（无需额外指定） |
receiverName | String | 通知接收者名称 | 可选返回（需在查询中指定） |
receiverEmail | String | 通知接收者邮箱 | 可选返回（需在查询中指定） |
receiverPhone | String | 通知接收者手机号 | 可选返回（需在查询中指定） |
purpose | String | 通知用途标识（如设备UDID等） | 可选返回（需在查询中指定） |
purposeDetail | String | 通知用途详情 | 可选返回（需在查询中指定） |
description | String | 通知描述信息 | 可选返回（需在查询中指定） |
type | String | 通知类型（目前支持：DeviceSharing） | 可选返回（需在查询中指定） |
data | String | 附加凭证数据 | 可选返回（需在查询中指定） |
（三）接口示例
1. 请求示例（curl）
POST方式请求（示例）
curl --location --request POST 'domain/vsaas/api/v1/be/' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "query {getNotifications(all:true) {sender,senderName,receiver,receiverName,type,description,pk,purpose,purposeDetail}}"
}'
GET方式请求（示例）
curl --location --request GET 'domain/vsaas/api/v1/be?query={getNotifications(all:true) {sender,senderName,receiver,type,pk}}' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json'
2. 响应示例（成功）
通知列表响应（示例）
{
"data": {
"getNotifications": [
{
"sender": "5dc3c96edd188dd0ce4e3976",
"senderName": "jerry_yang",
"senderEmail": "[email protected]",
"receiver": "5fe190807f5a7abd27220461",
"receiverName": "test_user",
"receiverEmail": "[email protected]",
"type": "DeviceSharing",
"description": "[email protected] want to share device : KGGJYP with you.",
"pk": "5fe1be9f21d016afe3d80369",
"purpose": "POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP",
"purposeDetail": "Device sharing request",
"data": "thisisacredential"
}
]
}
}
三、错误码说明
| 错误码 | 错误描述 | 解决方案 |
|---|---|---|
400 | Bad Request | 检查GraphQL查询语法是否正确，参数格式是否合法（如all参数是否为布尔值、字段名是否拼写正确）；必填参数是否完整传递 |
401 | Unauthorized | 检查token是否有效、未过期，授权格式是否正确（JWT/Bearer前缀是否完整）；重新获取有效的授权令牌 |
429 | Too Many Requests | 接口调用频率超出限制（每分钟最多30次），需等待1分钟后重试 |
500 | Internal Server Error | 服务器内部错误，请联系技术支持排查；确认接口域名是否正确、服务是否正常运行 |
