Skip to main content
2023-12-13 02:52 更新Version: latest

系统接口

鉴权方式

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'

账号与应用管理

获取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'

HTTP状态码

HTTP 状态码用来表明特定 HTTP 请求是否成功完成。当状态码为200时,表示请求成功。

HTTP Response Body

类型字段名说明值示例
stringappName应用名your app name
ArrayavailableFileTypes可用石墨套件列表["document","documentPro","spreadsheet","presentation","table"]
numberactivatedUserCount已激活席位用户数43
numberuserCount用户数总数,包含已激活、已禁用和未使用的用户总数,仅“已激活 ”数量占用席位。50
numbermemberLimitlicense 席位限制用户数,即“已激活 ”用户数量最大限制99
stringvalidFromlicense 生效时间2020-12-31T16:00:00Z
stringvalidUntillicense 有效期截止时间2022-12-30T16:00:00Z
stringendpointUrl接入方回调地址http://your-domain

响应示例

{
"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"}'

HTTP 状态码 当状态码为204时,表示创建成功。

HTTP Response Body

席位管理

用户席位状态说明

值域席位状态说明
1激活仅“激活”状态的用户占用席位数。
0已禁用“已禁用”状态的用户必须重新激活才可以使用。
-1未启用1、若接入方已集成实现@ 人 / 提及人相关功能时,在调用接入方搜索接口时,可能会返回石墨 SDK 中未关联的用户,由于需要在石墨编辑器中的 at 下拉列表中展示此类用户,石墨 SDK 会首先进行建立用户关联操作,此时用户的状态将会初始化为未启用状态,此状态 不会占用 席位数量。
2、当用户处于未启用状态时,当通过此用户身份进行如下操作时,将会自动激活,成为 激活 状态,此时占用相应席位,若席位不足,则会被拒绝访问:

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

获取用户列表和席位状态

提示

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

请求地址

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'

HTTP Response Body

字段名类型值示例说明
userIdstring1用户 ID
createdAtstring2021-05-20T14:56:53+08:00创建时间
statusnumber1请参考 用户席位状态说明

响应示例

[
{
"userId": "1",
"createdAt": "2021-05-20T14:56:53+08:00",
"status": 1
}
]

激活用户席位

提示

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

请求地址

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"]}'

HTTP状态码 当状态码为204时,表示操作成功。

HTTP Response Body

取消用户席位

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

提示

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

请求地址

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"]}'

HTTP状态码 当状态码为204时,表示操作成功。

HTTP Response Body

批量设置用户席位

提示

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

请求地址

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}'

HTTP状态码 当状态码为204时,表示操作成功。

HTTP Response Body