一、接口總覽
| 接口名稱(chēng) | 功能描述 | 請(qǐng)求方式 | 授權(quán)方式 | 接口版本 |
|---|---|---|---|---|
| 合約綁定設(shè)備（create_binding） | 將方案綁定到指定設(shè)備 | POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 查詢(xún)合約（getContract） | 根據(jù)合約ID查詢(xún)合約詳情 | GET | JWT / Bearer Token 授權(quán) | v1 |
| 設(shè)備合約解綁（remove_binding） | 將方案與設(shè)備解綁 | POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 方案列表查詢(xún)（get_contract_list） | 查詢(xún)當(dāng)前用戶的所有方案列表 | POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 方案轉(zhuǎn)移（transferContract） | 將方案從源設(shè)備轉(zhuǎn)移到目標(biāo)設(shè)備 | GET / POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
本章節(jié)介紹TUTK VSaaS平臺(tái)合約管理核心API接口（GraphQL版本），第三方系統(tǒng)可通過(guò)這些接口完成合約綁定、查詢(xún)、解綁、方案列表查詢(xún)、方案轉(zhuǎn)移等操作，所有接口均需攜帶有效的VSaaS Token完成身份認(rèn)證。
二、合約綁定設(shè)備接口（create_binding）
用于將方案綁定到指定設(shè)備，需傳遞方案Contract ID和設(shè)備UDID，兩個(gè)參數(shù)均為必填項(xiàng)，為空或格式錯(cuò)誤會(huì)返回400參數(shù)錯(cuò)誤。
（一）請(qǐng)求說(shuō)明
1. 請(qǐng)求URL
POST: https://vsaas-domain/vsaas/api/v1/be/
說(shuō)明：僅支持POST方式，基于GraphQL協(xié)議提交請(qǐng)求
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ō)明 |
|---|---|---|---|---|
contract | String | 是 | GraphQL參數(shù) MUTATION | 方案的Contract ID，不能為空或格式錯(cuò)誤 |
device | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備端的UDID（唯一標(biāo)識(shí)），不能為空或格式錯(cuò)誤 |
4. 請(qǐng)求體（POST 方式專(zhuān)用）
{
"query": "mutation {create_binding(contract:\"方案Contract ID\",device:\"設(shè)備UDID\")}"
}
（二）響應(yīng)說(shuō)明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，返回綁定結(jié)果 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)錯(cuò)誤（如GraphQL語(yǔ)法錯(cuò)誤、Contract ID/設(shè)備UDID為空/格式錯(cuò)誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無(wú)效或過(guò)期 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"create_binding": "方案綁定結(jié)果（Bind contract finish. 或錯(cuò)誤信息）"
}
}
（三）接口示例
1. 請(qǐng)求示例（curl）
POST方式請(qǐng)求（示例）
curl -XPOST -H 'Authorization: Bearer yJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
-H 'Content-Type: application/json' \
-d '{"query": "mutation {create_binding(contract:\"5c3c685d023bde0e7828aa4a\",device:\"QWERTYUIOPPOIUYTREWQ\")}"}' \
https://vsaas-domain/vsaas/api/v1/be/
2. 響應(yīng)示例（成功）
合約綁定響應(yīng)（示例）
{
"data": {
"create_binding": "Bind contract finish."
}
}
三、查詢(xún)合約接口（getContract）
用于根據(jù)合約ID查詢(xún)合約詳情，需在URL路徑中傳遞合約ID，該參數(shù)為空或格式錯(cuò)誤會(huì)返回400參數(shù)錯(cuò)誤。
（一）請(qǐng)求說(shuō)明
1. 請(qǐng)求URL
GET: http://vsaas-domain/vsaas/api/v1/ss/contract/{id}
說(shuō)明：僅支持GET方式，合約ID需拼接在URL路徑中
2. 請(qǐng)求頭（Header）
| 參數(shù)名 | 類(lèi)型 | 必選 | 說(shuō)明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 路徑參數(shù)
| 參數(shù)名 | 類(lèi)型 | 必選 | 位置 | 說(shuō)明 |
|---|---|---|---|---|
id | String | 是 | URL路徑 PATH | 合約ID，不能為空或格式錯(cuò)誤 |
（二）響應(yīng)說(shuō)明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，返回合約詳情 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)錯(cuò)誤（如合約ID為空/格式錯(cuò)誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無(wú)效或過(guò)期 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"durationType": "時(shí)長(zhǎng)類(lèi)型",
"expires": "到期時(shí)間",
"state": "合約狀態(tài)",
"contractId": "合約ID"
}
}
（三）接口示例
1. 請(qǐng)求示例（curl）
GET方式請(qǐng)求（示例）
curl \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer yJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
http://vsaas-domain/vsaas/api/v1/ss/contract/93FEE01553D71FE0AA0F
2. 響應(yīng)示例（成功）
查詢(xún)合約響應(yīng)（示例）
{
"data": {
"durationType": "Regular",
"expires": "2019-10-02T03:12:19.948Z",
"state": "Expired",
"contractId": "93FEE01553D71FE0AA0F"
}
}
四、設(shè)備合約解綁接口（remove_binding）
用于將方案與設(shè)備解綁，需傳遞設(shè)備UDID，該參數(shù)為空或格式錯(cuò)誤會(huì)返回400參數(shù)錯(cuò)誤。
（一）請(qǐng)求說(shuō)明
1. 請(qǐng)求URL
POST: https://vsaas-domain/vsaas/api/v1/be/
說(shuō)明：僅支持POST方式，基于GraphQL協(xié)議提交請(qǐng)求
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ō)明 |
|---|---|---|---|---|
device | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備端的UDID（唯一標(biāo)識(shí)），不能為空或格式錯(cuò)誤 |
4. 請(qǐng)求體（POST 方式專(zhuān)用）
{
"query": "mutation {remove_binding(device:\"設(shè)備UDID\")}"
}
（二）響應(yīng)說(shuō)明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，返回解綁結(jié)果 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)錯(cuò)誤（如GraphQL語(yǔ)法錯(cuò)誤、設(shè)備UDID為空/格式錯(cuò)誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無(wú)效或過(guò)期 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"remove_binding": "方案解綁結(jié)果（remove contract finish. 或錯(cuò)誤信息）"
}
}
（三）接口示例
1. 請(qǐng)求示例（curl）
POST方式請(qǐng)求（示例）
curl -XPOST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
-H 'Content-Type: application/json' \
-d '{"query": "mutation {remove_binding(device:\"POIUYTREWQQWERTYUIOP\")}"}' \
https://vsaas-domain/vsaas/api/v1/be/
2. 響應(yīng)示例（成功）
合約解綁響應(yīng)（示例）
{
"data": {
"remove_binding": "remove contract finish."
}
}
五、方案列表查詢(xún)接口（get_contract_list）
用于查詢(xún)當(dāng)前用戶的所有方案列表，支持傳遞設(shè)備UDID或事件ID作為篩選條件，也可空參數(shù)查詢(xún)?nèi)糠桨?，支持GraphQL按需指定返回字段。
（一）請(qǐng)求說(shuō)明
1. 請(qǐng)求URL
POST: https://vsaas-domain/vsaas/api/v1/be/
說(shuō)明：僅支持POST方式，基于GraphQL協(xié)議提交請(qǐng)求
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ō)明 |
|---|---|---|---|---|
device | String | 否 | GraphQL參數(shù) QUERY | 設(shè)備端的UDID，用于篩選指定設(shè)備的方案 |
pk | String | 否 | GraphQL參數(shù) QUERY | 事件的ID，用于篩選指定事件的方案 |
4. 請(qǐng)求體（POST 方式專(zhuān)用）
{
"query": "query {get_contract_list {pk,account,duration_type,state,created,updated,expires,nickname,description,devices{udid}}}"
}
（二）響應(yīng)說(shuō)明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，返回方案列表數(shù)據(jù) |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)錯(cuò)誤（如GraphQL語(yǔ)法錯(cuò)誤、字段名拼寫(xiě)錯(cuò)誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無(wú)效或過(guò)期 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"get_contract_list": [方案對(duì)象數(shù)組]
}
}
3. 方案對(duì)象字段說(shuō)明
| 字段名 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
pk | String | 事件ID |
account | String | 賬戶 |
duration_type | String | 時(shí)長(zhǎng)類(lèi)型 |
state | String | 合約狀態(tài) |
created | String | 創(chuàng)建時(shí)間 |
updated | String | 修改時(shí)間 |
expires | String | 到期時(shí)間 |
nickname | String | 方案名稱(chēng) |
description | String | 方案描述 |
devices | Array | 設(shè)備列表（包含udid字段） |
（三）接口示例
1. 請(qǐng)求示例（curl）
POST方式請(qǐng)求（示例）
curl -XPOST -H 'Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1ODAyODgzNzksImlhdCI6MTU0ODc1MjM3OSwiaWQiOiI1YjFkZjY1ZGYwYjMyODRkMGRjNTU5YWYiLCJ0YWciOiIxMWUwMjI0MyJ9.JBFyr3XZUa_95uZHMZrx-tXyTCIfBlBQGY2GWvGQloQ' \
-H 'Content-Type: application/json' \
-d '{"query": "query {get_contract_list {pk,account,duration_type,state,created,updated,expires,nickname,description,devices{udid}}}"}' \
https://vsaas-domain/vsaas/api/v1/be/
2. 響應(yīng)示例（成功）
查詢(xún)方案列表響應(yīng)（示例）
{
"data": {
"get_contract_list": [
{
"account": "5b1df65df0b3284d0dc559af",
"devices": [
{
"udid":"QWERTYUIOPPOIUYTREWW"
}
],
"created": "2019-02-21T10:15:13.055Z",
"description": "7 days general event plan",
"expires": "2019-03-02T00:00:00Z",
"nickname": "GeneralEvent7DaysPlan",
"media_type": "FREE_PLAN",
"pk": "5c6e7a311d41c87815d585ed",
"state": "Activated",
"duration_type": "Regular",
"updated": "2019-02-21T10:15:13.055Z"
}
]
}
}
六、方案轉(zhuǎn)移接口（transferContract）
用于將方案從源設(shè)備轉(zhuǎn)移到目標(biāo)設(shè)備，需傳遞源設(shè)備UID和目標(biāo)設(shè)備UID，兩個(gè)參數(shù)均為必填項(xiàng)，為空或格式錯(cuò)誤會(huì)返回400參數(shù)錯(cuò)誤。
（一）請(qǐng)求說(shuō)明
1. 請(qǐng)求URL
GET: /vsaas/api/v1/be?query=mutation+{transferContract(from:String!,to:String!) String!}
POST: /vsaas/api/v1/be/
說(shuō)明：支持GET和POST兩種請(qǐng)求方式，推薦使用POST方式
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ō)明 |
|---|---|---|---|---|
from | String | 是 | GraphQL參數(shù) MUTATION | 源設(shè)備UID，不能為空或格式錯(cuò)誤 |
to | String | 是 | GraphQL參數(shù) MUTATION | 目標(biāo)設(shè)備UID，不能為空或格式錯(cuò)誤 |
4. 請(qǐng)求體（POST 方式專(zhuān)用）
{
"query": "mutation {transferContract(from:\"源設(shè)備UID\",to:\"目標(biāo)設(shè)備UID\")}"
}
（二）響應(yīng)說(shuō)明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，返回轉(zhuǎn)移結(jié)果 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)錯(cuò)誤（如GraphQL語(yǔ)法錯(cuò)誤、設(shè)備UID為空/格式錯(cuò)誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無(wú)效或過(guò)期 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"transferContract": "轉(zhuǎn)移結(jié)果（ok 或錯(cuò)誤信息）"
}
}
（三）接口示例
1. 請(qǐng)求示例（curl）
POST方式請(qǐng)求（示例）
curl --location --request POST 'https://vsaas-domain/vsaas/api/v1/be/' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"query": "mutation {transferContract(from:\"udid1\",to:\"udid2\")}"}'
2. 響應(yīng)示例（成功）
方案轉(zhuǎn)移響應(yīng)（示例）
{
"data": {
"transferContract": "ok"
}
}
