1.5.0

快速开始

Shimo-JavaScript-SDK（下文简称为 JS-SDK）用于在浏览器环境查看及编辑石墨文档数据，JS-SDK 需结合石墨文档官方 API 使用。

事前准备

在开始之前，请确保您已完成以下准备：

  • 在使用 JS-SDK 之前，您须向石墨文档申请 ClientId 和 ClientSecret，以作为鉴权依据，详情请参阅 API 文档
  • 满足 JS-SDK 运行所需的浏览器环境
    • Chrome、IE 11、Firefox、Microsoft Edge、Safari 等现代浏览器
  • 本页面中所有代码均基于 JavaScript，服务器端部分需要 node.js 环境，您可根据需要选用其他语言环境
  • 若您在使用石墨文档测试服务，则额外需要可连接至石墨文档的网络

约定事项：

  • <SHIMO_API> 指石墨 SDK API 的入口，和 API 文档 保持一致
    • 测试环境为：https://platform.shimodev.com/entry
    • 正式环境为：https://platform.shimo.im/entry
  • <CLIENT_ID> 和 <CLIENT_SECRET> 为分配给您的认证用凭证
  • <CLIENT_USER_ID> 为您内部系统标识用户的唯一 ID，一般为数字 ID、电子邮箱或手机号码
  • <ACCESS_TOKEN> 为您通过 <CLIENT_ID> 和 <CLIENT_SECRET> 申请的 Access Token
  • <GUID> 为石墨为创建的文档分配的唯一 ID，您需要独立保存该 GUID
  • 如无特殊说明，所有请求均基于 Content-Type: application/json，请根据所使用的 HTTP 请求库添加对应的 header

接入石墨 SDK

申请 Access Token

Access Token 是与 API 通信的凭证，并且和文档一一对应，因此访问不同文档时需要申请不同 Access Token。

为了保障信息安全，请通过您的服务器程序申请 Access Token。

const fetch = require('node-fetch')

const token = await fetch(`<SHIMO_API>/oauth2/token`, {
  method: 'post',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientId: '<CLIENT_ID>',
    clientSecret: '<CLIENT_SECRET>',
    clientUserId: '<CLIENT_USER_ID>',
    grantType: 'client_credentials',
    scope: 'write',
    info: '' // 额外的权限信息，用于访问文档时使用，详见 API 文档
  })
}).then(res => res.json())

返回示例：

{
  "scope": "write",
  "tokenType": "bearer",
  "accessToken": "<ACCESS_TOKEN>",
  "refreshToken": "<REFRESH_TOKEN>",
  "expireTime": "2018-06-12T09:50:23.000Z"
}

创建文档

const fetch = require('node-fetch')

const file = await fetch(`<SHIMO_API>/files`, {
  body: JSON.stringify({
    type: 'document',
    name: 'my title'
  }),
  headers: {
    Authorization: `Bearer <ACCESS_TOKEN>`,
    'Content-Type': 'application/json'
  }
}).then(res => res.json())

返回示例：

{
  "head": 1,
  "guid": "<GUID>",
  "type": "document",
  "content": ""
}

如何接入

云 SDK

石墨云 SDK 提供 iframe 的接入方式，方便在任何 HTML 页面嵌入石墨文档。

<!DOCTYPE html>
<html>
  <body>
    <iframe src="<SHIMO_API>/view/<GUID>?accessToken=<ACCESS_TOKEN>"></iframe>
  </body>
</html>

私有部署

JS SDK 接入方式请参考官方 GitHub 项目：shimohq/sdk-cabinet。