一、接口總覽
| 接口名稱 | 功能描述 | 請求方式 | 授權(quán)方式 | 接口版本 |
|---|---|---|---|---|
| 分享設(shè)備（deviceShare） | 將設(shè)備分享給指定郵箱用戶 | GET / POST | JWT / Bearer Token 授權(quán) | v1 |
| 停止分享（deviceUnshare） | 停止對指定用戶的設(shè)備分享 | GET / POST | JWT / Bearer Token 授權(quán) | v1 |
| 清空分享（clearDeviceShare） | 清空指定設(shè)備的所有分享記錄 | GET / POST | JWT / Bearer Token 授權(quán) | v1 |
二、分享設(shè)備接口（deviceShare）
用于將設(shè)備分享給指定郵箱用戶，需傳遞設(shè)備UID、被分享者郵箱及設(shè)備訪問憑證，支持可選權(quán)限配置和自定義描述信息。
（一）請求說明
1. 請求URL
GET: /vsaas/api/v1/be?query=mutation {deviceShare(device:String!,email:String!,credential:String!,permission:Int,description:String) String!}
POST: /vsaas/api/v1/be/
說明：支持GET和POST兩種請求方式，推薦使用POST方式
說明：
device、email、credential為核心必填參數(shù)，其他為可選參數(shù)。2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
device | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備UID（唯一標識） |
email | String | 是 | GraphQL參數(shù) MUTATION | 被分享者的郵箱 |
credential | String | 是 | GraphQL參數(shù) MUTATION | 連線的憑證（密碼信息） |
permission | Int | 否 | GraphQL參數(shù) MUTATION | 權(quán)限配置：bit0為允許event，bit1為允許liveview（如1=僅允許event，2=僅允許liveview，3=兩者都允許） |
description | String | 否 | GraphQL參數(shù) MUTATION | 自定義分享說明信息 |
4. 請求體（POST 方式專用）
{
"query": "mutation {deviceShare(email:\"被分享者郵箱\",device:\"設(shè)備UID\",credential:\"訪問憑證\",permission:3,description:\"自定義描述\")}"
}
說明：device、email、credential為必填參數(shù)，permission未傳遞時使用默認權(quán)限配置，description僅用于備注說明。
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回操作結(jié)果 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如GraphQL語法錯誤、必填參數(shù)為空、郵箱格式非法） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
| 429 | 請求頻繁 | 接口調(diào)用頻率超出限制（每分鐘最多30次），需等待1分鐘后重試 |
| 500 | 服務(wù)器錯誤 | 服務(wù)器內(nèi)部錯誤，請聯(lián)系技術(shù)支持排查 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"deviceShare": "String", // 操作結(jié)果（ok 或具體錯誤信息）
}
}
（三）接口示例
1. 請求示例（curl）
POST方式請求（示例）
curl --location --request POST 'domain/vsaas/api/v1/be/' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "mutation {deviceShare(email:\"kate_hung@tutk.com\",device:\"POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP\",credential:\"thisisacredential\")}"
}'
GET方式請求（示例）
curl --location --request GET 'domain/vsaas/api/v1/be?query=mutation {deviceShare(email:\"kate_hung@tutk.com\",device:\"POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP\",credential:\"thisisacredential\")}' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json'
2. 響應(yīng)示例（成功）
分享設(shè)備響應(yīng)（示例）
{
"data": {
"deviceShare": "ok"
}
}
三、停止分享接口（deviceUnshare）
用于停止對指定用戶的設(shè)備分享，需傳遞設(shè)備UID和被分享者的PK（用戶唯一標識），被分享者PK可通過「設(shè)備管理API」的Get Device接口獲取。
（一）請求說明
1. 請求URL
GET: /vsaas/api/v1/be?query=mutation {deviceUnshare(device:String!,account:String!) String!}
POST: /vsaas/api/v1/be/
說明：支持GET和POST兩種請求方式，推薦使用POST方式
2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
device | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備UID（唯一標識） |
account | String | 是 | GraphQL參數(shù) MUTATION | 被分享者的PK（用戶唯一標識），可通過「設(shè)備管理API」的Get Device接口獲取 |
4. 請求體（POST 方式專用）
{
"query": "mutation {deviceUnshare(device:\"設(shè)備UID\",account:\"被分享者PK\")}"
}
說明：device和account為必填參數(shù)，account參數(shù)不可使用郵箱，需傳遞用戶PK值。
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回操作結(jié)果 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如GraphQL語法錯誤、必填參數(shù)為空、被分享者PK無效） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
| 429 | 請求頻繁 | 接口調(diào)用頻率超出限制（每分鐘最多30次），需等待1分鐘后重試 |
| 500 | 服務(wù)器錯誤 | 服務(wù)器內(nèi)部錯誤，請聯(lián)系技術(shù)支持排查 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"deviceUnshare": "String", // 操作結(jié)果（ok 或具體錯誤信息）
}
}
（三）接口示例
1. 請求示例（curl）
POST方式請求（示例）
curl --location --request POST 'domain/vsaas/api/v1/be/' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "mutation {deviceUnshare(device:\"POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP\",account:\"5fe190807f5a7abd27220461\")}"
}'
GET方式請求（示例）
curl --location --request GET 'domain/vsaas/api/v1/be?query=mutation {deviceUnshare(device:\"POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP\",account:\"5fe190807f5a7abd27220461\")}' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json'
2. 響應(yīng)示例（成功）
停止分享響應(yīng)（示例）
{
"data": {
"deviceUnshare": "ok"
}
}
四、清空分享接口（clearDeviceShare）
用于清空指定設(shè)備的所有分享記錄，移除該設(shè)備的所有被分享用戶權(quán)限，僅需傳遞設(shè)備UID即可。
（一）請求說明
1. 請求URL
GET: /vsaas/api/v1/be?query=mutation {clearDeviceShare(device:String!) String!}
POST: /vsaas/api/v1/be/
說明：支持GET和POST兩種請求方式，推薦使用POST方式
2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
device | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備UID（唯一標識） |
4. 請求體（POST 方式專用）
{
"query": "mutation {clearDeviceShare(device:\"設(shè)備UID\")}"
}
說明：device參數(shù)為必填，該接口操作不可逆，清空后無法恢復設(shè)備的分享記錄，請謹慎使用。
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回操作結(jié)果 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如GraphQL語法錯誤、設(shè)備UID為空） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
| 429 | 請求頻繁 | 接口調(diào)用頻率超出限制（每分鐘最多30次），需等待1分鐘后重試 |
| 500 | 服務(wù)器錯誤 | 服務(wù)器內(nèi)部錯誤，請聯(lián)系技術(shù)支持排查 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"clearDeviceShare": "String", // 操作結(jié)果（ok 或具體錯誤信息）
}
}
（三）接口示例
1. 請求示例（curl）
POST方式請求（示例）
curl --location --request POST 'domain/vsaas/api/v1/be/' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "mutation {clearDeviceShare(device:\"POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP\")}"
}'
GET方式請求（示例）
curl --location --request GET 'domain/vsaas/api/v1/be?query=mutation {clearDeviceShare(device:\"POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP\")}' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json'
2. 響應(yīng)示例（成功）
清空分享響應(yīng)（示例）
{
"data": {
"clearDeviceShare": "ok"
}
}
