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

文件操作

上传下载

上传附件

步骤一:获取 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大小字节

导入导出

导入文件

导入文件过程是一个异步处理过程,接口请求成功仅代表导入服务收到并开始处理导入请求,实际是否成功需要轮询 获取导入进度 接口查询导入任务是否完成。

说明

此接口为新版导入文件接口,建议优先使用。新版导入文件接口要求接入方必须解析结果中的 taskId,并且在调用 获取导入进度 时带上 taskId 参数。任务执行的最长时间为 10 分钟。

导入支持的文件格式

石墨文件类型支持导入的文件类型
document.docx,.doc,.md,.txt
documentPro.docx,.doc,.wps
spreadsheet.xlsx,.xls,.csv, .xlsm
presentation.pptx,.ppt

请求地址

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

HTTP Request Body

传参方式参数名类型值示例必选说明
FormfileIdstringfile1001服务商文件的唯一 ID
FormtypestringdocumentPro需要导入的文件类型
Formfilefile需要导入的文件(如果不发送文件,就必须传 fileUrl、fileName)
FormfileUrlstringhttps://domain.com/files/download/test.docx需要导入的文件下载地址(有参数 file,可以不用传)
FormfileNamestringtest.docx需要导入的文件名称(有参数 file,可以不用传)
说明

如无特别说明,导入文件时需要附带扩展名,否则可能解析失败,如「测试文件.doc」或使用 FormDatafilename 字段中传入带扩展名的文件名,详细操作请参考 MDN

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/files/v1/import' \
--form 'fileId="{importFileId}"' \
--form 'type="document"' \
--form 'file=@"/your/local/path/测试.docx"' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP Response Body

字段名类型值示例说明
statusnumber0导入状态,非零值表示异常
messagestring导入异常时的提示信息
data.taskIdstringTnJdQS8Wk70wNHuB导入任务的标识 ID,调用导入进度接口时,请带上该参数。导入失败时请提供此 ID 用于调试

获取导入进度

提示

此接口为新版获取导入进度接口,建议优先使用。当任务完成之后,进度结果将会默认缓存 5 分钟,过期之后再次调用进度结果将会失败。

请求地址

POST https://shimo-domain/sdk/v2/api/files/v1/import/progress

HTTP Request Parameters

传参方式参数名类型值示例必选说明
QuerytaskIdstringTnJdQS8Wk70wNHuB导入文件接口返回的 taskId

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/files/v1/import/progress?taskId={taskId}' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw ''

HTTP Response Body

字段名类型值示例说明
statusnumber0导入状态,非零值表示异常
messagestring导入异常时的提示信息
data.progressnumber100导入进度百分比,为 100 时表示导入完成
说明

通过轮询该接口,直到返回的 status == 0data.progress == 100 时表示导入完成,即可通过对接前端 js-sdk,在页面上进行查看或编辑。

导出文件

将在线编辑文件导出为 Office 文件、PDF 等格式,不同套件支持的导出格式有所不同。

导出文件过程是一个异步处理过程,接口请求成功仅代表导出服务收到并开始处理导出请求,实际是否成功需要轮询 获取导出进度 接口查询导出任务是否完成。当任务完成后,用「获取导出进度」返回的链接 ( data.downloadUrl 字段) 下载文件。

提示

此接口为新版导出文件接口,建议优先使用。新版导出文件接口要求接入方必须解析结果中的 taskId,并且在调用 获取导出进度 时带上 taskId 参数。此接口允许同时将同一个石墨文件导出为不同的文件类型,例如:同时将轻文档导出为 PDF 和 Word 两个格式。任务执行的最长时间为 10 分钟。

导出支持的文件格式

石墨文件类型默认导出的文件类型支持导出的文件类型
documentdocxdocx, md, jpg, pdf
documentProdocxdocx, pdf, wps
spreadsheetxlsxxlsx
presentationpptxpptx, pdf

请求地址

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

HTTP Request Body

传参方式参数名类型值示例必选说明
Bodytypestringdocx需要导出的文件类型,不传时按照默认类型导出

导出支持的文件格式

石墨文件类型默认导出的文件类型支持导出的文件类型
documentdocxdocx, md, jpg, pdf
documentProdocxdocx, pdf, wps
spreadsheetxlsxxlsx
presentationpptxpptx, pdf

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/files/v1/export/{exportFileId}' \
--header 'Content-Type: application/json' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw '{"type": "docx"}'

HTTP Response Body

字段名类型值示例说明
statusnumber0导出状态,非零值表示异常
data.taskIdstring3oo4vnBJgcG5HxMm:1:603:xmind导出任务的标识 ID,调用导出进度接口时,请带上该参数,导出失败时请提供此 ID 用于调试
messagestring导出异常时的提示信息

获取导出进度

说明

此接口为新版获取导入进度接口,建议优先使用。进度结果将会默认缓存 5 分钟,过期之后再次调用进度结果将会失败。

请求地址

POST https://shimo-domain/sdk/v2/api/files/v1/export/progress

HTTP Request Parameters

传参方式参数名类型值示例必选说明
QuerytaskIdstring3oo4vnBJgcG5HxMm:1:603:xmind导出文件接口返回的 taskId

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/files/v1/export/progress?taskId={taskId}' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token' \
--data-raw ''

HTTP Response Body

字段名类型值示例说明
statusnumber0导出状态,非零值表示异常
messagestring-导出异常时的提示信息
data.progressnumber100导出进度百分比,为 100 时表示导入完成
data.downloadUrlstring-导出文件的下载地址
提示

通过轮询该接口,直到返回的 data.progress == 100 时表示导出完成。

导出应用表格为 Excel

导出应用表格为 .xlsx 文件并返回该文件的下载地址。

请求地址

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

HTTP Request Parameters

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

请求示例

curl -X POST "https://shimo-domain/sdk/v2/api/files/export/table-sheets/{fileId}" \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP Response Body

字段名类型值示例说明
statusnumber0导出状态,非零值表示异常
messagestring-导出异常时的提示信息
downloadUrlstring-.xlsx 文件下载地址

文件预览

说明

此功能不支持编辑文档,如果要编辑文档,请参考 协同文档

创建预览

同步创建预览任务,,如果创建失败则返回失败的原因。

请求地址

POST https://shimo-domain/sdk/v2/api/cloud-files/{fileID}/create

HTTP Request Parameters

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

请求示例

curl --request POST 'https://shimo-domain/sdk/v2/api/cloud-files/acd87e72-946c-4182-b864-f1a7e9c74ddb/create' \
--header 'X-Shimo-Signature: your_signature' \
--header 'X-Shimo-Token: your_token'

HTTP Response Body

字段名类型值示例说明
codestring90028创建预览结果状态码,空字符串代表创建成功, 非空代表创建失败
messagestringfile is converting创建失败错误信息

Example

// 创建失败
{
"code": "90042",
"message": "文件格式不正确"
}
// 创建成功
{
"code": "",
"message": ""
}

访问预览

用于在浏览器上渲染出预览的页面, 需要嵌入 Iframe 使用。

对于同一个文件, 第一次调用该接口时, 后台会异步调用 创建预览 接口创建任务,创建成功后才会渲染出预览页面。 如果需要加快第一次打开文件的速度, 可在服务端提前调用 创建预览 接口创建预览。

请求地址

GET https://shimo-domain/sdk/v2/api/cloud-files/{fileID}/page

HTTP Request Parameters

传参方式参数名类型示例值必选说明
PathfileIdstringqeK4Xdxvxg8jF5gz文件 ID 位于创建预览接口的 URL 路径中,此文件 ID 为接入服务商文件列表中的唯一 ID,石墨会根据此 ID 请求接入服务商的文件接口获取文件信息和下载地址
Querylangstringzh-CN页面中的语言设置, 默认 zh-CN, 可选 en-US,ja-JP

嵌入 iframe 使用

<html>
<head>
<!-- some code -->
</head>
<body>
<!-- your HTML elements -->
<div id="shimo-sdk-preview" class="shimo-sdk-preview">
<iframe
src="https://shimo-domain/sdk/v2/api/cloud-files/acd87e72-946c-4182-b864-f1a7e9c74ddb/page?signature=your_signature&token=your_token&lang=zh-CN"
style="border: none; overflow: hidden;"
></iframe>
</div>
</body>
</html>