简介
本文档提供关于文件相关接口介绍以及示例代码
文件上传
功能说明
该上传方法内部会自动进行快速上传、简单上传、分块上传的逻辑,生成的 task 可以供外部进行暂停、恢复、取消等。
示例代码
上传
try {let filePath = "本地文件路径";// 调用 SMHFileApis 的 uploadObject 方法进行文件上传let task = SMHFileApis.uploadObject({spaceId: "spaceId",libraryId: "libraryId",body: filePath, // 本地路径uploadPath: `smh/test.jpg`, // 目标路径});task.onStateChange = (state: SMHTransferState) => {// 任务状态回调}task.confirmKeyInitCallback = (confimKey: string) => {// 上传返回 confirmKey 回调。用于断点续传}task.onProgress = (progress) => {// 进度回调}task.onFinish = (result?: object, error?: SMHError) => {// 完成回调}// 启动任务task.start();//其他方法//task.pause() 暂停任务//task.cancel() 取消任务//task.resume() 重新启动任务,与 pause 配合使用}catch (e) {// 异常处理}
断点续传
try {let filePath = "本地文件路径";// 调用 SMHFileApis 的 uploadObject 方法进行文件上传let task = SMHFileApis.uploadObject({spaceId: "spaceId",libraryId: "libraryId",body: filePath, // 本地路径uploadPath: `smh/test.jpg`, // 目标路径confirmKey:"confirmKey"// confirmKeyInitCallback 回调返回的 confirmKey。});task.onStateChange = (state: SMHTransferState) => {// 任务状态回调}task.confirmKeyInitCallback = (confimKey: string) => {// 上传返回 confirmKey 回调。用于断点续传}task.onProgress = (progress) => {// 进度回调}task.onFinish = (result?: object, error?: SMHError) => {// 完成回调}// 启动任务task.start();//其他方法//task.pause() 暂停任务//task.cancel() 取消任务//task.resume() 重新启动任务,与 pause 配合使用}catch (e) {// 异常处理}
参数说明
请求参数 | 描述 | 类型 | 是否必选 |
libraryId | String | 是 | |
spaceId | String | 否 | |
body | 待上传的文件,格式为本地文件路径或者 ArrayBuffer | String/ArrayBuffer | 是 |
uploadPath | 目标路径,例如 foo/bar/file.docx | String | 是 |
confirmKey | 确认参数,指定为开始上传文件时响应体中的 confirmKey 字段的值,用于续传 | String | 否 |
simpleUploadLimit | 简单上传阈值 默认1m。小于1m则使用简单上传,否则使用分块上传 | Number | 否 |
sliceLength | 分块大小:默认1m | Number | 否 |
conflictResolutionStrategy | 文件名冲突时的处理方式: ask:冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码 rename:冲突时自动重命名文件 overwrite:如果冲突目标为目录时返回 HTTP 409 Conflict 及SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件 | SMHConflictResolutionStrategy | 否 |
customHeader | 自定义请求头 | Map | 否 |
trafficLimit | 单链接上传限速,范围100KB/s-100MB/s,单位 B | Number | 否 |
withInode | 上传完是否返回 inode,即文件目录 ID | Bool | 否 |
URL 上传
功能说明
该上传方法内部会自动进行简单上传、分块上传的逻辑,生成的 task 可以供外部进行暂停、恢复、取消等。
示例代码
上传
try {// 第三方 urllet sourceUrl = "https://xxxxxxx.com/file";// 第三方 url 需要的 headerlet sourceHeaders = new Map<string, string>();sourceHeaders.set('testkey', 'testvalue');// 调用 SMHFileApis 的 uploadUrlObject 方法进行 url 上传let task = SMHFileApis.uploadUrlObject({spaceId: "spaceId",libraryId: "libraryId",sourceUrl: sourceUrl,sourceHeaders: sourceHeaders,uploadPath: `smh/test.jpg`, // 目标路径});task.onStateChange = (state: SMHTransferState) => {// 任务状态回调}task.confirmKeyInitCallback = (confimKey: string) => {// 上传返回 confirmKey 回调。用于断点续传}task.onProgress = (progress) => {// 进度回调}task.onFinish = (result?: object, error?: SMHError) => {// 完成回调}// 启动任务task.start();//其他方法//task.pause() 暂停任务//task.cancel() 取消任务//task.resume() 重新启动任务,与 pause 配合使用}catch (e) {// 异常处理}
断点续传
try {// 第三方 urllet sourceUrl = "https://xxxxxxx.com/file";// 第三方 url 需要的 headerlet sourceHeaders = new Map<string, string>();// 调用 SMHFileApis 的 uploadUrlObject 方法进行 url 上传let task = SMHFileApis.uploadUrlObject({spaceId: "spaceId",libraryId: "libraryId",sourceUrl: sourceUrl,sourceHeaders: sourceHeaders,uploadPath: `smh/test.jpg`, // 目标路径confirmKey: "confirmKey"// confirmKeyInitCallback 回调返回的 confirmKey。});task.onStateChange = (state: SMHTransferState) => {// 任务状态回调}task.confirmKeyInitCallback = (confimKey: string) => {// 上传返回 confirmKey 回调。用于断点续传}task.onProgress = (progress) => {// 进度回调}task.onFinish = (result?: object, error?: SMHError) => {// 完成回调}// 启动任务task.start();//其他方法//task.pause() 暂停任务//task.cancel() 取消任务//task.resume() 重新启动任务,与 pause 配合使用}catch (e) {// 异常处理}
参数说明
请求参数 | 描述 | 类型 | 是否必选 |
libraryId | String | 是 | |
spaceId | String | 否 | |
sourceUrl | 第三方文件 URL | String | 是 |
sourceHeaders | 访问第三方 URL 时附加的请求头(如鉴权 Token 等) | Map<string, string> | 否 |
uploadPath | 目标路径,例如 foo/bar/file.docx | String | 是 |
confirmKey | 确认参数,指定为开始上传文件时响应体中的 confirmKey 字段的值,用于续传 | String | 否 |
simpleUploadLimit | 简单上传阈值,默认1m。小于1m则使用简单上传,否则使用分块上传 | Number | 否 |
sliceLength | 分块大小:默认1m | Number | 否 |
conflictResolutionStrategy | 文件名冲突时的处理方式: ask:冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码 rename:冲突时自动重命名文件 overwrite:如果冲突目标为目录时返回 HTTP 409 Conflict 及SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件 | SMHConflictResolutionStrategy | 否 |
customHeader | 自定义请求头 | Map | 否 |
trafficLimit | 单链接上传限速,范围100KB/s-100MB/s,单位 B | Number | 否 |
withInode | 上传完是否返回 inode,即文件目录 ID | Bool | 否 |
说明:
第三方 URL 支持分片上传和简单上传。当 URL 支持 range 时会执行分片上传,其余情况执行简单上传(不支持断点续传功能)。
第三方 URL 在简单上传的情况下仅支持小于等于5GB的文件进行上传,当您上传大于5GB的文件时会抛出错误码:FILE_TOO_LARGE(提示上传的文件超过限制),您可尝试将文件下载到本地之后在重新调用上传接口进行上传。
文件下载
功能说明
该下载方法内部会自动进行下载到本地以及续传的逻辑,生成的 task 可以供外部进行暂停、恢复、取消等。
说明:
下载接口默认支持断点续传,确保写入本地路径不变即可。
示例代码
try {// 调用 SMHFileApis 的 downloadObject 方法进行文件下载let task = SMHFileApis.downloadObject({spaceId: "spaceId",libraryId: "libraryId",filePath: `smh/test.jpg`,// 远端路径savePath: "本地路径" // 本地路径})task.onStateChange = (state: SMHTransferState) => {// 任务状态回调}task.onProgress = (progress: HttpProgress) => {// 进度回调}task.onFinish = (result?: object, error?: SMHError) => {// 完成回调}// 启动任务task.start();//其他方法//task.pause() 暂停任务//task.cancel() 取消任务//task.resume() 重新启动任务,与 pause 配合使用} catch (e) {// 异常处理}
参数说明
获取照片/视频封面缩略图
功能说明
用于获取照片/视频封面缩略图。
示例代码
try {let result = await SMHFileApis.preview({libraryId: "libraryId",spaceId: "spaceId",filePath: "foo/bar/image.jpg"})} catch (e) {// 异常处理}
参数说明
请求参数 | 描述 | 类型 | 是否必选 |
libraryId | String | 是 | |
spaceId | String | 否 | |
filePath | 云端目标路径,例如 foo/bar/image.jpg | String | 是 |
size | 缩放大小 | String | 否 |
scale | 等比例缩放百分比,不传 Size 时生效 | String | 否 |
widthSize | 缩放宽度,不传高度时,高度按等比例缩放,不传 Size 和 Scale 时生效 | String | 否 |
heightSize | 缩放高度,不传宽度时,宽度按等比例缩放,不传 Size 和 Scale 时生效 | String | 否 |
frameNumber | 帧数,针对 gif 的降帧处理 | String | 否 |
获取文件下载链接和信息
功能说明
用于获取文件下载链接和信息。
示例代码
try {let result =await SMHFileApis.downloadInfo({libraryId: "libraryId",spaceId: "spaceId",filePath: "foo/bar/file.docx"})} catch (e) {// 异常处理}
参数说明
请求参数 | 描述 | 类型 | 是否必选 |
libraryId | String | 是 | |
spaceId | String | 否 | |
filePath | 云端目标路径,例如 foo/bar/file.docx | String | 是 |
historyId | 历史版本 ID,用于获取不同版本的文件内容 | String | 否 |
trafficLimit | 单链接下载限速,范围 100KB/s-100MB/s,单位 B | Number | 否 |
contentDisposition | 用于设置 Content-Disposition 响应头,支持 inline 或者 attachment | SMHContentDisposition | 否 |
purpose | 用途,可以设置为 download 或者 preview,用于决定是否将该文件加入最近使用文件列表中,如果设置为 preview,则会将该文件加入最近使用文件列表中,否则不会加入 | SMHPurpose | 否 |
pre_check | 是否只用于校验文件是否可预览和下载,设置该参数后返回结果中不包含 cosUrl | Bool | 否 |
删除文件
功能说明
用于删除文件。
示例代码
try {let result = await SMHFileApis.deleteFile({libraryId: "TestLibraryId",spaceId: "TestSpaceId",filePath: "foo/bar/file.docx",permanent: true});} catch (e) {// 异常处理}
参数说明
复制文件
功能说明
用于复制文件。
示例代码
try {let result = await SMHFileApis.copyFile({libraryId: "libraryId",spaceId: "spaceId",filePath: "foo/bar/file_new.docx",copyFrom: "foo/bar/file.docx"})} catch (e) {// 异常处理}
参数说明
请求参数 | 描述 | 类型 | 是否必选 |
libraryId | String | 是 | |
spaceId | String | 否 | |
filePath | 云端目标路径,例如 foo/bar/file_new.docx | String | 是 |
copyFrom | 被复制的源文件云端路径,例如 foo/bar/file.docx | String | 是 |
conflictResolutionStrategy | 文件名冲突时的处理方式,默认为 rename ask: 冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码 rename: 冲突时自动重命名文件 overwrite: 如果冲突目标为目录时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件 | SMHConflictResolutionStrategy | 否 |
重命名或移动文件
功能说明
用于重命名或移动文件。
示例代码
try {let result = await SMHFileApis.moveFile({libraryId: "libraryId",spaceId: "spaceId",filePath: "foo/bar/file_new.docx",from: "foo/bar/file.docx"})} catch (e) {// 异常处理}
参数说明
请求参数 | 描述 | 类型 | 是否必选 |
libraryId | String | 是 | |
spaceId | String | 否 | |
filePath | 云端目标路径,例如 foo/bar/file_new.docx | String | 是 |
from | 被移动的源文件云端路径,例如 foo/bar/file.docx | String | 是 |
conflictResolutionStrategy | 文件名冲突时的处理方式,默认为 rename ask: 冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码 rename: 冲突时自动重命名文件 overwrite: 如果冲突目标为目录时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件 | SMHConflictResolutionStrategy | 否 |
更新文件的标签(Labels)或分类(Category)
功能说明
用于更新文件的标签(Labels)或分类(Category)。
示例代码
try {let result = await SMHFileApis.updateTagAndCategory({libraryId: "libraryId",spaceId: "spaceId",filePath: "foo/bar/file.jpg",labels: ["大象","动物","亚洲象"],category: "image",localCreationTime: "2022-07-26T02:58:09Z",localModificationTime: "2022-07-26T02:58:09Z",})} catch (e) {// 异常处理}
参数说明
请求参数 | 描述 | 类型 | 是否必选 |
libraryId | String | 是 | |
spaceId | String | 否 | |
filePath | 云端目标路径,例如 foo/bar/file.docx | String | 是 |
labels | 文件标签列表 | String 数组 | 否 |
category | 文件自定义的分类 | String | 否 |
localCreationTime | 文件对应的本地创建时间 | String | 否 |
localModificationTime | 文件对应的本地修改时间 | String | 否 |
查看最近使用文件列表
功能说明
用于查看最近使用文件列表。
示例代码
try {let result = await SMHFileApis.recentlyUseFile({libraryId: "libraryId",spaceId: "spaceId",filterActionBy: SMHFilterAction.preview,withPath: true});}catch (e) {// 异常处理}
参数说明
请求参数 | 描述 | 类型 | 是否必选 |
libraryId | String | 是 | |
spaceId | String | 否 | |
marker | 用于顺序列出分页的标识,不传默认第一页 | String | 否 |
limit | 用于顺序列出分页时本地列出的项目数限制,可选参数,不传则默认20 | String | 否 |
filterActionBy | 筛选操作方式,不传返回全部,preview 只返回预览操作,modify 返回编辑操作 | SMHFilterAction | 否 |
type | 筛选文件类型,当前支持的类型包括: all: 搜索所有文件,当不传 type 或传空时默认为 all document: 搜索所有文档,文档类型为:['pdf', 'powerpoint', 'excel', 'word','text'] pdf: 仅搜索 PDF 文档,对应的文件扩展名为 .pdf powerpoint: 仅搜索演示文稿,如 .ppt、.pptx、.pot、.potx 等 excel: 仅搜索表格文件,如 .xls、.xlsx、.ett、.xltx、.csv 等 word: 仅搜索文档,如 .doc、.docx、.dot、.wps、.wpt 等 text: 仅搜索纯文本,如 .txt、.asp、.htm 等 doc、xls 或 ppt: 仅搜索 Word、Excel 或 Powerpoint 类型文档,对应的文件扩展名为 .doc(x)、.xls(x) 或 .ppt(x) 字符串数组: 可以是文档后缀数组,如 ['.ppt', '.doc', '.excel']等;也可以是上述筛选类型数组,如 ['pdf', 'powerpoint', 'word'] 等 | SMHFileInfoType 数组 | 否 |
withPath | 是否返回文件路径,true|false,默认为 false,可选参数 | Bool | 否 |
根据文件 ID 查询文件信息
功能说明
用于根据文件 ID 查询文件信息。
示例代码
try {let result = await SMHFileApis.getFileInfoByInode({libraryId: "libraryId",spaceId: "spaceId",inode: "inode"})} catch (e) {// 异常处理}
参数说明
检查文件状态
功能说明
用于检查文件状态。
示例代码
try {let result = await SMHFileApis.headFile({libraryId: "libraryId",spaceId: "spaceId",filePath: "foo/bar/file.docx"});} catch (e) {// 异常处理}
参数说明
获取 HTML 格式文档预览
功能说明
用于获取 HTML 格式文档预览。
示例代码
try {let result = await SMHFileApis.previewHtml({libraryId: "libraryId",spaceId: "spaceId",filePath: "foo/bar/file.docx"})} catch (e) {// 异常处理}