一、接口總覽
| 接口名稱 | 功能描述 | 請求方式 | 授權(quán)方式 | 接口版本 |
|---|---|---|---|---|
| 獲取通知列表（getNotifications） | 獲取當(dāng)前用戶相關(guān)的通知信息，支持按需返回字段及全部通知查詢 | GET / POST | JWT / Bearer Token 授權(quán) | v1 |
二、獲取通知列表接口（getNotifications）
用于獲取當(dāng)前授權(quán)用戶相關(guān)的通知信息，支持通過
all參數(shù)控制是否獲取全部通知，支持 GraphQL 按需指定返回字段，未指定字段不會出現(xiàn)在響應(yīng)中。（一）請求說明
1. 請求URL
GET: /vsaas/api/v1/be?query={getNotifications(all:Boolean) {字段1,字段2,...}}
POST: /vsaas/api/v1/be/
說明：支持GET和POST兩種請求方式，推薦使用POST方式
說明：
all為可選參數(shù)，用于控制是否返回全部通知數(shù)據(jù)。2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
all | Boolean | 否 | GraphQL參數(shù) QUERY | 是否獲取全部通知，默認(rèn)值：false（按系統(tǒng)規(guī)則返回，如僅返回未讀通知） |
4. 請求體（POST 方式專用）
{
"query": "query {getNotifications(all:true) {sender,senderName,receiver,type,pk,purpose,purposeDetail,description}}"
}
說明：查詢語句中可按需指定返回字段（字段列表見「Notification 對象字段說明」），未指定的字段不會出現(xiàn)在響應(yīng)數(shù)據(jù)中。
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回通知列表數(shù)據(jù) |
| 400 | 參數(shù)錯(cuò)誤 | 請求參數(shù)錯(cuò)誤（如GraphQL語法錯(cuò)誤、參數(shù)格式不合法） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
| 500 | 服務(wù)器錯(cuò)誤 | 服務(wù)器內(nèi)部錯(cuò)誤，請聯(lián)系技術(shù)支持排查 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"getNotifications": [
{
"pk": "String", // 通知唯一ID（主鍵）
"sender": "String", // 通知創(chuàng)建者ID
"senderName": "String", // 通知創(chuàng)建者名稱（需指定返回）
"senderEmail": "String", // 通知創(chuàng)建者郵箱（需指定返回）
"senderPhone": "String", // 通知創(chuàng)建者手機(jī)號（需指定返回）
"receiver": "String", // 通知接收者ID
"receiverName": "String", // 通知接收者名稱（需指定返回）
"receiverEmail": "String", // 通知接收者郵箱（需指定返回）
"receiverPhone": "String", // 通知接收者手機(jī)號（需指定返回）
"purpose": "String", // 通知用途標(biāo)識（如設(shè)備UDID）（需指定返回）
"purposeDetail": "String", // 通知用途詳情（需指定返回）
"description": "String", // 通知描述信息（需指定返回）
"type": "String", // 通知類型（需指定返回）
"data": "String" // 附加憑證數(shù)據(jù)（需指定返回）
}
// 更多通知...
]
}
}
3. 響應(yīng)參數(shù)說明
| 字段名 | 類型 | 說明 | 返回規(guī)則 |
|---|---|---|---|
pk | String | 通知唯一ID（主鍵） | 必返回（無需額外指定） |
sender | String | 通知創(chuàng)建者ID | 必返回（無需額外指定） |
senderName | String | 通知創(chuàng)建者名稱 | 可選返回（需在查詢中指定） |
senderEmail | String | 通知創(chuàng)建者郵箱 | 可選返回（需在查詢中指定） |
senderPhone | String | 通知創(chuàng)建者手機(jī)號 | 可選返回（需在查詢中指定） |
receiver | String | 通知接收者ID | 必返回（無需額外指定） |
receiverName | String | 通知接收者名稱 | 可選返回（需在查詢中指定） |
receiverEmail | String | 通知接收者郵箱 | 可選返回（需在查詢中指定） |
receiverPhone | String | 通知接收者手機(jī)號 | 可選返回（需在查詢中指定） |
purpose | String | 通知用途標(biāo)識（如設(shè)備UDID等） | 可選返回（需在查詢中指定） |
purposeDetail | String | 通知用途詳情 | 可選返回（需在查詢中指定） |
description | String | 通知描述信息 | 可選返回（需在查詢中指定） |
type | String | 通知類型（目前支持：DeviceSharing） | 可選返回（需在查詢中指定） |
data | String | 附加憑證數(shù)據(jù) | 可選返回（需在查詢中指定） |
（三）接口示例
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. 響應(yīng)示例（成功）
通知列表響應(yīng)（示例）
{
"data": {
"getNotifications": [
{
"sender": "5dc3c96edd188dd0ce4e3976",
"senderName": "jerry_yang",
"senderEmail": "jerry_yang@tutk.com",
"receiver": "5fe190807f5a7abd27220461",
"receiverName": "test_user",
"receiverEmail": "test@example.com",
"type": "DeviceSharing",
"description": "jerry_yang@tutk.com want to share device : KGGJYP with you.",
"pk": "5fe1be9f21d016afe3d80369",
"purpose": "POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP",
"purposeDetail": "Device sharing request",
"data": "thisisacredential"
}
]
}
}
三、錯(cuò)誤碼說明
| 錯(cuò)誤碼 | 錯(cuò)誤描述 | 解決方案 |
|---|---|---|
400 | Bad Request | 檢查GraphQL查詢語法是否正確，參數(shù)格式是否合法（如all參數(shù)是否為布爾值、字段名是否拼寫正確）；必填參數(shù)是否完整傳遞 |
401 | Unauthorized | 檢查token是否有效、未過期，授權(quán)格式是否正確（JWT/Bearer前綴是否完整）；重新獲取有效的授權(quán)令牌 |
429 | Too Many Requests | 接口調(diào)用頻率超出限制（每分鐘最多30次），需等待1分鐘后重試 |
500 | Internal Server Error | 服務(wù)器內(nèi)部錯(cuò)誤，請聯(lián)系技術(shù)支持排查；確認(rèn)接口域名是否正確、服務(wù)是否正常運(yùn)行 |
