跳到主要内容
2023-12-13 02:52 更新版本:latest

协同编辑

基础功能

创建协同文档

创建指定类型的协同文档,创建后加载编辑器。

支持的文件类型类型值
轻文档document
表格spreadsheet
传统文档documentPro
幻灯片presentation
应用表格table
说明
  • 轻文档传统文档表格幻灯片,其他类型为非标准功能 (如 应用表格) ,详询石墨客服。
  • 轻文档应用表格之外,其他文件类型均高度兼容 Office 格式

请求地址

POST https://shimo-domain/sdk/v2/api/files

HTTP Request Parameters

传参方式参数名类型值示例必选说明
Querylangstringen可选。默认值为服务端默认语言设置,通常默认为 zh-CN 。指定创建文件时的语言信息,可选值:zh-CN(简体中文)、en(英文)、ja(日文)

HTTP Request Headers

Header 名必选说明
Accept-Languagezh-CN,zh;q=0.9,en;q=0.8若无 lang 参数默认尝试从此 Header 识别,若未传此 Header 则使用服务器默认语言。Accept-Languge 格式参考 MDN Accept-Language

HTTP Request Body

字段名类型值示例必选说明
typestringdocument石墨文件类型,可选值参考 「支持的文件类型」 部分
fileIdstringfileid1001接入服务商的文件的唯一 ID,必须为不超过 64 长度的字符串

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/files' \
--header 'Content-Type: application/json' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{"type": "document","fileId": "83478944-8d4c-4936-baff-20ab180eb712"}'

HTTP 状态码

状态码说明
204创建成功

HTTP Response Body

创建协同文档副本

创建指定协同文档的副本。

提示

path 中的 shimo-files 改为 collab-files,原 shimo-files 仍可用

请求地址

POST https://shimo-domain/sdk/v2/collab-files/{fileId}/copy

HTTP Request Body

字段名类型值示例必选说明
fileIdstringfileid1001新文件 ID,接入方的文件唯一 ID,字符串长度不超过 64 。

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/files/e0f238d1-8c10-448c-bf69-cd315051c095/copy' \
--header 'Content-Type: application/json' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{"fileId": "83478944-8d4c-4936-baff-20ab180eb712"}'

HTTP 状态码

状态码说明
204创建成功
200重复请求时,文件拷贝正在执行,响应数据 {"code":70019}
400重复请求时,目标文件关联数据存在但无法找到创建副本任务信息,响应数据 {"code":70016}
400重复请求时,目标文件关联数据存在,创建副本执行失败,响应数据 {"code":70017}
500重复请求时,创建副本时获取源文件内容遇到错误,响应数据 {"code":70015}
500重复请求时,获取创建副本任务时遇到错误,响应数据 {"code":70018}
500重复请求时,未知的创建副本任务状态, 响应数据 {"code":70020}

HTTP Response Body

删除协同文档

删除指定类型的协同文档,要求用户对文档有 manageable 权限。

请求地址

DELETE https://shimo-domain/sdk/v2/api/files/{fileId}

HTTP Request Body

请求示例

curl --request DELETE 'https://shimo-domain/sdk/v2/api/files' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP 状态码

状态码说明
204操作成功

HTTP Response Body

获取历史列表

获取文件侧边栏历史列表信息,历史类型分为操作历史和编辑历史。

提示

path 中的 shimo-files 改为 collab-files,原 shimo-files 仍可用

请求地址

GET https://shimo-domain/sdk/v2/collab-files/{fileId}/doc-sidebar-info

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址
QuerypageSizenumber10每一页返回的条数,推荐值 1020 ,设的过大将会影响响应时间。默认值为 10
Querycountnumber0当前页需要跳过的记录数,可通过 count = (page - 1) * pageSize 求得。默认值为 0
QueryhistoryTypenumber1可选值:1 操作历史 (如锁定单元格此类未实际编写内容的修改产生的操作历史),2 编辑历史。未传时,默认返回所有类型

请求示例

curl "https://shimo-domain/sdk/v2/collab-files/{fileId}/doc-sidebar-info" \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP 状态码

状态码说明
200返回成功

HTTP Response Body

字段名类型值示例说明
historiesarray-侧边栏历史数组
histories[i].contentstring-协作文件格式数据
histories[i].createdAtstring2021-06-07T06:12:24Z本条侧边栏历史创建时间
histories[i].historyTypenumber2侧边栏历史类型,1 为操作历史,2 为编辑产生
histories[i].idstring60bdb8c847a7850006bf12c1侧边栏历史 ID
histories[i].namestring历史 1侧边栏历史名称
histories[i].updatedAtstring2021-06-07T06:12:24Z侧边栏历史最后更新时间
histories[i].userIdstringuser123,user134服务商用户 ID,可能有多个,以英文逗号 "," 分隔
isLastPageboolean是否最后一页
limitnumber100分页大小
usersobject{ "user123": "用户 A" }接入方用户 ID 对应的用户名映射

Example

{
"histories": [
{
"content": "{\"range\":[1,1],\"changeset\":\"[[10, \\\"\\\\n\\\", \\\"line:\\\\\\\"init\\\\\\\"\\\"]]\",\"frozen\":true}",
"createdAt": "2021-06-07T06:12:24Z",
"historyType": 2,
"id": "60bdb8c847a7850006bf12c1",
"name": "",
"updatedAt": "2021-06-07T06:12:24Z",
"userId": "user123,user134"
},
{
"content": "{\"range\":[2,3],\"changeset\":\"省略若干内容 ...\"}",
"createdAt": "2021-06-07T06:12:39Z",
"historyType": 2,
"id": "60bdb8d747a7850006bf12c2",
"name": "",
"updatedAt": "2021-06-07T06:12:39Z",
"userId": "user123,user134"
},
{
"content": "{\"action\":\"unlock_cell\",\"range\":[\"E14:E14\"],\"name\":\"工作表1\"}",
"createdAt": "2022-03-11T03:58:59Z",
"historyType": 1,
"id": "622ac9034079aa0006d54f3b",
"name": "",
"updatedAt": "2022-03-11T03:58:59Z",
"userId": "user123"
},
{
"content": "{\"action\":\"lock_sheet\",\"name\":\"工作表1\"}",
"createdAt": "2022-03-11T03:59:04Z",
"historyType": 1,
"id": "622ac9084079aa0006d54f3c",
"name": "",
"updatedAt": "2022-03-11T03:59:04Z",
"userId": "user123"
}
],
"isLastPage": true,
"limit": null,
"users": {
"user123": "testuser",
"user134": "testuser2"
}
}

操作历史说明 (historyType = 1)

表示手动操作而通常不造成文件内容等发生变化的记录,例如创建版本、锁定单元格等操作,此类历史的类型及上下文信息存于 content 字段中,格式为 JSON 字符串形式。

JSON 数据为 histories[i].content 字段,经过 JSON.parse()解析后的结果如下:

createRevision 创建版本
{
"action": "createRevision"
}
renameRevision 重命名版本
{
"action": "renameRevision",
"before": "修改前的版本名称",
"after": "修改后的版本名称"
}
deleteRevision 删除版本
{
"action": "deleteRevision",
"label": "被删除的版本名称"
}
lock_cell 锁定单元格
{
"action": "lock_cell",
"range": "E14:E14",
"name": "工作表1"
}
unlock_cell 解锁单元格
{
"action": "unlock_cell",
"range": ["E14:E14"],
"name": "工作表1"
}
lock_sheet 锁定工作表
{
"action": "lock_sheet",
"name": "工作表1"
}
unlock_sheet 解锁工作表
{
"action": "unlock_sheet",
"name": "工作表1"
}
update_lock_cell 更新单元格锁定
{
"action": "update_lock_cell",
"range": ["E17:E17"],
"name": "工作表1"
}

编辑历史说明 (historyType = 2)

表示一个或多个用户在一段时间内对文件内容进行了编辑。

获取版本列表

获取文件版本列表信息。

提示

path 中的 shimo-files 改为 collab-files,原 shimo-files 仍可用

请求地址

GET https://shimo-domain/sdk/v2/collab-files/{fileId}/revisions

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址

请求示例

curl --request GET 'https://shimo-domain/sdk/v2/collab-files/{fileId}/revisions' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP 状态码

状态码说明
200返回成功

HTTP Response Body

字段名类型值示例说明
idstring11089版本 ID
labelstring2021/6/7 星期一 14:33版本 Label
titlestring123标题
docHistoryIdstring60bdbda2f0a8af000664d719对应侧边栏历史 ID
createdAtstring2021-06-07T06:33:13Z侧边栏历史创建时间
updatedAtstring2021-06-07T06:33:13Z侧边栏历史更新时间
user.idstringuser123服务商用户 ID
user.namestringtestuser用户名

Example

[
{
"id": 11089,
"label": "2021/6/7 星期一 14:33",
"title": "123",
"docHistoryId": "60bdbda2f0a8af000664d719",
"createdAt": "2021-06-07T06:33:13.000Z",
"updatedAt": "2021-06-07T06:33:13.000Z",
"user": {
"id": "user123",
"name": "testuser"
}
},
{
"id": 11090,
"label": "2021/6/7 星期一 14:33",
"title": "123",
"docHistoryId": "60bdbdd5f0a8af000664d71d",
"createdAt": "2021-06-07T06:33:59.000Z",
"updatedAt": "2021-06-07T06:33:59.000Z",
"user": {
"id": "user123",
"name": "testuser"
}
}
]

获取文件纯文本内容

获取指定文件的纯文本形式内容。

提示

path 中的 shimo-files 改为 collab-files,原 shimo-files 仍可用

支持文件类型:

  • document 轻文档
  • documentPro 传统文档
  • spreadsheet 表格
  • presentation 幻灯片

请求地址

GET https://shimo-domain/sdk/v2/collab-files/{fileId}/plain-text

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址

请求示例

curl --request GET 'https://shimo-domain/sdk/v2/collab-files/{fileId}/plain-text' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP 状态码

状态码说明
200返回成功

HTTP Response Body

字段名类型值示例说明
contentstring文件纯文本内容根据指定文件 ID 获取的石墨文件纯文本内容

Example

{
"content": "文件纯文本内容"
}

文件纯文本字数统计

获取指定文件的纯文本字数以及给定关键词出现的次数。 中日韩文字,每个字符都当做一个独立的单词来计数,比如对于“你好”,是两个单词:”你“ 和 ”好“ 英文和其它符号,只会由空格来区分,比如对于“Hello world”,也只有两个单词:“Hello” 和 “world”。

提示

path 中的 shimo-files 改为 collab-files,原 shimo-files 仍可用

支持文件类型:

  • document 轻文档
  • documentPro 传统文档
  • spreadsheet 表格
  • presentation 幻灯片

请求地址

POST https://shimo-domain/sdk/v2/collab-files/{fileId}/plain-text/wc

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址

HTTP Request Body

字段名类型值示例必选说明
keywords[]string["foo", "bar"]要查询的关键词

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/collab-files/{fileId}/plain-text/wc' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{
"keywords": ["foo", "bar"]
}'

HTTP 状态码

状态码说明
200返回成功

HTTP Response Body

字段名类型值示例说明
wordCountnumber纯文本字数根据指定文件 ID 获取的石墨文件纯文本字数
keywordsobject关键词出现次数map[keyword]count,示例: {"foo":1,"bar":10}

Example

{
"wordCount": 10,
"keywords": {
"foo": 1,
"bar": 2
}
}

获取文件内容中所有的 at 人信息列表

获取文件内容中所有的 at 人信息列表。

支持的文件类型:

  • document 轻文档
  • documentPro 传统文档
  • spreadsheet 表格
提示

path 中的 shimo-files 改为 collab-files,原 shimo-files 仍可用

请求地址

GET https://shimo-domain/sdk/v2/collab-files/{fileId}/mention-at-list

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址

请求示例

curl "https://shimo-domain/sdk/v2/collab-files/ad8ed1afa8172d91/mention-at-list" \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP 状态码

状态码说明
200返回成功

HTTP Response Body

字段名类型值示例说明
mentionAtListArray-根据指定文件 ID 获取的石墨文件中的所有 at 信息列表
mentionAtList[0].userIdstringuser1at 提及的用户 ID
mentionAtList[0].atGuidstringMODOCnb4HPu04G8fat 提及在文件中对应的位置标记

Example

{
"mentionAtList": [
{
"userId": "1",
"atGuid": "MODOCnb4HPu04G8f"
},
{
"userId": "4",
"atGuid": "MODOCPryKBQpdLVS"
},
{
"userId": "3",
"atGuid": "MODOC6IQPpxpi5RV"
},
{
"userId": "1", // 同个用户在不同位置被 at
"atGuid": "MODOCSxgFvWiIupK"
}
]
}

获取文件中的评论数

获取文件内中的评论总数。

支持文件类型:

  • spreadsheet 表格
提示

path 中的 shimo-files 改为 collab-files,原 shimo-files 仍可用

请求地址

GET https://shimo-domain/sdk/v2/collab-files/{fileId}/comment-count

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址

请求示例

curl "https://shimo-domain/sdk/v2/collab-files/fe143ca1a08e9976/comment-count" \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP 状态码

状态码说明
200返回成功

HTTP Response Body

字段名类型值示例说明
countnumber2评论条数

Example

{
"count": 2
}

表格

表格参数说明

range

格式为 {工作表}!{单元格范围},规范如下:

  • 单元格范围的格式为 A1:C10 or A1,单元格起始位置不能超过表格最大的行列
  • 如果工作表名称中含有 !:' 这 3 种特殊字符,必须以单引号包裹工作表名称。示例:
    • 工作表1
    • 工作表1!A1
    • 工作表1!A1:C1
    • '工作!:表'!A2:C3

resource

类型为 object,里面必须包含 key 值 "values"values 为一个二维数组,表示追加/更新的表格内容,第一维表示行,第二维表示列。空字符串表示当前单元格为空。 示例:

返回一行数据
{
"resource": {
"values": [[1, "", "a"]]
}
}
返回多行数据
{
"resource": {
"values": [
[1, "", "a"],
["b", "c", 2]
]
}
}

日期类型 OADate 数值转换

日期类型返回值为 OADate 类型数值,如单元格中日期为 2022/7/27 ,返回的值为 44769

参考以下 JavaScript 代码进行转换:

convertOADateToLocaleDateString.js
function _getTimezoneOffset(date) {
let offset = date.getTimezoneOffset();
if (offset === -485) {
offset = -485 - 43 / 60;
}
return offset;
}

function _fromOADate(oadate) {
const offsetDay = oadate - 25569;
const date = new Date(offsetDay * 86400000);

const adjustValue = offsetDay >= 0 ? 1 : -1;
const oldDateTimezoneOffset = _getTimezoneOffset(date);
const ms =
(oadate * 86400000 * 1440 +
adjustValue -
25569 * 86400000 * 1440 +
oldDateTimezoneOffset * 86400000) /
1440;
let firstResult = new Date(ms);

const fixHourSign = oldDateTimezoneOffset >= 0 ? 1 : -1;
const nextHour = new Date(ms + fixHourSign * 3600000);
const nextHourTimezoneOffset = _getTimezoneOffset(nextHour);
if (oldDateTimezoneOffset !== nextHourTimezoneOffset) {
let newResult = new Date(
ms + (nextHourTimezoneOffset - oldDateTimezoneOffset) * 60 * 1000
);
if (oldDateTimezoneOffset > nextHourTimezoneOffset) {
if (
fixHourSign === -1 ||
nextHourTimezoneOffset === _getTimezoneOffset(firstResult)
) {
newResult =
newResult.getMilliseconds() === 999
? new Date(newResult.valueOf() + 1)
: newResult;
return newResult;
}
} else if (oldDateTimezoneOffset < nextHourTimezoneOffset) {
if (
fixHourSign === 1 ||
nextHourTimezoneOffset === _getTimezoneOffset(firstResult)
) {
newResult =
newResult.getMilliseconds() === 999
? new Date(newResult.valueOf() + 1)
: newResult;
return newResult;
}
}
}

firstResult =
firstResult.getMilliseconds() === 999
? new Date(firstResult.valueOf() + 1)
: firstResult;
return firstResult;
}

function convertOADate(OAdate) {
return _fromOADate(OAdate).toLocaleDateString();
}

convertOADate(44769);
// '2022/7/27'

获取表格内容

根据传入的表格范围获取表格内容。

支持文件类型:

  • spreadsheet 表格

请求地址

GET https://shimo-domain/sdk/v2/api/files/{fileId}/sheets/values

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址
Queryrangestring工作表1!A1:C3请参考 range 参数说明。

请求示例

curl --request GET 'https://shimo-domain/sdk/v2/api/files/{fileId}/sheets/values?range=工作表1!A1:C3' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP 状态码

状态码说明
200返回成功

HTTP Response Body

字段名类型值示例说明
valuesarray[["姓名","年龄","性别"],["小明",29,"男"]]表格单元格值

Example

{
"values": [
["姓名", "年龄", "性别"],
["小明", 29, "男"],
["小强", 18, "男"],
["小兰", 20, "女"],
[null, null, "a"]
]
}

更新表格内容

根据传入范围更新表格内容。

支持文件类型:

  • spreadsheet 表格

请求地址

POST https://shimo-domain/sdk/v2/api/files/{fileId}/sheets/values

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址

HTTP Request Body

字段名类型值示例说明
rangestring工作表1!A1:C3请参考 range 参数说明。
resourceobject-请参考 resource 参数说明。

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/files/{fileId}/sheets/values' \
--header 'Content-Type: application/json' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{
"range": "工作表1!A1:C3",
"resource": {
"values": [
["第一行第一列的值","第一行第二列的值"],
["第二行第一列的值","第二行第二列的值"]
]
}
}'

HTTP 状态码

状态码说明
204返回成功

HTTP Response Body

追加表格内容

根据传入的表格范围追加表格内容(只支持纯文本和数字)。

支持文件类型:

  • spreadsheet 表格

根据 range 查找追加位置的逻辑是定位到需要追加的行位置: a. 不指定单元格范围,例如工作表1:会遍历整个表格,找到最后一个有数据的行 b. 指定单元格范围,例如 工作表1!C5:E8:会找到起始单元格 C5 所在的行,从该行向下遍历,找到最后一个连续的有数据行向下插入 N 行,填充 values,其中 N = values.length 如果修改了不存在的列,会自动新增到该列。

请求地址

PUT https://shimo-domain/sdk/v2/api/files/{fileId}/sheets/values

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址

HTTP Request Body

字段名类型值示例说明
rangestring工作表1!A1:C3请参考 range 参数说明。
resourceobject-请参考 resource 参数说明。

请求示例

curl --request PUT 'https://shimo-domain/sdk/v2/api/files/{fileId}/sheets/values' \
--header 'Content-Type: application/json' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{
"range": "工作表1!A1:C3",
"resource": {
"values": [
["第一行第一列追加文本","第一行第二列追加文本"],
["第二行第一列追加文本","第二行第二列追加文本"]
]
}
}'

HTTP 状态码

状态码说明
204返回成功

HTTP Response Body

删除表格行

删除表格中的一行和多行。从 index 开始,删除数量为 count 的行数。

支持文件类型:

  • spreadsheet 表格

请求地址

DELETE https://shimo-domain/sdk/v2/api/files/{fileId}/sheets/{sheetName}/rows/{index}

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址
PathsheetNamestring工作表1表格中工作表的名称
Pathindexnumber0从第几行开始删除
Querycountnumber1删除几行,默认为 1

HTTP Request Body

请求示例

curl --request DELETE 'https://shimo-domain/sdk/v2/api/files/{fileId}/sheets/工作表1/rows/0?count=2' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP 状态码

状态码说明
204返回成功

HTTP Response Body

新增表格工作表

在表格中新增工作表。

支持文件类型:

  • spreadsheet 表格

请求地址

POST https://shimo-domain/sdk/v2/api/files/{fileId}/sheets/

HTTP Request Parameters

传参方式参数名类型值示例必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址

HTTP Request Body

字段名类型值示例说明
namestring工作表 2新增表格工作表名称

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/files/{fileId}/sheets' \
--header 'Content-Type: application/json' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{"name": "工作表2"}'

HTTP 状态码

状态码说明
204返回成功

HTTP Response Body

表格上传附件

步骤一:获取 Token

POST https://shimo-domain/sdk/v2/api/uploader/token

Body 请求参数

[
{
"bucket": "attachments",
"filename": "my_file.png",
"fileSize": 368,
"encrypt": "default"
}
]

请求参数

名称位置类型必选说明
X-Shimo-SignatureheaderstringX-Shimo-Signature
X-Shimo-TokenheaderstringX-Shimo-Token
Content-Typeheaderstringapplication/json
bodybodyarray[object]none
body[i].bucketbodystring别名,必须为以下几种之一:attachments,assets,avatar,images
body[i].filenamebodystring指定上传文件的文件名, 为空时使用 untitled{ext} 作为文件名
body[i].fileSizebodynumber文件大小,单位字节
body[i].encryptbodystring是否开启加密,若开启填 default

返回示例

200 Response

[
{
"fileFieldKey": "string",
"formData": {
"accessToken": "string",
"download": "string"
},
"guid": "string",
"images": "string",
"key": "string",
"serverUrl": "string",
"url": "string"
}
]

返回结果

状态码状态码含义说明数据模型
200OK成功Inline

返回数据结构

状态码 200

名称类型必选约束中文名说明
fileFieldKeystringfalsenonefile第二步上传时 file 应该使用的 key name。固定值 file
formDataobjectfalsenone-第二步上传时的 post form data
accessTokenstringtruenone-第二步上传时候使用的 accessToken
downloadstringtruenone-控制生成的 url 是否携带 download=1 参数
guidstringfalsenone附件 guid附件 guid
imagesstringfalsenoneurl同 url,兼容使用
keystringfalsenone附件 key附件 key
serverUrlstringfalsenone上传地址下一步上传需要提交 post 表单到的服务器地址
urlstringfalsenoneurl附件访问 url

步骤二:执行上传

POST https://shimo-domain/sdk/v2/api/uploader/upload

Body 请求参数

accessToken: string
download: true, false
file: string

请求参数

名称位置类型必选说明
Content-Typeheaderstring表单
X-Shimo-SignatureheaderstringX-Shimo-Signature
X-Shimo-TokenheaderstringX-Shimo-Token
bodybodyobjectnone
accessTokenbodystring第一步中获取到的 accessToken
downloadbodystring是否在返回结果 url 中增加 download 参数
filebodystring(binary)文件

返回示例

200 Response

{
"code": 0,
"data": {
"GUID": "string",
"filename": "string",
"key": "string",
"mimeType": "string",
"images": "string",
"rawUrl": "string",
"url": "string",
"audio": null,
"video": null,
"width": "string",
"height": "string",
"size": 0
}
}

返回结果

状态码状态码含义说明数据模型
200OK成功Inline

返回数据结构

状态码 200

名称类型必选约束中文名说明
codeintegertruenone-none
dataobjecttruenone-none
GUIDstringtruenoneGUID附件 GUID
filenamestringtruenone文件名称文件名称
keystringtruenonekey附件 key
mimeTypestringtruenonemimeType例如 application/gzip
imagesstringtruenone同 urlnone
urlstringtruenone附件 urlnone
audionulltruenone音频信息none
videonulltruenone视频信息例如 {"width":"640","height":"352","duration":"17.333333","fps":"","fileFormat":"","bitrate":"49710"}
widthstringtruenone图片宽度none
heightstringtruenone图片高度none
sizeintegertruenone大小字节

传统文档

读取传统文档书签内容

读取传统文档指定书签内容。

请求地址

GET https://shimo-domain/sdk/v2/api/files/{fileId}/documentpro/bookmark_content

HTTP Request Query

传参方式参数名类型值示例必选说明
Querybookmarks[]string["guid"]数组最大长度 500

请求示例

curl --request GET 'https://shimo-domain/sdk/v2/api/files/{fileId}/documentpro/bookmark_content?bookmarks=1&bookmarks=2' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP 状态码

状态码说明
200返回成功

HTTP Response Body

字段名类型值示例说明
dataArray-列表
data[0].bookmarkstring测试书签名称
data[0].contentstring学习网站书签内容

替换传统文档书签内容

替换传统文档指定书签部分内容。

请求地址

PUT https://shimo-domain/sdk/v2/api/files/{fileId}/documentpro/bookmark_content

HTTP Request Body

传参方式参数名类型值示例必选说明
BodyreplacementsArray-数组最大长度 50
Bodyreplacements[0].bookmarkstring-字符串最大长度 500
Bodyreplacements[0].typestringtext书签类型 text / document
Bodyreplacements[0].valuestring-字符串最大长度 5242880
说明
  • 书签类型 text 则 value 为替换的文本内容
  • 书签类型 document 则 value 为 {fileId}

请求示例

curl --request GET 'https://shimo-domain/sdk/v2/api/files/{fileId}/documentpro/bookmark_content' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'
--data-raw '{"replacements": [{"bookmark":"bookmark","type":"text","value":"bookmark value"}]}'

HTTP 状态码

状态码说明
204返回成功