[账户管理] 查询、修改、删除

极致加深 - VSaaS 账户管理 API 文档

一、接口总览

接口名称	功能描述	请求方式	授权方式	接口版本
查询账户信息（get_account）	查询VSaaS账户的详细信息，支持按需返回指定字段	GET / POST (GraphQL)	JWT / Bearer Token 授权	v1
修改账户信息（update_account）	更新VSaaS账户的基本信息（昵称、姓名、语言等）	GET / POST (GraphQL)	JWT / Bearer Token 授权	v1
删除账户（delete_account）	删除VSaaS账户，解绑关联设备/方案（不可恢复）	DELETE (RESTful)	JWT / Bearer Token 授权	v1

本章节介绍VSaaS平台账户管理核心API接口（GraphQL/RESTful版本），第三方系统可通过这些接口完成账户信息的管理操作，所有接口均需携带有效的VSaaS Token完成身份认证。

二、账户管理API

（一）查询账户信息（get_account）

通过GraphQL查询VSaaS账户的详细信息，支持按需返回指定字段，返回账户的基础信息及扩展属性。

1. 请求说明

1.1 请求URL

GET: https://vsaas.kalay.us/vsaas/api/v1/be?query={get_account [VsaasAccount]} POST: https://vsaas.kalay.us/vsaas/api/v1/be/ 说明：支持GET/POST方式，推荐使用POST方式通过请求体传递复杂查询

1.2 请求头（Header）

参数名	类型	必选	说明
`Authorization`	String	是	授权令牌，格式：`JWT {token}` 或 `Bearer {token}`
`Content-Type`	String	是	固定值：`application/json`

1.3 请求参数

参数名	类型	必选	位置	说明
无	-	-	-	查询参数通过GraphQL语法在query中指定返回字段

1.4 请求体（POST 方式专用）

{ "query": "query {get_account {pk,email,nickname,lang,uid,created}}" }

（二）响应说明

1. 响应状态码

状态码	徽章	说明
200	成功	请求成功，返回账户信息
400	参数错误	GraphQL语法错误、参数格式错误等
401	认证失败	Token无效或过期

2. 响应数据结构

{ "data": { "get_account": { "pk": "String", // 账户主键ID "vendor": "String", // 厂商标识 "lang": "String", // 账户语言设置 "nickname": "String", // 账户昵称 "email": "String", // 账户邮箱 "phone": "String", // 账户手机号 "userId": "String", // 用户ID "name": "String", // 账户姓名 "uid": "String", // 账户唯一标识 "created": "String", // 账户创建时间 "updated": "String", // 账户更新时间 "last_login": "String", // 最后登录时间 "is_active": "Boolean" // 账户是否激活 } } }

3. 响应参数说明

字段名	类型	说明	返回规则
`pk`	String	账户主键ID	可选返回（需在查询中指定）
`vendor`	String	厂商标识	可选返回（需在查询中指定）
`lang`	String	账户语言设置	可选返回（需在查询中指定）
`nickname`	String	账户昵称	可选返回（需在查询中指定）
`email`	String	账户邮箱	可选返回（需在查询中指定）
`phone`	String	账户手机号	可选返回（需在查询中指定）
`userId`	String	用户ID	可选返回（需在查询中指定）
`name`	String	账户姓名	可选返回（需在查询中指定）
`uid`	String	账户唯一标识	可选返回（需在查询中指定）
`created`	String	账户创建时间	可选返回（需在查询中指定）
`updated`	String	账户更新时间	可选返回（需在查询中指定）
`last_login`	String	最后登录时间	可选返回（需在查询中指定）
`is_active`	Boolean	账户是否激活	可选返回（需在查询中指定）

（三）接口示例

1. 请求示例（curl）

POST方式请求（示例）

curl --location --request POST 'https://vsaas.kalay.us/vsaas/api/v1/be/' \ --header 'Authorization: Bearer LKdkjlk8873BNN' \ --header 'Content-Type: application/json' \ --data-raw '{ "query": "query {get_account {pk,email,nickname,lang}}" }'

GET方式请求（示例）

curl --location --request GET 'https://vsaas.kalay.us/vsaas/api/v1/be?query={get_account {pk,email,nickname,lang}}' \ --header 'Authorization: Bearer LKdkjlk8873BNN' \ --header 'Content-Type: application/json'

2. 响应示例（成功）

账户信息响应（示例）

{ "data": { "get_account": { "email": "", "lang": "zh-CN", "nickname": "test_user", "pk": "8f7e6d5c4b3a2e1f0e9d8c7b6a5f4e3d" } } }

（二）修改账户信息（update_account）

通过GraphQL的mutation更新VSaaS账户的基本信息，支持修改昵称、姓名、语言设置等字段，仅需传入需要修改的参数。

1. 请求说明

1.1 请求URL

GET: https://vsaas.kalay.us/vsaas/api/v1/be?query=mutation {update_account(nickname:string,name:string,lang:string)} POST: https://vsaas.kalay.us/vsaas/api/v1/be/

1.2 请求头（Header）

参数名	类型	必选	说明
`Authorization`	String	是	授权令牌，格式：`JWT {token}` 或 `Bearer {token}`
`Content-Type`	String	是	固定值：`application/json`

1.3 请求参数

参数名	类型	必选	位置	说明
`nickname`	String	否	GraphQL参数 MUTATION	新的账户昵称
`name`	String	否	GraphQL参数 MUTATION	新的账户姓名
`lang`	String	否	GraphQL参数 MUTATION	新的语言设置（如zh-CN/en-US）

1.4 请求体（POST 方式专用）

{ "query": "mutation {update_account(nickname:\"jj\",name:\"jyp\")}" }

（二）响应说明

1. 响应状态码

状态码	徽章	说明
200	成功	请求成功，账户信息已更新
400	参数错误	GraphQL语法错误、参数格式错误等
401	认证失败	Token无效或过期

2. 响应数据结构

{ "data": { "update_account": "success" } }

3. 响应参数说明

字段名	类型	说明	返回规则
`data`	Object	响应数据对象，包含更新结果	必返回（无需额外指定）
`update_account`	String	更新结果标识（success/fail）	必返回（无需额外指定）

（三）接口示例

1. 请求示例（curl）

POST方式请求（示例）

GET方式请求（示例）

curl --location --request GET 'https://vsaas.kalay.us/vsaas/api/v1/be?query=mutation {update_account(nickname:\"jj\",name:\"jyp\")}' \ --header 'Authorization: Bearer LKdkjlk8873BNN' \ --header 'Content-Type: application/json'

2. 响应示例（成功）

账户更新响应（示例）

{ "data": { "update_account": "success" } }

（三）删除账户（delete_account）

通过RESTful API删除VSaaS账户，删除后账户关联的设备、方案等信息将被解绑（但不会删除），账户数据不可恢复，操作前需确保账户无未处理的业务关联。

1. 请求说明

1.1 请求URL

DELETE: https://vsaas.kalay.us/vsaas/api/v1/be/account 说明：仅支持DELETE方式，账户标识通过Token上下文关联

1.2 请求头（Header）

参数名	类型	必选	说明
`Authorization`	String	是	授权令牌，格式：`JWT {token}` 或 `Bearer {token}`
`Content-Type`	String	是	固定值：`application/json`

1.3 请求参数

参数名	类型	必选	位置	说明
无	-	-	-	账户标识通过上下文/Token关联

（二）响应说明

1. 响应状态码

状态码	徽章	说明
200	成功	请求成功，账户已删除
400	参数错误	请求参数格式错误
401	认证失败	Token无效或过期
409	冲突	账户关联的设备未解绑，无法删除

2. 响应数据结构

{ "data": { "delete_account": "success", "delete_time": "String" // 删除时间 } }

3. 响应参数说明

字段名	类型	说明	返回规则
`data`	Object	响应数据对象，包含删除结果	必返回（无需额外指定）
`delete_account`	String	删除结果标识（success/fail）	必返回（无需额外指定）
`delete_time`	String	账户删除时间（格式：YYYY-MM-DD HH:MM:SS）	必返回（无需额外指定）

（三）接口示例

1. 请求示例（curl）

DELETE方式请求（示例）

curl --location --request DELETE 'https://vsaas.kalay.us/vsaas/api/v1/be/account' \ --header 'Authorization: Bearer LKdkjlk8873BNN' \ --header 'Content-Type: application/json'

2. 响应示例（成功）

账户删除响应（示例）

{ "data": { "delete_account": "success", "delete_time": "2025-01-01 15:00:00" } }