快速开始
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。