用户
石墨 SDK 采用的是弱用户系统,留存在石墨中的数据仅用于在协同编辑中区分不同用户,用户组织架构、权限管理均在接入方的系统中实现。
创建用户
接口
POST <SHIMO_API>/users
在申请 Access Token 的时候,石墨会判断传入的 clientUserId 是否已存在于系统中,若不存在,会自动创建一个用户,因此无需调用此接口创建用户。
鉴权信息
参数 | 说明 |
---|---|
scope | "write user:create" |
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
name | String | Y | 用户名 |
String | Y | 用户邮箱 | |
avatar | String | N | 用户头像 |
gender | Number | N | 用户性别 |
clientUserId | String | Y | 用户对应的 clientUserId |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/users', {
method: 'POST',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '墨客',
email: 'example@shimo.im',
clientUserId: 1
})
})
.then(res => res.json())
.then(body => console.log(body.data))
返回示例
{
"id": 1,
"name": "墨客",
"namePinyin": null,
"email": "shimo@shimo.im",
"avatar": null,
"status": 0,
"createdAt": "2018-06-01T07:45:15.000Z",
"updatedAt": "2018-06-01T08:33:59.000Z"
}
获取用户列表
此接口用于根据接入方传入的用户标识反查在石墨中保存的数据,无法列出所有用户。
接口
GET <SHIMO_API>/users
鉴权信息
参数 | 说明 |
---|---|
scope | "read" |
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
ids | Number[] | Y | 用户 ID 数组。clientUserIds 存在时可为空。 |
clientUserIds | String[] | Y | Client user ID 数组。ids 存在时可为空。 |
size | Number | N | 单次获取的数量 |
page | Number | N | 从第几页 |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/users?clientUserIds=1', {
method: 'GET',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
}
})
.then(res => res.json())
.then(body => console.log(body.data))
返回示例
[{
"id": 1,
"name": "shimo",
"email": "shimo@shimo.im",
"avatar": "https://assets-cdn.shimo.im/static/unmd5/default-avatar-moke.png",
"status": 0,
"gender": null,
"createdAt": "2018-06-01T07:45:15.000Z",
"updatedAt": "2018-06-01T08:33:59.000Z",
"clientUserId": "1"
}]
获取用户
接口
GET <SHIMO_API>/users/:id
GET <SHIMO_API>/users/email?email=
GET <SHIMO_API>/users/client_user_id?client_user_id=
鉴权信息
参数 | 说明 |
---|---|
scope | "read" |
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
String | Y | 用户邮箱 | |
client_user_id | String | Y | 客户系统的用户标识 |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/users/email?email=example@shimo.im', {
method: 'DELETE',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
}
})
.then(res => res.json())
.then(body => console.log(body.data))
返回示例
{
"id": 1,
"name": "墨客",
"namePinyin": null,
"email": "shimo@shimo.im",
"avatar": null,
"status": 0,
"createdAt": "2018-06-01T07:45:15.000Z",
"updatedAt": "2018-06-01T08:33:59.000Z"
}
修改用户信息
接口
PATCH <SHIMO_API>/users/me
PATCH <SHIMO_API>/users/:id
使用 me
时等同于当前登录用户的 id
。
鉴权信息
参数 | 说明 |
---|---|
scope | "write" |
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
name | String | N | 用户名 |
String | N | 用户邮箱 | |
avatar | String | N | 用户头像 |
gender | Number | N | 用户性别 |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/users/me', {
method: 'PATCH',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '石墨文档'
})
})
.then(res => res.json())
.then(body => console.log(body.data))
返回示例
{
"id": 1,
"name": "石墨文档",
"namePinyin": null,
"email": "shimo@shimo.im",
"avatar": null,
"status": 0,
"createdAt": "2018-06-01T07:45:15.000Z",
"updatedAt": "2018-06-01T08:33:59.000Z"
}
批量获取用户
接口
POST <SHIMO_API>/users/find
此接口是为了方便用 clientUserId
批量查询用户信息,用于实现表格锁定的功能而设计。为了信息安全,要求的 access token scope
需要满足 read
和 user:list
,user:list
也可用 user
代替,正常编辑使用过程中用的 API 不会要求 user
,因此此接口应该在服务器端访问,给用户生成的 access token 也不应该包含 user scope
。
鉴权信息
参数 | 说明 |
---|---|
scope | "read user:list" |
read user:list
意思为 access token 的 scope
需为以下值之一:
read user:list
read user
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
clientUserIds | String[] | Y | 需要查询的用户 ID 列表 |
size | Number | N | 一次返回的数量,默认 30 |
page | Number | N | 查询的页数,从 1 开始算,默认 1 |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/users/find', {
method: 'POST',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
clientUserIds: ['example@shimo.im', '13112345678'],
page: 1,
size: 100
})
})
.then(res => res.json())
.then(body => console.log(body.data))
返回示例
{
"users": [
{
"id": 1,
"name": "shimo",
"email": null,
"avatar": null,
"status": 0,
"isSeat": 0,
"createdAt": "2018-06-01T07:45:15.000Z",
"updatedAt": "2018-06-01T07:45:15.000Z",
"clientUserId": "example@shimo.im",
}
],
"page": 1,
"size": 100
}
修改用户 (席位) 状态
适用于新版本的私有部署版本 SDK。
石墨 SDK 使用 user.status
字段进行席位管理,当 status
小于 0 时:
- 该用户将不计入席位总数
- 不可为该用户申请 Access Token
- 已为该用户申请的 Access Token 将立即失效 (忽略 Access Token 的过期时间)
接口
POST <SHIMO_API>/users/activate
激活用户席位
POST <SHIMO_API>/users/deactivate
取消用户席位
鉴权信息
参数 | 说明 |
---|---|
scope | "write license" |
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
clientUserIds | String[] | Y | 需要处理的用户 ID 列表 |
- 接口不会校验 clientUserIds 的合法性
- 存在则修改状态
- 不存在则忽略
- 激活用户席位时,如果可用席位小于提交的列表,将修改失败
- 比如可用席位只有 1,如提交 ["a","b"],请求将会失败,a 和 b 将会是未激活状态
代码示例
激活用户席位
const request = require('node-fetch')
fetch('<SHIMO_API>/users/activate', {
method: 'POST',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
clientUserIds: ['example@shimo.im', '13112345678'],
})
})
.then(res => res.json())
.then(body => console.log(body.data))
取消用户席位
const request = require('node-fetch')
fetch('<SHIMO_API>/users/deactivate', {
method: 'POST',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
clientUserIds: ['example@shimo.im', '13112345678'],
})
})
.then(res => res.json())
.then(body => console.log(body.data))
状态码说明
204
操作成功
返回示例
无返回值