一、接口总览
| 接口名称 | 功能描述 | 请求方式 | 授权方式 | 接口版本 |
|---|---|---|---|---|
| 分享设备（deviceShare） | 将设备分享给指定邮箱用户 | GET / POST | JWT / Bearer Token 授权 | v1 |
| 停止分享（deviceUnshare） | 停止对指定用户的设备分享 | GET / POST | JWT / Bearer Token 授权 | v1 |
| 清空分享（clearDeviceShare） | 清空指定设备的所有分享记录 | GET / POST | JWT / Bearer Token 授权 | v1 |
二、分享设备接口（deviceShare）
用于将设备分享给指定邮箱用户，需传递设备UID、被分享者邮箱及设备访问凭证，支持可选权限配置和自定义描述信息。
（一）请求说明
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为核心必填参数，其他为可选参数。2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
device | String | 是 | GraphQL参数 MUTATION | 设备UID（唯一标识） |
email | String | 是 | GraphQL参数 MUTATION | 被分享者的邮箱 |
credential | String | 是 | GraphQL参数 MUTATION | 连线的凭证（密码信息） |
permission | Int | 否 | GraphQL参数 MUTATION | 权限配置：bit0为允许event，bit1为允许liveview（如1=仅允许event，2=仅允许liveview，3=两者都允许） |
description | String | 否 | GraphQL参数 MUTATION | 自定义分享说明信息 |
4. 请求体（POST 方式专用）
{
"query": "mutation {deviceShare(email:\"被分享者邮箱\",device:\"设备UID\",credential:\"访问凭证\",permission:3,description:\"自定义描述\")}"
}
说明：device、email、credential为必填参数，permission未传递时使用默认权限配置，description仅用于备注说明。
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回操作结果 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、必填参数为空、邮箱格式非法） |
| 401 | 授权失败 | 授权令牌无效或过期 |
| 429 | 请求频繁 | 接口调用频率超出限制（每分钟最多30次），需等待1分钟后重试 |
| 500 | 服务器错误 | 服务器内部错误，请联系技术支持排查 |
2. 响应数据结构
{
"data": {
"deviceShare": "String", // 操作结果（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:\"[email protected]\",device:\"POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP\",credential:\"thisisacredential\")}"
}'
GET方式请求（示例）
curl --location --request GET 'domain/vsaas/api/v1/be?query=mutation {deviceShare(email:\"[email protected]\",device:\"POIUYTREWQQWERTYUIOPPOIUYTREWQQWERTYUIOP\",credential:\"thisisacredential\")}' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json'
2. 响应示例（成功）
分享设备响应（示例）
{
"data": {
"deviceShare": "ok"
}
}
三、停止分享接口（deviceUnshare）
用于停止对指定用户的设备分享，需传递设备UID和被分享者的PK（用户唯一标识），被分享者PK可通过「设备管理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）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
device | String | 是 | GraphQL参数 MUTATION | 设备UID（唯一标识） |
account | String | 是 | GraphQL参数 MUTATION | 被分享者的PK（用户唯一标识），可通过「设备管理API」的Get Device接口获取 |
4. 请求体（POST 方式专用）
{
"query": "mutation {deviceUnshare(device:\"设备UID\",account:\"被分享者PK\")}"
}
说明：device和account为必填参数，account参数不可使用邮箱，需传递用户PK值。
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回操作结果 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、必填参数为空、被分享者PK无效） |
| 401 | 授权失败 | 授权令牌无效或过期 |
| 429 | 请求频繁 | 接口调用频率超出限制（每分钟最多30次），需等待1分钟后重试 |
| 500 | 服务器错误 | 服务器内部错误，请联系技术支持排查 |
2. 响应数据结构
{
"data": {
"deviceUnshare": "String", // 操作结果（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. 响应示例（成功）
停止分享响应（示例）
{
"data": {
"deviceUnshare": "ok"
}
}
四、清空分享接口（clearDeviceShare）
用于清空指定设备的所有分享记录，移除该设备的所有被分享用户权限，仅需传递设备UID即可。
（一）请求说明
1. 请求URL
GET: /vsaas/api/v1/be?query=mutation {clearDeviceShare(device:String!) String!}
POST: /vsaas/api/v1/be/
说明：支持GET和POST两种请求方式，推荐使用POST方式
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
device | String | 是 | GraphQL参数 MUTATION | 设备UID（唯一标识） |
4. 请求体（POST 方式专用）
{
"query": "mutation {clearDeviceShare(device:\"设备UID\")}"
}
说明：device参数为必填，该接口操作不可逆，清空后无法恢复设备的分享记录，请谨慎使用。
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回操作结果 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、设备UID为空） |
| 401 | 授权失败 | 授权令牌无效或过期 |
| 429 | 请求频繁 | 接口调用频率超出限制（每分钟最多30次），需等待1分钟后重试 |
| 500 | 服务器错误 | 服务器内部错误，请联系技术支持排查 |
2. 响应数据结构
{
"data": {
"clearDeviceShare": "String", // 操作结果（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. 响应示例（成功）
清空分享响应（示例）
{
"data": {
"clearDeviceShare": "ok"
}
}
