跳到主要内容
版本：SDK-3.10

开发资源

签名​

使用和 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​

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

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

JSSDK 使用 npm 包的形式发布，点击访问以及 webpack。