一、接口總覽
| 接口名稱 | 功能描述 | 請(qǐng)求方式 | 授權(quán)方式 | 接口版本 |
|---|---|---|---|---|
| 添加設(shè)備（create_device） | 將設(shè)備添加至VSaaS平臺(tái)，完成設(shè)備注冊(cè)入庫(kù) | POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 查詢?cè)O(shè)備列表（get_device_list） | 查詢當(dāng)前賬戶下的設(shè)備列表，支持按UDID篩選 | GET / POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 修改設(shè)備（update_device） | 更新已注冊(cè)設(shè)備的基本信息（名稱、標(biāo)簽等） | GET / POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 刪除設(shè)備（remove_device） | 從VSaaS平臺(tái)刪除指定UDID的設(shè)備 | GET / POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
本章節(jié)介紹TUTK VSaaS平臺(tái)設(shè)備管理核心API接口（GraphQL版本），第三方系統(tǒng)可通過(guò)這些接口完成設(shè)備添加、查詢、修改、刪除等操作，所有接口均需攜帶有效的VSaaS Token完成身份認(rèn)證。
二、添加設(shè)備接口（create_device）
將設(shè)備添加至VSaaS平臺(tái)，完成設(shè)備的注冊(cè)入庫(kù)。需傳遞設(shè)備UDID、名稱、顏色標(biāo)簽等必填參數(shù)，參數(shù)為空或格式錯(cuò)誤會(huì)返回400參數(shù)錯(cuò)誤。
（一）請(qǐng)求說(shuō)明
1. 請(qǐng)求URL
POST: https://vsaas-domain/vsaas/api/v1/be/
2. GraphQL Schema 定義
mutation {
create_device(parameters)
}
3. 請(qǐng)求頭（Header）
| 參數(shù)名 | 類(lèi)型 | 必選 | 說(shuō)明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
4. 請(qǐng)求參數(shù)
| 參數(shù)名 | 類(lèi)型 | 必選 | 位置 | 說(shuō)明 |
|---|---|---|---|---|
udid | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備的UDID |
nickname | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備名稱 |
color_tag | String | 是 | GraphQL參數(shù) MUTATION | 顏色標(biāo)簽，用以UI呈現(xiàn)（如#ffffff） |
thumbnail | String | 是 | GraphQL參數(shù) MUTATION | 縮略圖路徑，無(wú)則傳空字符串 |
channel | Int | 是 | GraphQL參數(shù) MUTATION | 設(shè)備通道數(shù) |
credential | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備的秘鑰，不同SDK版本創(chuàng)建方式不同： SDK 4.x：由設(shè)備端調(diào)用SDK API創(chuàng)建 SDK 3.x：由authkey(ak)、identity、av password(av)和authType組成，經(jīng)base64編碼得到。格式：base64({"av":"%s","ak":"%s","identity":"%s","authType":"authToken"})，authType支持authPass或authToken，設(shè)備端未使用authkey時(shí)ak字段可空 |
uid | String | 否 | GraphQL參數(shù) MUTATION | 設(shè)備UID，舊版本為20位 |
fw_ver | String | 否 | GraphQL參數(shù) MUTATION | 設(shè)備固件版本 |
5. 請(qǐng)求示例（curl）
POST方式請(qǐng)求（示例）
curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' \
-H 'Content-Type: application/json' \
-d 'mutation {create_device(uid:"KJKWJK",udid:"KJKWJK",nickname:"LivingRoom",color_tag:"#ffffff",thumbnail:"a.jpg",channel:"0",credential:"adsfwefasdfa", fw_ver:"v0.0.0.1")}' \
https://vsaas.kalay.us/vsaas/api/v1/be/
（二）響應(yīng)說(shuō)明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，設(shè)備添加完成 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)錯(cuò)誤（如UDID無(wú)效、必填參數(shù)缺失、credential格式錯(cuò)誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無(wú)效或過(guò)期 |
2. 響應(yīng)參數(shù)說(shuō)明
| 參數(shù)名 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
create_device（stoken） | String | APP端獲取到此stoken后，需通過(guò)P2P SDK發(fā)送給設(shè)備端保存，用以設(shè)備端推流使用 |
3. 響應(yīng)示例（成功）
添加設(shè)備響應(yīng)（示例）
{
"data": {
"create_device": "aasdfawjlekjlkjxlkjcoijijkl"
}
}
三、查詢?cè)O(shè)備接口（get_device_list）
查詢當(dāng)前賬戶下的設(shè)備列表，支持按設(shè)備UDID篩選指定設(shè)備信息，空參數(shù)則查詢?nèi)吭O(shè)備，支持GraphQL按需指定返回字段。
（一）請(qǐng)求說(shuō)明
1. 請(qǐng)求URL
GET: /vsaas/api/v1/be?query=query {get_device_list(udid:String) [Device]}
POST: https://vsaas-domain/vsaas/api/v1/be/
2. 請(qǐng)求頭（Header）
| 參數(shù)名 | 類(lèi)型 | 必選 | 說(shuō)明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請(qǐng)求參數(shù)
| 參數(shù)名 | 類(lèi)型 | 必選 | 位置 | 說(shuō)明 |
|---|---|---|---|---|
udid | String | 否 | GraphQL參數(shù) QUERY | 指定設(shè)備UDID，不傳則查詢所有設(shè)備 |
4. 請(qǐng)求示例（curl）
POST方式請(qǐng)求（示例）
curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' \
-H 'Content-Type: application/json' \
-d 'query {get_device_list{udid,color_tag,channel,vendor,nickname,created,updated,channel,st,credential,fw_ver,contracts{pk},contractInUse{pk},shareTo{account}}}' \
https://vsaas.kalay.us/vsaas/api/v1/be/
（二）響應(yīng)說(shuō)明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，返回設(shè)備列表 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)錯(cuò)誤（如GraphQL語(yǔ)法錯(cuò)誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無(wú)效或過(guò)期 |
2. 響應(yīng)參數(shù)說(shuō)明
| 參數(shù)名 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
created | String | 設(shè)備創(chuàng)建時(shí)間 |
updated | String | 設(shè)備信息更新時(shí)間 |
udid | String | 設(shè)備UDID |
account | String | 關(guān)聯(lián)賬戶標(biāo)識(shí) |
vendor | String | 廠商ID |
nickname | String | 設(shè)備名稱 |
color_tag | String | 顏色標(biāo)簽 |
thumbnail | String | 縮略圖路徑 |
channel | Int | 通道數(shù) |
st | String | 設(shè)備stoken |
credential | String | 設(shè)備秘鑰（base64編碼） |
fw_ver | String | 固件版本 |
contracts | Contract Object | 關(guān)聯(lián)的方案，包含pk字段（方案唯一標(biāo)識(shí)） |
contractInUse | Contract Object | 當(dāng)前使用的方案，包含pk字段 |
shareTo | Array[DeviceSharingInfo] | 設(shè)備共享信息列表 |
| DeviceSharingInfo 子參數(shù) | ||
account | String | 共享賬戶標(biāo)識(shí) |
email | String | 共享賬戶郵箱 |
phone | String | 共享賬戶手機(jī)號(hào) |
name | String | 共享賬戶姓名 |
credential | String | 共享憑證 |
permission | Int | 共享權(quán)限等級(jí) |
state | Int | 共享狀態(tài) |
startTime | String | 共享開(kāi)始時(shí)間 |
3. 響應(yīng)示例（成功）
查詢?cè)O(shè)備列表響應(yīng)（示例）
{
"data": {
"get_device_list": [
{
"udid": "588feadd",
"nickname": "LivingRoom",
"color_tag": "#ffffff",
"channel": 0,
"vendor": "TUTK",
"created": "2024-01-01T00:00:00Z",
"updated": "2024-01-01T00:00:00Z",
"st": "aasdfawjlekjlkjxlkjcoijijkl",
"credential": "adsfwefasdfa",
"fw_ver": "v0.0.0.1",
"contracts": [{"pk": "5c6e7a311d41c87815d585ed"}],
"contractInUse": {"pk": "5c6e7a311d41c87815d585ed"},
"shareTo": [{"account": "user123", "email": "user@example.com", "phone": "13800138000", "name": "Test User", "credential": "share_cred", "permission": 1, "state": 1, "startTime": "2024-01-01T00:00:00Z"}]
},
{
"udid": "699febee",
"nickname": "BedRoom",
"color_tag": "#ff0000",
"channel": 0,
"vendor": "TUTK",
"created": "2024-01-02T00:00:00Z",
"updated": "2024-01-02T00:00:00Z",
"st": "bsdfawjlekjlkjxlkjcoijijkl",
"credential": "bsdfwefasdfa",
"fw_ver": "v0.0.0.1",
"contracts": [],
"contractInUse": null,
"shareTo": []
}
]
}
}
四、修改設(shè)備接口（update_device）
更新已注冊(cè)設(shè)備的基本信息（名稱、顏色標(biāo)簽、縮略圖、秘鑰等），需傳遞設(shè)備UDID作為唯一標(biāo)識(shí)，其余參數(shù)為可選修改項(xiàng)。
（一）請(qǐng)求說(shuō)明
1. 請(qǐng)求URL
GET: /vsaas/api/v1/be?query=mutation {update_device(udid:String!,nickname:String,color_tag:String,uid:String,channel:Int,pw:String,credential:String,fw_ver:String)}
POST: https://vsaas-domain/vsaas/api/v1/be/
2. 請(qǐng)求頭（Header）
| 參數(shù)名 | 類(lèi)型 | 必選 | 說(shuō)明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請(qǐng)求參數(shù)
| 參數(shù)名 | 類(lèi)型 | 必選 | 位置 | 說(shuō)明 |
|---|---|---|---|---|
udid | String | 是 | GraphQL參數(shù) MUTATION | 指定要修改的設(shè)備UDID |
nickname | String | 否 | GraphQL參數(shù) MUTATION | 設(shè)備名稱（可選修改） |
color_tag | String | 否 | GraphQL參數(shù) MUTATION | 顏色標(biāo)簽（可選修改） |
thumbnail | String | 否 | GraphQL參數(shù) MUTATION | 縮略圖路徑（可選修改） |
channel | Int | 否 | GraphQL參數(shù) MUTATION | 設(shè)備通道數(shù)（可選修改） |
credential | String | 否 | GraphQL參數(shù) MUTATION | 設(shè)備的秘鑰（可選修改），創(chuàng)建規(guī)則同添加設(shè)備接口 |
uid | String | 否 | GraphQL參數(shù) MUTATION | 設(shè)備UID（可選修改，舊版本為20位） |
fw_ver | String | 否 | GraphQL參數(shù) MUTATION | 設(shè)備固件版本（可選修改） |
pw | String | 否 | GraphQL參數(shù) MUTATION | 設(shè)備密碼（可選修改） |
4. 請(qǐng)求示例（curl）
POST方式請(qǐng)求（示例）
curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' \
-H 'Content-Type: application/json' \
-d 'mutation {update_device(udid:"KJKWJK",nickname:"ResetRoom",color_tag:"#ff00ff")}' \
https://vsaas.kalay.us/vsaas/api/v1/be/
（二）響應(yīng)說(shuō)明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，設(shè)備信息修改完成 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)錯(cuò)誤（如UDID不存在、參數(shù)格式錯(cuò)誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無(wú)效或過(guò)期 |
2. 響應(yīng)參數(shù)說(shuō)明
| 參數(shù)名 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
data | JSON Object | 響應(yīng)主體，包含修改結(jié)果提示 |
update_device | String | 修改結(jié)果提示（如"success"表示成功） |
3. 響應(yīng)示例（成功）
修改設(shè)備響應(yīng)（示例）
{
"data": {
"update_device": "success"
}
}
五、刪除設(shè)備接口（remove_device）
從VSaaS平臺(tái)刪除指定UDID的設(shè)備，解除設(shè)備與賬戶的關(guān)聯(lián)，需傳遞設(shè)備UDID作為唯一標(biāo)識(shí)，該參數(shù)為空或不存在會(huì)返回400參數(shù)錯(cuò)誤。
（一）請(qǐng)求說(shuō)明
1. 請(qǐng)求URL
GET: /vsaas/api/v1/be?query=mutation {remove_device(udid:String!)}
POST: https://vsaas-domain/vsaas/api/v1/be/
2. 請(qǐng)求頭（Header）
| 參數(shù)名 | 類(lèi)型 | 必選 | 說(shuō)明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請(qǐng)求參數(shù)
| 參數(shù)名 | 類(lèi)型 | 必選 | 位置 | 說(shuō)明 |
|---|---|---|---|---|
udid | String | 是 | GraphQL參數(shù) MUTATION | 指定要?jiǎng)h除的設(shè)備UDID |
4. 請(qǐng)求示例（curl）
POST方式請(qǐng)求（示例）
curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' \
-H 'Content-Type: application/json' \
-d 'mutation {remove_device(udid:"KJKWJK")}' \
https://vsaas.kalay.us/vsaas/api/v1/be/
（二）響應(yīng)說(shuō)明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，設(shè)備刪除完成 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)錯(cuò)誤（如UDID不存在、UDID格式無(wú)效） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無(wú)效或過(guò)期 |
2. 響應(yīng)參數(shù)說(shuō)明
| 參數(shù)名 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
data | JSON Object | 響應(yīng)主體，包含刪除結(jié)果提示 |
remove_device | String | 刪除結(jié)果提示（如"success"表示成功） |
3. 響應(yīng)示例（成功）
刪除設(shè)備響應(yīng)（示例）
{
"data": {
"remove_device": "success"
}
}
