跳到主要内容
版本:SDK-3.12

开发资源

签名

使用和 appId 和 secret 签名,用于石墨服务器(私有部署则为接入方提供的部署服务器)验证请求合法性。

签名后的结果(即 signature 的值)为 JSON Web Token(简称为 JWT)格式字符串,其结构包括 Header、Payload、Signature 三个部分。

JWT 通常形式为 xxxxx.yyyyy.zzzzz

  • Header 部分
    • 默认包含的字段:alg 、typ
      • alg 表示签名算法,通常默认为 HS256
      • typ 标识 Token 类型,JSON Web Token 的类型默认为 JWT
    • 添加 kid 字段,值为 AppId 的值
  • Payload
    • 仅添加 exp 字段即可,值为 JWT 的过期时间秒数 ,例如 1612411882 (如当前时间的秒数值比 exp 字段的值要小,说明还没有到达过期时间,此签名不会被判断为失效)
    • 当请求 /admin 相关 API 时,会额外增加 fileId 信息

签名前的数据结构:

Header

{
"alg": "HS256", // 默认字段
"typ": "JWT", // 默认字段
"kid": "your AppId"
}

Payload

{
"exp": 1612411882
}

Payload 参数

字段名类型值示例必选说明
expnumber1612411882签名的过期时间称
scopestringlicense用于访问某些限定 scope 的 API,具体见对应的 API 说明

Java 示例

使用 https://github.com/auth0/java-jwt 为例

<dependency>
<groupId>com.auth0</groupId>
<artifactId>java-jwt</artifactId>
<version>4.4.0</version>
</dependency>
// JDK8或以上
String signature = JWT.create()
// .withClaim("scope", "license") // 如果调用需要scope参数的接口,需要添加此行
.withKeyId("your shimo sdk AppId")
.withExpiresAt(new Date().toInstant().plus(4, ChronoUnit.MINUTES))
.sign(Algorithm.HMAC256("your shimo sdk AppSecret"));

回调凭证类型

由于请求回调存在不同的触发场景,因此存在不同的凭证类型,通过回调请求的 HTTP Header 指定 X-Shimo-Credential-Type。已知的凭证类型:

  • X-Shimo-Credential-Type == 0,此类型通常是由用户的操作行为触发,比如打开页面、编辑文件等,请求会通过 HTTP Header X-Shimo-Token 携带用户在浏览器操作时接入方颁发的 token
  • X-Shimo-Credential-Type == 3, 此类型通常由石墨 SDK 主动触发,如跨表格引用的更新等,请求会通过 HTTP Header X-Shimo-Signature 根据接入方当前的 appId secret 主动签名后供接入方回调进行校验,确认此请求是否来自石墨 SDK

JS SDK

JS SDK 的作用是生成一个指向石墨服务器(私有部署则为接入方提供的部署服务器)的编辑器地址,然后以 iframe 的形式加载到当前页面中。同时封装了 iframe 页面通信方法。使用 JSSDK 可以实现以下动作/事件:

  • 打开侧边栏(历史、版本、全局讨论等功能的展示和隐藏)
  • 获取当前协作者列表
  • 订阅文档保存成功/失败事件
  • 更多动作和事件还在持续更新中

JS SDK 以 npm 包的形式发布:

JS SDK 版本兼容的版本文档链接
>= 1.02022.12.1 (SDK 3.10) 或更早的版本文档链接
< 1.02022.10.1 (SDK 3.9) 或更早的版本文档链接