1.5.0

用户

石墨 SDK 采用的是弱用户系统，留存在石墨中的数据仅用于在协同编辑中区分不同用户，用户组织架构、权限管理均在接入方的系统中实现。

创建用户

接口

POST <SHIMO_API>/users

在申请 Access Token 的时候，石墨会判断传入的 clientUserId 是否已存在于系统中，若不存在，会自动创建一个用户，因此无需调用此接口创建用户。

鉴权信息

参数说明
scope"write user:create"

参数说明

参数类型必填说明
nameStringY用户名
emailStringY用户邮箱
avatarStringN用户头像
genderNumberN用户性别
clientUserIdStringY用户对应的 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"

参数说明

参数类型必填说明
idsNumber[]Y用户 ID 数组。clientUserIds 存在时可为空。
clientUserIdsString[]YClient user ID 数组。ids 存在时可为空。
sizeNumberN单次获取的数量
pageNumberN从第几页

代码示例

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"

参数说明

参数类型必填说明
emailStringY用户邮箱
client_user_idStringY客户系统的用户标识

代码示例

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"

参数说明

参数类型必填说明
nameStringN用户名
emailStringN用户邮箱
avatarStringN用户头像
genderNumberN用户性别

代码示例

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

参数说明

参数类型必填说明
clientUserIdsString[]Y需要查询的用户 ID 列表
sizeNumberN一次返回的数量，默认 30
pageNumberN查询的页数，从 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"

参数说明

参数类型必填说明
clientUserIdsString[]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 操作成功

返回示例

无返回值

← 上一页