1.5.0

文档

基本数据结构

字段名类型说明
typeString见下表
headNumber文档的当前版本号，协同编辑场景下，此版本号会随着每次编辑递增
contentString文档的内容，格式为专用格式
type 类型说明
document/richdoc新文档
document/modoc专业文档
sheet/modoc表格
slide/modoc幻灯片

创建文档

接口

POST <SHIMO_API>/files

鉴权信息

参数说明
scope"write"

参数说明

参数类型必填说明
typeStringY文档类型，类型列表见下方
nameStringN文档标题，默认 无标题
copyBooleanN不为空时代表该文档是拷贝自其他文档，仅影响历史的创建，不是对其他文档进行复制
contentstringN文档的默认内容，需要以石墨格式的形式传递

type 类型：

类型说明
document新文档
documentPro专业文档，别名 modoc。
sheet表格，别名 spreadsheet。
slide幻灯片

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ type: 'document' })
})
  .then(res => res.json())
  .then(body => console.log(body.data))

返回示例

{
  "head": 1,
  "guid": "JyRX1679PL86rbTk",
  "type": "document",
  "content": "shimo content"
}

获取文档

接口

GET <SHIMO_API>/files/<GUID>

鉴权信息

参数说明
scope"read"
info.fileGuid<GUID>
info.filePermissions.readonlytrue

参数说明

参数类型必填说明
contentStringN为 plain 时，将会把 file.content 从石墨专有格式转换为纯文本返回
withConfigBooleanN服务器返回内容时，同时返回用于初始化编辑器的配置，会放置在 config 字段下

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files/JyRX1679PL86rbTk', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  }
})
  .then(res => res.json())
  .then(body => console.log(body.data))

返回示例

{
  "head": 1,
  "guid": "JyRX1679PL86rbTk",
  "type": "document",
  "content": "shimo content"
}

更改文档标题

对于私有部署版本，此接口仅用于生成用户更改标题的历史，并不保存实际的文件标题。

接口

PATCH <SHIMO_API>/files/<GUID>/title

鉴权信息

参数说明
scope"write"
info.fileGuid<GUID>
info.filePermissions.editabletrue

参数说明

参数类型必填说明
nameStringY新的文档标题

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/title', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'new document name' })
})
  .then(res => res.json())
  .then(body => console.log(body.data))

状态码说明

204 操作成功

还原文档

接口

POST <SHIMO_API>/files/<GUID>/revert

鉴权信息

参数说明
scope"write"
info.fileGuid<GUID>
info.filePermissions.editabletrue

参数说明

参数类型必填说明
docHistoryIdNumberY待还原的历史 ID
beforeStringN值为 true / false
startTimestampNumberN该次改动发生的时间

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/revert', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "docHistoryId": 478035
  })
})

状态码说明

204 操作成功

删除文档和相关内容

接口

DELETE <SHIMO_API>/files/<GUID>

删除文档会连同历史等记录一起删除，不可恢复

鉴权信息

参数说明
scope"write"
info.fileGuid<GUID>
info.filePermissions.editabletrue

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files/JyRX1679PL86rbTk', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  }
})

状态码说明

204 操作成功

在线用户列表

接口

GET <SHIMO_API>/files/<GUID>/online

clients 对应同一个用户打开的多个 tab 页

鉴权信息

参数说明
scope"write"
info.fileGuid<GUID>
info.filePermissions.editabletrue

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/online', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  }
})

返回示例

[
  {
    "user":
      {
        "id":13249,
        "avatar":"https://avatars3.githubusercontent.com/u/13383310?s=70&v=4",
        "name":"tom"
      },
      "clients":[
        {
          "clientId":"6b310abfe3ab43d8977342de9f6f870f"
        }
      ]
  },
  {
    "user":
    {
      "id":13250,
      "avatar":"https://avatars0.githubusercontent.com/u/1641516?s=96&v=4",
      "name":"lucy"
    },
    "clients":[
      {
        "clientId":"67d30248feaa4d73871299aad149e2ce"
      }
    ]
  }
]

获取协作者列表

此接口用于表格单元格锁定，目前只用于私有部署版本。
需要在后端部署 API 回调接口。

接口

GET <SHIMO_API>/files/<GUID>/collaborators

鉴权信息

参数说明
scope"read"
info.fileGuid<GUID>
info.filePermissions.readabletrue

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/collaborators', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  }
})

接入说明:

需要在后端配置 FILE_COLLABORATORS_API，在请求此接口时，石墨服务会向 FILE_COLLABORATORS_API 发起 POST 请求，带上 fileGuid 和 clientUserId 参数，FILE_COLLABORATORS_API 需以 application/json 和数组形式返回协作者列表，返回数据格式：

[
  {
    "clientUserId": "shimodev",
    "permissions": {
      "read": true,
      "edit": true,
      "comment": true,
      "lock": true,
      "manage": true
    }
  }
]

石墨后端会以此结果做二次封装。

每个用户的权限需要以 permissions 字段声明。

返回示例

[{
  "id": 1,
  "name": "shimodev",
  "namePinyin": null,
  "email": "shimodev@shimo.im",
  "avatar": "https://assets-cdn.shimo.im/static/unmd5/default-avatar-moke.png",
  "status": 0,
  "createdAt": "2019-03-10T07:35:41.000Z",
  "updatedAt": "2019-07-15T02:11:38.000Z",
  "deletedAt": null,
  "clientUserId": "shimodev",
  "permission": {
    "read": true,
    "edit": true,
    "comment": true,
    "lock": true,
    "manage": true
  }
}]
← 鉴权认证文档历史 →