金山云-文档中心-高级上传

对象存储(KS3)

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

SDK

JavaScript

上传文件（JavaScript）

高级上传（JavaScript）

最近更新时间：2025-04-29 14:35:47

uploadFile高级上传

高级上传会自动根据文件大小选择采用简单上传还是分块上传，该方法无需手动构造上传过程，并且在上传过程中支持主动暂停、重新上传、续传等功能。上传文件时推荐使用高级上传方式。

使用示例

ks3.uploadFile({
    bucket: 'bucket-name',     // 存储桶，非必填
    region: 'beijing',     // 存储桶所在地域，例如beijing，非必填
    key: '1.jpg',     // 桶里的对象键（例如test.txt），必填
    sliceSize: 1024 * 1024 * 5,     // 触发分块上传的阈值，默认超过10MB使用分块上传， 非必填
    body: 'this is content' ,    //上传的文件内容，可选Stream/Buffer/String，必填
    encryption: true,     //是否使用服务端加密，默认是false，非必填
    storageClass: '',    // 上传Object的存储类型，可选STANDARD/STANDARD_IA/ARCHIVE，非必填
    onProgress: function (progressData) { 
        console.log(JSON.stringify(progressData));
    },    //上传过程中的进度回调，非必填
    headers:{},    // 自定义Header信息，非必填
    acl: 'public-read',     //默认值private，文件预设ACL（private/public-read），非必填
    onTaskReady: function(taskId) {
     // taskId可用来取消上传ks3.cancelTask(taskId)、停止上传ks3.pauseTask(taskId)、重新上传ks3.restartTask(taskId)
      console.log(taskId);
    },   //非必填
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名	参数描述	类型	是否必填
bucket	桶名称，若初始化的config配置参数填写Bucket，此处可忽略不填写；若此处填写，则以此处填写的Bucket为主	String	否
region	Region名称，若初始化的config配置参数填写Region，此处可忽略不填写；若此处填写，则以此处填写的Region为主	String	否
key	对象的Key	String	是
acl	文件预设ACL（private/public-read）默认值：private	String	否
body	上传的文件	Stream/Buffer/String	是
encryption	是否使用服务端加密文件	Boolean	否
storageClass	文件的存储类型，上传文件时如果不指定存储类型，默认与桶的存储类型保持一致	String	否
sliceSize	触发分块上传的阈值，默认超过10MB时使用分块上传	Number	否
headers	自定义Header信息	Object	否
onProgress	上传文件的进度回调函数，回调参数为一个progressData： loaded：已经上传的文件大小（Byte） total：整个文件大小 speed：上传速度，字节/秒（Bytes/s） percent：上传进度百分比	Function	否
onTaskReady	上传任务创建时的回调函数，每个上传任务都存在一个唯一的taskId，可以通过该taskId进行中断、暂停、重试任务等操作	Function	否

putUploadFile简单上传

putUploadFile简单上传在putObject简单上传的基础上，增加了中断上传的能力，客户可以通过任务Id中断上传过程。

使用示例

ks3.putUploadFile({
    bucket: 'bucket-name',     // 存储桶
    region: 'beijing',      // 存储桶所在地域，例如beijing
    key: '1.jpg',     // 桶里的对象键（例如 test.txt），必填
    body: 'this is content' ,    //上传的文件内容，可选Stream/Buffer/String，必填
    onTaskReady: function(taskId) {
     // taskId可用来取消上传ks3.cancelTask(taskId)、停止上传ks3.pauseTask(taskId)、重新上传ks3.restartTask(taskId)
      console.log(taskId);
    },
    onProgress: function (progressData) { 
      console.log(JSON.stringify(progressData));
    },    // 上传过程中的进度回调，非必填
    headers:{},    // 自定义Header信息，非必填
    acl: 'public-read',     // 默认值private，文件预设ACL，可选private/public-read
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名	参数描述	类型	是否必填
bucket	桶名称，若初始化的config配置参数填写Bucket，此处可忽略不填写；若此处填写，则以此处填写的Bucket为主	String	否
region	Region名称，若初始化的config配置参数填写Region，此处可忽略不填写；若此处填写，则以此处填写的Region为主	String	否
key	对象Key	String	是
acl	文件预设ACL（private/public-read）默认值：private	String	否
body	上传的文件	Stream/Buffer/String	是
encryption	是否使用服务端加密文件	Boolean	否
storageClass	文件的存储类型，上传文件时如果不指定存储类型，默认与桶的存储类型保持一致	String	否
headers	自定义Header信息	Object	否
onProgress	上传文件的进度回调函数，回调参数为一个progressData： loaded：已经上传的文件大小（Byte） total：整个文件大小 speed：上传速度，字节/秒（Bytes/s） percent：上传进度百分比	Function	否
onTaskReady	上传任务创建时的回调函数，每个上传任务都存在一个唯一的taskId，可以通过该taskId进行中断、暂停、重试任务等操作	Function	否

sliceUploadFile分块上传

sliceUploadFile分块上传在uploadPart的基础上，增加了大文件上传过程中支持续传和重试。

使用示例

ks3.sliceUploadFile({
    bucket: 'bucket-name',    // 存储桶，非必填
    region: 'beijing',    // 存储桶所在地域，例如beijing，非必填
    key: '1.jpg',    // 桶里的对象键（例如 test.txt），必填
    body: 'this is content',    //上传的文件内容，可选Stream/Buffer/String
    chunkSize: 10,    //分块上传的最小单位，默认5MB，会根据文件大小动态调整，非必填
    onTaskReady: function(taskId) {
     // taskId可用来取消上传ks3.cancelTask(taskId)、停止上传ks3.pauseTask(taskId)、重新上传ks3.restartTask(taskId)
      console.log(taskId);
    },   // 非必填
    onProgress: function (progressData) {    // 上传过程中的进度回调，非必填
        console.log(JSON.stringify(progressData));
    },   // 上传过程中的进度回调，非必需
    headers:{},    // 自定义Header信息，非必填
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名	参数描述	类型	是否必填
bucket	桶名称，若初始化的config配置参数填写Bucket，此处可忽略不填写；若此处填写，则以此处填写的Bucket为主	String	否
region	Region名称，若初始化的config配置参数填写Region，此处可忽略不填写；若此处填写，则以此处填写的Region为主	String	否
key	对象Key	String	是
acl	文件预设ACL（private/public-read）默认值：private	String	否
body	上传的文件	Stream/Buffer/String	是
encryption	是否使用服务端加密文件	Boolean	否
storageClass	文件的存储类型，上传文件时如果不指定存储类型，默认与桶的存储类型保持一致	String	否
chunkSize	分块上传的最小单位，默认5MB，会根据文件大小动态调整	Number	否
headers	自定义Header信息	Object	否
onProgress	上传文件的进度回调函数，回调参数为一个progressData： loaded：已经上传的文件大小（Byte） total：整个文件大小 speed：上传速度，字节/秒（Bytes/s） percent：上传进度百分比	Function	否
onTaskReady	上传任务创建时的回调函数，每个上传任务都存在一个唯一的taskId，可以通过该taskId进行中断、暂停、重试任务等操作	Function	否

taskId说明

生成规则

taskId是通过调用JS SDK的uploadFile、putUploadFile、sliceUploadFile发起的上传任务时自动生成的一个全局唯一标识符（UUID），格式类似："550e8400-e29b-41d4-a716-446655440000"。每个上传任务的 taskId 都是唯一的，避免冲突。

获取方式

通过onTaskReady返回值拿到taskId：

ks3.uploadFile({
    onTaskReady: function(taskId) {
        console.log(taskId); // 返回taskId
    }
},  function(err, data) {
    console.log(err || data);
});

通过taskId可执行的操作

取消上传

ks3.cancelTask(taskId);   // 终止任务

暂停上传

通过taskId暂停上传任务后，可通过ks3.restartTask(taskId) 重新上传。

ks3.pauseTask(taskId);   // 暂停任务

重新上传

通过ks3.restartTask(taskId) 重新上传，如果是分块上传任务将自动进行续传。

ks3.restartTask(taskId);   // 重新开始任务

上传队列

通过调用 KS3 JS SDK 的uploadFile、putUploadFile、sliceUploadFile方法发起的文件上传任务，都会自动加入全局任务队列管理。

每个上传任务在队列中都会分配一个唯一的taskId，用于标识和管理该任务。

获取上传任务队列

const taskList = ks3.getTaskList()   // 获取上传任务队列

返回值为数组格式，包含所有进行中和已完成的任务对象，每个任务对象包含以下关键属性：

名称	说明
taskId	唯一任务标识
bucket	桶名称
state	当前状态（waiting/uploading/paused/success/error/canceled）
region	Region名称
key	上传对象
filePath	上传对象在本地的具体路径
size	文件总大小
loaded	已上传字节数
speed	上传速度（字节/秒）
percent	上传进度百分比（0~100）
statusCode	请求的状态码
error	当任务状态为 “error” 时，该属性会返回具体的失败原因

监听任务列表

当任务队列中进度、状态、数量等发生变化时会触发list-update事件，例如：新增上传任务、任务状态变更、任务被移除队列等。

ks3.on('list-update', callback); // 监听任务列表变化

文档导读

上一篇：上传回调（JavaScript）

下一篇：追加上传（JavaScript）

纯净模式常规模式

纯净模式

点击可全屏预览文档内容