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

文件操作

导入导出

导入文件

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

说明

此接口为新版导入文件接口,建议优先使用。新版导入文件接口要求接入方必须解析结果中的 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>