文档 · 石墨文档协同编辑 SDK

基本数据结构

字段名	类型	说明
type	String	见下表
head	Number	文档的当前版本号，协同编辑场景下，此版本号会随着每次编辑递增
content	String	文档的内容，格式为专用格式，若客户自行保管文档数据，请通过石墨提供的方式生成合法内容，直接修改可能会造成文档内容加载失败

type 类型	说明
document/richdoc	新文档
document/modoc	专业文档
sheet/modoc	表格
slide/modoc	幻灯片

创建文档

接口

POST <SHIMO_API>/files

鉴权信息

参数	说明
scope	"write"

参数说明

参数	类型	必填	说明
type	String	Y	文档类型，类型列表见下方
name	String	N	文档标题，默认 `无标题`
copy	Boolean	N	不为空时代表该文档是拷贝自其他文档

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.readonly	true

参数说明

参数	类型	必填	说明
content	String	N	为 `plain` 时，将会把 `file.content` 从石墨专有格式转换为纯文本返回

代码示例

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.editable	true

参数说明

参数	类型	必填	说明
name	String	Y	新的文档标题

代码示例

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>/compose

鉴权信息

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

参数说明

参数	类型	必填	说明
clientId	String	Y	当前客户端的唯一 ID
rev	Number	Y	该次改动的版本号
changeset	String	Y	对文档的改动
apool	String	N
uuid	String	N	该次改动的唯一 ID，用于同步文档改动信息
startTimestamp	Number	N	该次改动发生的时间
responseChannel	String	N	该次改动发布的目标频道，如无必要请留空

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files/JyRX1679PL86rbTk', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "clientId": "03caa56f-c900-4e79-b80f-fd050d68be3e",
    "rev": 11,
    "changeset": "[[20,\"H\",\"26:\\\"10676\\\"\"]]",
    "uuid": "888e62a71284483db9c306ae8383b3aa"
  })
})

状态码说明

204 操作成功

更新文档内容

一般由石墨内部服务调用。

接口

PATCH <SHIMO_API>/files/<GUID>

该接口用于以新内容替换文档现有内容

鉴权信息

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

参数说明

参数	类型	必填	说明
content	String	N	新的内容，内容需为石墨专有格式

代码示例

const request = require('node-fetch')

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

状态码说明

204 操作成功

还原文档

接口

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

鉴权信息

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

参数说明

参数	类型	必填	说明
docHistoryId	Number	Y	待还原的历史 ID
before	String	N	值为 `true` / `false`
startTimestamp	Number	N	该次改动发生的时间

代码示例

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 操作成功

获取文档最新历史流

一般由石墨内部服务调用。

接口

GET <SHIMO_API>/files/<GUID>/pull

该接口采用长轮询方式持续返回最新的文档历史

鉴权信息

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

参数说明

参数	类型	必填	说明
clientId	String	Y	当前客户端的唯一 ID
rev	Number	Y	该接口以此版本号为基础查询新的历史
timeout	Number	N	请求中止的时间，单位为毫秒，默认是 12000

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/pull?clientId=03caa56f-c900-4e79-b80f-fd050d68be3e&rev=11', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  }
})

返回示例

该接口返回的类型是 text/event-stream

event: changes
data: []

event: ping
data: "pong"

删除文档和相关内容

接口

DELETE <SHIMO_API>/files/<GUID>

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

鉴权信息

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

代码示例

const request = require('node-fetch')

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

状态码说明

204 操作成功

广播

一般由石墨内部服务调用。

接口

POST <SHIMO_API>/files/<GUID>/broadcast

只会向在文档中的用户发送信息，信息保留时间半小时；需要结合前端的协同编辑模块使用。

鉴权信息

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

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/broadcast', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <Access Token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'this is a broadcast text'
  })
})

状态码说明

204 操作成功

在线用户列表

接口

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

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

鉴权信息

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

代码示例

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.readable	true

代码示例

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
  }
}]