[方案管理] 綁定、解綁、查詢、轉(zhuǎn)移

TUTK VSaaS 合約接口文檔

一、接口總覽

接口名稱	功能描述	請求方式	授權(quán)方式	接口版本
合約綁定設備（create_binding）	將方案綁定到指定設備	POST (GraphQL)	JWT / Bearer Token 授權(quán)	v1
查詢合約（getContract）	根據(jù)合約ID查詢合約詳情	GET	JWT / Bearer Token 授權(quán)	v1
設備合約解綁（remove_binding）	將方案與設備解綁	POST (GraphQL)	JWT / Bearer Token 授權(quán)	v1
方案列表查詢（get_contract_list）	查詢當前用戶的所有方案列表	POST (GraphQL)	JWT / Bearer Token 授權(quán)	v1
方案轉(zhuǎn)移（transferContract）	將方案從源設備轉(zhuǎn)移到目標設備	GET / POST (GraphQL)	JWT / Bearer Token 授權(quán)	v1

本章節(jié)介紹TUTK VSaaS平臺合約管理核心API接口（GraphQL版本），第三方系統(tǒng)可通過這些接口完成合約綁定、查詢、解綁、方案列表查詢、方案轉(zhuǎn)移等操作，所有接口均需攜帶有效的VSaaS Token完成身份認證。

二、合約綁定設備接口（create_binding）

用于將方案綁定到指定設備，需傳遞方案Contract ID和設備UDID，兩個參數(shù)均為必填項，為空或格式錯誤會返回400參數(shù)錯誤。

（一）請求說明

1. 請求URL

POST: https://vsaas-domain/vsaas/api/v1/be/ 說明：僅支持POST方式，基于GraphQL協(xié)議提交請求

2. 請求頭（Header）

參數(shù)名	類型	必選	說明
`Authorization`	String	是	授權(quán)令牌，格式：`JWT {token}` 或 `Bearer {token}`
`Content-Type`	String	是	固定值：`application/json`

3. 請求參數(shù)

參數(shù)名	類型	必選	位置	說明
`contract`	String	是	GraphQL參數(shù) MUTATION	方案的Contract ID，不能為空或格式錯誤
`device`	String	是	GraphQL參數(shù) MUTATION	設備端的UDID（唯一標識），不能為空或格式錯誤

4. 請求體（POST 方式專用）

{ "query": "mutation {create_binding(contract:\"方案Contract ID\",device:\"設備UDID\")}" }

（二）響應說明

1. 響應狀態(tài)碼

狀態(tài)碼	徽章	說明
200	成功	請求成功，返回綁定結(jié)果
400	參數(shù)錯誤	請求參數(shù)錯誤（如GraphQL語法錯誤、Contract ID/設備UDID為空/格式錯誤）
401	授權(quán)失敗	授權(quán)令牌無效或過期

2. 響應數(shù)據(jù)結(jié)構(gòu)

{ "data": { "create_binding": "方案綁定結(jié)果（Bind contract finish. 或錯誤信息）" } }

（三）接口示例

1. 請求示例（curl）

POST方式請求（示例）

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. 響應示例（成功）

合約綁定響應（示例）

{ "data": { "create_binding": "Bind contract finish." } }

三、查詢合約接口（getContract）

用于根據(jù)合約ID查詢合約詳情，需在URL路徑中傳遞合約ID，該參數(shù)為空或格式錯誤會返回400參數(shù)錯誤。

（一）請求說明

1. 請求URL

GET: http://vsaas-domain/vsaas/api/v1/ss/contract/{id} 說明：僅支持GET方式，合約ID需拼接在URL路徑中

2. 請求頭（Header）

參數(shù)名	類型	必選	說明
`Authorization`	String	是	授權(quán)令牌，格式：`JWT {token}` 或 `Bearer {token}`
`Content-Type`	String	是	固定值：`application/json`

3. 路徑參數(shù)

參數(shù)名	類型	必選	位置	說明
`id`	String	是	URL路徑 PATH	合約ID，不能為空或格式錯誤

（二）響應說明

1. 響應狀態(tài)碼

狀態(tài)碼	徽章	說明
200	成功	請求成功，返回合約詳情
400	參數(shù)錯誤	請求參數(shù)錯誤（如合約ID為空/格式錯誤）
401	授權(quán)失敗	授權(quán)令牌無效或過期

2. 響應數(shù)據(jù)結(jié)構(gòu)

{ "data": { "durationType": "時長類型", "expires": "到期時間", "state": "合約狀態(tài)", "contractId": "合約ID" } }

（三）接口示例

1. 請求示例（curl）

GET方式請求（示例）

curl \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer yJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \ http://vsaas-domain/vsaas/api/v1/ss/contract/93FEE01553D71FE0AA0F

2. 響應示例（成功）

查詢合約響應（示例）

{ "data": { "durationType": "Regular", "expires": "2019-10-02T03:12:19.948Z", "state": "Expired", "contractId": "93FEE01553D71FE0AA0F" } }

四、設備合約解綁接口（remove_binding）

用于將方案與設備解綁，需傳遞設備UDID，該參數(shù)為空或格式錯誤會返回400參數(shù)錯誤。

（一）請求說明

1. 請求URL

POST: https://vsaas-domain/vsaas/api/v1/be/ 說明：僅支持POST方式，基于GraphQL協(xié)議提交請求

2. 請求頭（Header）

參數(shù)名	類型	必選	說明
`Authorization`	String	是	授權(quán)令牌，格式：`JWT {token}` 或 `Bearer {token}`
`Content-Type`	String	是	固定值：`application/json`

3. 請求參數(shù)

參數(shù)名	類型	必選	位置	說明
`device`	String	是	GraphQL參數(shù) MUTATION	設備端的UDID（唯一標識），不能為空或格式錯誤

4. 請求體（POST 方式專用）

{ "query": "mutation {remove_binding(device:\"設備UDID\")}" }

（二）響應說明

1. 響應狀態(tài)碼

狀態(tài)碼	徽章	說明
200	成功	請求成功，返回解綁結(jié)果
400	參數(shù)錯誤	請求參數(shù)錯誤（如GraphQL語法錯誤、設備UDID為空/格式錯誤）
401	授權(quán)失敗	授權(quán)令牌無效或過期

2. 響應數(shù)據(jù)結(jié)構(gòu)

{ "data": { "remove_binding": "方案解綁結(jié)果（remove contract finish. 或錯誤信息）" } }

（三）接口示例

1. 請求示例（curl）

POST方式請求（示例）

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. 響應示例（成功）

合約解綁響應（示例）

{ "data": { "remove_binding": "remove contract finish." } }

五、方案列表查詢接口（get_contract_list）

用于查詢當前用戶的所有方案列表，支持傳遞設備UDID或事件ID作為篩選條件，也可空參數(shù)查詢?nèi)糠桨?，支持GraphQL按需指定返回字段。

（一）請求說明

1. 請求URL

POST: https://vsaas-domain/vsaas/api/v1/be/ 說明：僅支持POST方式，基于GraphQL協(xié)議提交請求

2. 請求頭（Header）

參數(shù)名	類型	必選	說明
`Authorization`	String	是	授權(quán)令牌，格式：`JWT {token}` 或 `Bearer {token}`
`Content-Type`	String	是	固定值：`application/json`

3. 請求參數(shù)

參數(shù)名	類型	必選	位置	說明
`device`	String	否	GraphQL參數(shù) QUERY	設備端的UDID，用于篩選指定設備的方案
`pk`	String	否	GraphQL參數(shù) QUERY	事件的ID，用于篩選指定事件的方案

4. 請求體（POST 方式專用）

{ "query": "query {get_contract_list {pk,account,duration_type,state,created,updated,expires,nickname,description,devices{udid}}}" }

（二）響應說明

1. 響應狀態(tài)碼

狀態(tài)碼	徽章	說明
200	成功	請求成功，返回方案列表數(shù)據(jù)
400	參數(shù)錯誤	請求參數(shù)錯誤（如GraphQL語法錯誤、字段名拼寫錯誤）
401	授權(quán)失敗	授權(quán)令牌無效或過期

2. 響應數(shù)據(jù)結(jié)構(gòu)

{ "data": { "get_contract_list": [方案對象數(shù)組] } }

3. 方案對象字段說明

字段名	類型	說明
`pk`	String	事件ID
`account`	String	賬戶
`duration_type`	String	時長類型
`state`	String	合約狀態(tài)
`created`	String	創(chuàng)建時間
`updated`	String	修改時間
`expires`	String	到期時間
`nickname`	String	方案名稱
`description`	String	方案描述
`devices`	Array	設備列表（包含udid字段）

（三）接口示例

1. 請求示例（curl）

POST方式請求（示例）

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. 響應示例（成功）

查詢方案列表響應（示例）

{ "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）

用于將方案從源設備轉(zhuǎn)移到目標設備，需傳遞源設備UID和目標設備UID，兩個參數(shù)均為必填項，為空或格式錯誤會返回400參數(shù)錯誤。

（一）請求說明

1. 請求URL

GET: /vsaas/api/v1/be?query=mutation+{transferContract(from:String!,to: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ù)名	類型	必選	位置	說明
`from`	String	是	GraphQL參數(shù) MUTATION	源設備UID，不能為空或格式錯誤
`to`	String	是	GraphQL參數(shù) MUTATION	目標設備UID，不能為空或格式錯誤

4. 請求體（POST 方式專用）

{ "query": "mutation {transferContract(from:\"源設備UID\",to:\"目標設備UID\")}" }

（二）響應說明

1. 響應狀態(tài)碼

狀態(tài)碼	徽章	說明
200	成功	請求成功，返回轉(zhuǎn)移結(jié)果
400	參數(shù)錯誤	請求參數(shù)錯誤（如GraphQL語法錯誤、設備UID為空/格式錯誤）
401	授權(quán)失敗	授權(quán)令牌無效或過期

2. 響應數(shù)據(jù)結(jié)構(gòu)

{ "data": { "transferContract": "轉(zhuǎn)移結(jié)果（ok 或錯誤信息）" } }

（三）接口示例

1. 請求示例（curl）

POST方式請求（示例）

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. 響應示例（成功）

方案轉(zhuǎn)移響應（示例）

{ "data": { "transferContract": "ok" } }

[方案管理] 綁定、解綁、查詢、轉(zhuǎn)移

一、接口總覽

二、合約綁定設備接口（create_binding）

三、查詢合約接口（getContract）

四、設備合約解綁接口（remove_binding）

五、方案列表查詢接口（get_contract_list）

六、方案轉(zhuǎn)移接口（transferContract）

[方案管理] 綁定、解綁、查詢、轉(zhuǎn)移

二、合約綁定設備接口（create_binding）

三、查詢合約接口（getContract）

四、設備合約解綁接口（remove_binding）

五、方案列表查詢接口（get_contract_list）

六、方案轉(zhuǎn)移接口（transferContract）