Skip to main content
Version: SDK-3.12

系统接口

鉴权方式

Query string 鉴权方式

参数名类型值示例必选说明
tokenstringeyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9接入服务商提供的 token,在石墨请求接入服务商的接口时,会放到 HTTP Headers X-Shimo-Token 中作为值进行传递
signaturestring参考签名方法一节接入服务商,使用从石墨获取的 AppId 、AppSecret 根据签名方法生成的字符串,详见签名一节
appIdstringebc1cde3-9b57-4962-883d-54302d428600已废弃,可传可不传。接入服务商从石墨获取的 AppId

请求示例

curl --request GET 'https://shimo-domain/sdk/v2/api/fake-api?signature=your_signature&token=your_token'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://shimo-domain/sdk/v2/api/fake-api?signature=your_signature&token=your_token")
.build();
Response response = client.newCall(request).execute();
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {
url := "https://shimo-domain/sdk/v2/api/fake-api?signature=your_signature&token=your_token"
method := "GET"

client := &http.Client {
}
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}

res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
var axios = require("axios");

var config = {
method: "GET",
url: "https://shimo-domain/sdk/v2/api/fake-api?signature=your_signature&token=your_token",
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

账号与应用管理

获取 app 详情

获取 app 详细信息,包括 app 名称、可使用文件类型、已激活用户数、用户总数、席位数、license 有效时间、回调地址信息。

提醒

由于 app API 的特殊性,为了安全考虑,需要您在生成签名时附加上 "scope": "license" 字段

请求地址

GET https://shimo-domain/sdk/v2/api/license/apps/{appId}

请求示例

curl "https://shimo-domain/sdk/v2/api/license/apps/yourShimoAppId" \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://shimo-domain/sdk/v2/api/license/apps/yourShimoAppId")
.addHeader("X-Shimo-Signature", "your_signature")
.addHeader("X-Shimo-Token", "your_token")
.build();
Response response = client.newCall(request).execute();
package main

import (
"fmt"
"io/ioutil"
"net/http"
)

func main() {
url := "https://shimo-domain/sdk/v2/api/license/apps/yourShimoAppId"
method := "GET"

client := &http.Client {
}
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}

req.Header.Set("X-Shimo-Signature", "your_signature")
req.Header.Set("X-Shimo-Token", "your_token")

res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
var axios = require("axios");

axios({
method: "GET",
url: "https://shimo-domain/sdk/v2/api/license/apps/yourShimoAppId",
headers: {
"X-Shimo-Signature": "your_signature",
"X-Shimo-Token": "your_token",
},
})
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

HTTP 状态码

状态码说明
200返回成功

HTTP Response Body

字段名类型值示例说明
appNamestringyour app name应用名
availableFileTypesArray["document","documentPro","spreadsheet","presentation","table"]可用石墨套件列表
activatedUserCountnumber43已激活席位用户数
userCountnumber50用户数总数,包含已激活已禁用未使用 用户总数,仅 已激活 数量占用席位
memberLimitnumber99license 席位限制用户数,即 已激活 用户数量最大限制
validFromstring2020-12-31T16:00:00Zlicense 生效时间
validUntilstring2022-12-30T16:00:00Zlicense 有效期截止时间
endpointUrlstringhttp://your-domain服务商回调地址

Example

{
"appName": "your app name",
"availableFileTypes": [
"document",
"documentPro",
"spreadsheet",
"presentation",
"table"
],
"activatedUserCount": 43,
"userCount": 50,
"memberLimit": 99,
"validFrom": "2020-12-31T16:00:00Z",
"validUntil": "2022-12-30T16:00:00Z",
"endpointUrl": "http://your-domain"
}

更新 app 回调地址

用于更新 app 对应服务商回调地址

提醒

由于 app API 的特殊性,为了安全考虑,需要您在生成签名时附加上 "scope": "license" 字段

请求地址

PUT https://shimo-domain/sdk/v2/api/license/apps/{appId}/endpoint-url

HTTP Request Body

字段名类型值示例必选说明
urlstringhttp://your-domain需要更新的服务商回调地址

请求示例

curl -X PUT "https://shimo-domain/sdk/v2/api/license/apps/yourShimoAppId/endpoint-url" \
--header "Content-Type: application/json" \
--header "X-Shimo-Signature: your_signature" \
--header 'X-Shimo-Token: your_token' \
--data-raw $'{"url":"http://your-domain"}'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"url\":\"http://your-domain\"}");
Request request = new Request.Builder()
.url("https://shimo-domain/sdk/v2/api/license/apps/yourShimoAppId/endpoint-url")
.method("PUT", body)
.addHeader("Content-Type", "application/json")
.addHeader("X-Shimo-Signature", "your_signature")
.addHeader("X-Shimo-Token", "your_token")
.build();
Response response = client.newCall(request).execute();
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {
url := "https://shimo-domain/sdk/v2/api/license/apps/yourShimoAppId/endpoint-url"
method := "PUT"

payload := strings.NewReader(`{"url":"http://your-domain"}`)

client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)

if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Shimo-Signature", "your_signature")
req.Header.Set("X-Shimo-Token", "your_token")

res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
var axios = require("axios");
var data = JSON.stringify({
url: "http://your-domain",
});

var config = {
method: "PUT",
url: "https://shimo-domain/sdk/v2/api/license/apps/yourShimoAppId/endpoint-url",
headers: {
"Content-Type": "application/json",
"X-Shimo-Signature": "your_signature",
"X-Shimo-Token": "your_token",
},
data: data,
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

HTTP 状态码

状态码说明
204创建成功

HTTP Response Body

席位管理

caution

由于席位管理 API 的特殊性,为了安全考虑,需要您在生成签名时附加上 "scope": "license" 字段。

用户席位状态说明

目前有三种席位状态:

  • 1 激活
  • 0 已禁用
  • -1 未启用

-1 未启用 状态何时会存在?

若接入方已集成实现@ 人 / 提及人相关功能时,在调用接入方搜索接口时,可能会返回石墨 SDK 中未关联的用户,由于需要在石墨编辑器中的 at 下拉列表中展示此类用户,石墨 SDK 会首先进行建立用户关联操作,此时用户的状态将会初始化为未启用状态,此状态 不会占用 席位数量。

-1 未启用 状态自动激活

当用户处于未启用状态时,当通过此用户身份进行如下操作时,将会自动激活,成为 激活 状态,此时占用相应席位,若席位不足,则会被拒绝访问:

  • 创建文件
  • 创建副本
  • 访问编辑页
  • 导入、导出文件
  • 预览文件
  • 调用表格内容操作接口
  • 获取文件侧边栏历史信息、版本信息
  • 获取文件纯文本信息
  • 获取文件 at 人列表
  • 获取文件评论数据

获取用户列表和席位状态

请求地址

GET http(s)://shimo-domain/sdk/v2/api/license/users

HTTP Request Parameters

传参方式参数名类型值示例必选说明
Querypagenumber1请求页码
Querysizenumber30单页返回用户数量

请求示例

curl --request GET 'https://shimo-domain/sdk/v2/api/license/users?page=1&size=30' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://shimo-domain/sdk/v2/api/license/users?page=1&size=30")
.method("GET", null)
.addHeader("X-Shimo-Signature", "your_signature")
.addHeader("X-Shimo-Token", "your_token")
.build();
Response response = client.newCall(request).execute();
package main

import (
"fmt"
"net/http"
"io/ioutil"
)

func main() {
url := "https://shimo-domain/sdk/v2/api/license/users?page=1&size=30"
method := "GET"

client := &http.Client {
}
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}

req.Header.Set("X-Shimo-Signature", "your_signature")
req.Header.Set("X-Shimo-Token", "your_token")

res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
var axios = require("axios");

var config = {
method: "get",
url: "https://shimo-domain/sdk/v2/api/license/users?page=1&size=30",
headers: {
"X-Shimo-Signature": "your_signature",
"X-Shimo-Token": "your_token",
},
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

HTTP Response Body

响应体示例:

[
{
"userId": "1",
"createdAt": "2021-05-20T14:56:53+08:00",
"status": 1
}
]
字段名类型值示例说明
userIdstring1用户 ID
createdAtstring2021-05-20T14:56:53+08:00创建时间
statusnumber1用户席位状态说明

激活用户席位

请求地址

POST http(s)://shimo-domain/sdk/v2/api/license/users/activate

HTTP Request Body

请求体示例:

字段名类型值示例必选说明
userIds[]string["1", "2"]需要激活席位的用户 ID 列表

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/license/users/activate' \
--header 'Content-Type: application/json' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{"userIds":["1","2"]}'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"userIds\":[\"1\",\"2\"]}");
Request request = new Request.Builder()
.url("https://shimo-domain/sdk/v2/api/license/users/activate")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("X-Shimo-Signature", "your_signature")
.addHeader("X-Shimo-Token", "your_token")
.build();
Response response = client.newCall(request).execute();
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {
url := "https://shimo-domain/sdk/v2/api/license/users/activate"
method := "POST"

payload := strings.NewReader(`{"userIds":["1","2"]}`)

client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}

req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Shimo-Signature", "your_signature")
req.Header.Set("X-Shimo-Token", "your_token")

res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
var axios = require("axios");
var data = JSON.stringify({
userIds: ["1", "2"],
});

var config = {
method: "post",
url: "https://shimo-domain/sdk/v2/api/license/users/activate",
headers: {
"Content-Type": "application/json",
"X-Shimo-Signature": "your_signature",
"X-Shimo-Token": "your_token",
},
data: data,
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

HTTP Response Body

HTTP 状态码

状态码说明
204操作成功

取消用户席位

被取消席位的 userId 只能通过重新激活才可以使用。

请求地址

POST http(s)://shimo-domain/sdk/v2/api/license/users/deactivate

HTTP Request Body

请求体示例:

字段名类型值示例必选说明
userIds[]string["1", "2"]需要取消席位的用户 ID 列表

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/license/users/deactivate' \
--header 'Content-Type: application/json' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{"userIds":["1","2"]}'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"userIds\":[\"1\",\"2\"]}");
Request request = new Request.Builder()
.url("https://shimo-domain/sdk/v2/api/license/users/deactivate")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("X-Shimo-Signature", "your_signature")
.addHeader("X-Shimo-Token", "your_token")
.build();
Response response = client.newCall(request).execute();
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {
url := "https://shimo-domain/sdk/v2/api/license/users/deactivate"
method := "POST"

payload := strings.NewReader(`{"userIds":["1","2"]}`)

client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}

req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Shimo-Signature", "your_signature")
req.Header.Set("X-Shimo-Token", "your_token")

res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
var axios = require("axios");
var data = JSON.stringify({
userIds: ["1", "2"],
});

var config = {
method: "post",
url: "https://shimo-domain/sdk/v2/api/license/users/deactivate",
headers: {
"Content-Type": "application/json",
"X-Shimo-Signature": "your_signature",
"X-Shimo-Token": "your_token",
},
data: data,
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

HTTP Response Body

HTTP 状态码

状态码说明
204操作成功

批量设置用户席位

请求地址

POST http(s)://shimo-domain/sdk/v2/api/license/users/set-status

HTTP Request Body

请求体示例:

字段名类型值示例必选说明
userIds[]string["1", "2"]需要修改席位状态的用户 ID 列表
statusnumber-1用户席位状态说明
注意

设置为 -1 未启用 并不能阻止用户继续使用石墨 SDK,比如用户打开的石墨 SDK 页面并没有关闭,signature 和 token 仍有效,即使设置为 -1 未启用,只要用户未关闭的页面发起了请求,状态也会被自动设置为 1 激活

请求示例

curl -X POST 'https://shimo-domain/sdk/v2/api/license/users/set-status' \
--header 'Content-Type: application/json' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{"userIds":["1","2"],"status":1}'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"userIds\":[\"1\",\"2\"],\"status\":1}");
Request request = new Request.Builder()
.url("https://shimo-domain/sdk/v2/api/license/users/set-status")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("X-Shimo-Signature", "your_signature")
.addHeader("X-Shimo-Token", "your_token")
.build();
Response response = client.newCall(request).execute();
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {
url := "https://shimo-domain/sdk/v2/api/license/users/set-status"
method := "POST"

payload := strings.NewReader(`{"userIds":["1","2"],"status":1}`)

client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}

req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Shimo-Signature", "your_signature")
req.Header.Set("X-Shimo-Token", "your_token")

res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
var axios = require("axios");
var data = JSON.stringify({
userIds: ["1", "2"],
status: 1,
});

var config = {
method: "POST",
url: "https://shimo-domain/sdk/v2/api/license/users/set-status",
headers: {
"Content-Type": "application/json",
"X-Shimo-Signature": "your_signature",
"X-Shimo-Token": "your_token",
},
data: data,
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

HTTP Response Body

HTTP 状态码

状态码说明
204操作成功