对象存储
视频服务与安全产品捉虫活动邀您参加！> HOT
文档中心>对象存储>SDK 文档>鸿蒙(Harmony) SDK>对象操作>上传对象

上传对象

最近更新时间：2024-11-06 09:45:32

我的收藏

本页目录：

简介

本文档提供关于对象的高级上传、简单上传、分块上传等操作相关的 API 概览以及 SDK 示例代码。
简单操作
API
操作名
操作描述
简单上传对象
上传一个对象至存储桶
分块操作
API
操作名
操作描述
查询分块上传
查询正在进行中的分块上传信息
初始化分块上传
初始化分块上传任务
上传分块
分块上传对象
查询已上传块
查询特定分块上传操作中的已上传的块
完成分块上传
完成整个文件的分块上传
终止分块上传
终止一个分块上传操作并删除已上传的块

高级接口（推荐）

上传对象

高级接口封装了简单上传、分块上传接口，根据文件大小智能的选择上传方式，同时支持续传功能。

授权说明

在您进行 授权策略 时，action 请参考如下示例。
{
  "version": "2.0",
  "statement": [
    {
      "action": [
                //head操作 
                "name/cos:HeadObject",
                //简单上传操作 
                "name/cos:PutObject",
                //分块上传：初始化分块操作 
                "name/cos:InitiateMultipartUpload",
                //分块上传：List 进行中的分块上传
                "name/cos:ListMultipartUploads",
                //分块上传：List 已上传分块操作 
                "name/cos:ListParts",
                //分块上传：上传分块操作 
                "name/cos:UploadPart",
                //分块上传：完成所有分块上传操作 
                "name/cos:CompleteMultipartUpload",
                //取消分块上传操作 
                "name/cos:AbortMultipartUpload"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}
对象存储的更多 action，请参见 支持 CAM 的业务接口。

示例代码一: 上传本地文件

// 实例化 PutObjectRequest，设置存储桶名、目标路径，本地文件路径。
// 存储桶名称：由BucketName-Appid 组成，可以在COS控制台查看 https://console.cloud.tencent.com/cos5/bucket
// 上传目标路径：是对象在 COS 上的完整路径，如果带目录的话，格式为 "video/xxx/movie.mp4"
// 本地文件：文件路径。
let putRequest = new PutObjectRequest("存储桶名称", "上传目标路径", "本地文件");

// 使用 CosXmlBaseService 服务实例调用 upload 方法，获取当前上传任务 task；CosXmlBaseService具体使用方法，请参考 CosXmlBaseService。
let task:UploadTask = CosXmlBaseService.default().upload(putReqeust);

// 设置initCallBack ，获取分块上传 uploadId （简单上传不返回uploadId）
task.initCallBack = (uploadId:string)=>{
  this.uploadId = uploadId;
}
// 设置上传进度回调
task.onProgress = (progress: HttpProgress) => {
  complete：已发送的字节数
  target：本次上传要发送的总字节数（即一个文件大小）
};

// 设置完成回调
task.onResult = {
  // 成功回调
  onSuccess: (request, result) => {
      // request：当前请求request
      // resultL：响应结果
  },
  // 失败回调
  onFail: (request, error) => {
      // request：当前请求request
      // error：错误信息
  }
}
// 开始任务
task.start()
说明：
上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见生成预签名 URL文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

示例代码二: 上传二进制数据

// 实例化 PutObjectRequest，设置存储桶名、目标路径、文件内容ArrayBuffer。
// 上传 ArrayBuffer格式数据时，不支持暂停续传。
//
// 存储桶名称：由BucketName-Appid 组成，可以在COS控制台查看 https://console.cloud.tencent.com/cos5/bucket
// 上传目标路径：是对象在 COS 上的完整路径，如果带目录的话，格式为 "video/xxx/movie.mp4"
// buffer：文件内容，类型为：ArrayBuffer 。
let buffer:ArrayBuffer = ;
let putRequest = new PutObjectRequest("存储桶名称", "上传目标路径", buffer);

// 使用 CosXmlBaseService 服务实例调用 upload 方法，获取当前上传任务 task；CosXmlBaseService具体使用方法，请参考 CosXmlBaseService。
let task:UploadTask = CosXmlBaseService.default().upload(putReqeust);

// 设置上传进度回调
task.onProgress = (progress: HttpProgress) => {
  complete：已发送的字节数
  target：本次上传要发送的总字节数（即一个文件大小）
};

// 设置完成回调
task.onResult = {
  // 成功回调
  onSuccess: (request, result) => {
      // request：当前请求request
      // resultL：响应结果
  },
  // 失败回调
  onFail: (request, error) => {
      // request：当前请求request
      // error：错误信息
  }
}
// 开始任务
task.start()
说明：
上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见生成预签名 URL文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

示例代码三: 上传暂停、继续与取消

对于上传任务，可以通过以下方式暂停：
// 暂停：暂停当前任务，不会清空已上传的文件。
task.pause();
暂停之后，可以通过以下方式续传：
1、调用 task.resume()。适用于 task 没有被销毁。
// 继续：重新启动暂停的任务。
task.resume();
2、使用 本地保存的 uploadId 续传。适用于 app 进程被杀掉，重启后需要继续上传（uploadId 需业务侧持久化保存本地）。
 // 实例化 PutObjectRequest，设置存储桶名、目标路径，本地文件。
 let putRequest = new PutObjectRequest("存储桶名称", "上传目标路径", "本地文件");
 // 使用 CosXmlBaseService 服务实例调用 upload 方法，获取当前上传任务 task；CosXmlBaseService具体使用方法，请参考 CosXmlBaseService。
 // uploadId：业务测保存的需要续传的上传任务 uploadId。从 task.initCallBack 回调中获取。
 let task:UploadTask = CosXmlBaseService.default().upload(putReqeust,uploadId);
 // 设置initCallBack ，获取分块上传 uploadId （简单上传不返回uploadId）
 task.initCallBack = (uploadId:string)=>{
   this.uploadId = uploadId;
 }
 // 设置上传进度回调
 task.onProgress = (progress: HttpProgress) => {
   complete：已发送的字节数
   target：本次上传要发送的总字节数（即一个文件大小）
 };
 // 设置完成回调
 task.onResult = {
   // 成功回调
   onSuccess: (request, result) => {
       // request：当前请求request
       // resultL：响应结果
   },
   // 失败回调
   onFail: (request, error) => {
       // request：当前请求request
       // error：错误信息
   }
 }
 task.start()
3、通过以下方式取消上传：
取消：取消当前上传任务，会删除已上传的临时文件。取消后，不在支持续传。
task.cancel();

示例代码四: 单独设置临时密钥

// 初始化putRequest;
let putRequest = new PutObjectRequest("存储桶名称", "上传目标路径", "本地文件");
let credential = new QCloudCredential();
credential.secretID = '';
credential.secretKey = '';
credential.token = '';
// 设置当前请求临时密钥信息。
putRequest.credential = credential;    
let task:UploadTask = CosXmlBaseService.default().upload(putReqeust);
task.initCallBack = (uploadId:string)=>{
   this.uploadId = uploadId;
}
// 设置上传进度回调
task.onProgress = (progress: HttpProgress) => {
   complete：已发送的字节数
   target：本次上传要发送的总字节数（即一个文件大小）
};
// 设置完成回调
task.onResult = {
   // 成功回调
   onSuccess: (request, result) => {
       // request：当前请求request
       // resultL：响应结果
   },
   // 失败回调
   onFail: (request, error) => {
       // request：当前请求request
       // error：错误信息
   }
}
task.start()

示例代码五: 批量上传

for (int i = 0; i<20; i++) {
    let putRequest = new PutObjectRequest("存储桶名称", "上传目标路径", "本地文件");
    let task:UploadTask = CosXmlBaseService.default().upload(putReqeust);
    task.initCallBack = (uploadId:string)=>{
      this.uploadId = uploadId;
    }
    // 设置上传进度回调
    task.onProgress = (progress: HttpProgress) => {
      complete：已发送的字节数
      target：本次上传要发送的总字节数（即一个文件大小）
    };
    // 设置完成回调
    task.onResult = {
      // 成功回调
      onSuccess: (request, result) => {
          // request：当前请求request
          // resultL：响应结果
      },
      // 失败回调
      onFail: (request, error) => {
          // request：当前请求request
          // error：错误信息
      }
    }
    task.start()
}

示例代码六: 自定义简单上传与分块上传的阈值


    let putRequest = new PutObjectRequest("存储桶名称", "上传目标路径", "本地文件");

    // 初始化 TransferConfig；
    let config = new TransferConfig();
    // 设置分块阈值为：2M。
    config.simpleUploadLimit = 2 * 1024 * 1024;
    // 调用 upload 方法，并传入 config;
    let task:UploadTask = CosXmlBaseService.default().upload(putReqeust,undefined,config);
    task.initCallBack = (uploadId:string)=>{
      this.uploadId = uploadId;
    }
    // 设置上传进度回调
    task.onProgress = (progress: HttpProgress) => {
      complete：已发送的字节数
      target：本次上传要发送的总字节数（即一个文件大小）
    };
    // 设置完成回调
    task.onResult = {
      // 成功回调
      onSuccess: (request, result) => {
          // request：当前请求request
          // resultL：响应结果
      },
      // 失败回调
      onFail: (request, error) => {
          // request：当前请求request
          // error：错误信息
      }
    }
    task.start()

示例代码七: 自定义分块大小


    let putRequest = new PutObjectRequest("存储桶名称", "上传目标路径", "本地文件");

    // 初始化 TransferConfig；
    let config = new TransferConfig();
    // 设置分块大小为：1M。
    config.sliceLength = 1 * 1024 * 1024;
    // 调用 upload 方法，并传入 config;
    let task:UploadTask = CosXmlBaseService.default().upload(putReqeust,undefined,config);
    task.initCallBack = (uploadId:string)=>{
      this.uploadId = uploadId;
    }
    // 设置上传进度回调
    task.onProgress = (progress: HttpProgress) => {
      complete：已发送的字节数
      target：本次上传要发送的总字节数（即一个文件大小）
    };
    // 设置完成回调
    task.onResult = {
      // 成功回调
      onSuccess: (request, result) => {
          // request：当前请求request
          // resultL：响应结果
      },
      // 失败回调
      onFail: (request, error) => {
          // request：当前请求request
          // error：错误信息
      }
    }
    task.start()

示例代码八: 上传时限速

// 初始化putRequest;
let putRequest = new PutObjectRequest("存储桶名称", "上传目标路径", "本地文件");
// 限速值设置范围为819200 - 838860800，即800Kb/s - 800Mb/s
putRequest.addHeader('x-cos-traffic-limit','819200')
let task:UploadTask = CosXmlBaseService.default().upload(putReqeust);
task.initCallBack = (uploadId:string)=>{
   this.uploadId = uploadId;
}
// 设置上传进度回调
task.onProgress = (progress: HttpProgress) => {
   complete：已发送的字节数
   target：本次上传要发送的总字节数（即一个文件大小）
};
// 设置完成回调
task.onResult = {
   // 成功回调
   onSuccess: (request, result) => {
       // request：当前请求request
       // resultL：响应结果
   },
   // 失败回调
   onFail: (request, error) => {
       // request：当前请求request
       // error：错误信息
   }
}
task.start()



简单操作

简单上传对象

功能说明

PUT Object 接口可以上传一个对象至指定存储桶中，该操作需要请求者对存储桶有 WRITE 权限。最大支持上传不超过5GB的对象，5GB以上对象请使用 分块上传 或 高级接口 上传。
注意：
Key（上传目标路径）不能以/结尾，否则会被识别为文件夹。

示例代码

// 初始化putRequest;
let putRequest = new PutObjectRequest("存储桶名称", "上传目标路径", "本地文件");
// 设置进度回调
request.onProgress = (progress: HttpProgress) => {
   complete：已发送的字节数
   target：本次上传要发送的总字节数（即一个文件大小）
};
try {
  let result:PutObjectResult = await CosXmlBaseService.default().putObject(request);
} catch (e) {
}
说明：
上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见生成预签名 URL文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

分块操作

关于分块上传的更多说明请参见 分块上传。分块上传对象的操作流程如下。

分块上传流程介绍

分块上传的流程

1. 初始化分块上传（Initiate Multipart Upload），得到 UploadId。
2. 使用 UploadId 上传分块（Upload Part）。
3. 完成分块上传（Complete Multipart Upload）。

分块继续上传的流程

1. 使用 UploadId 列出已上传的分块（List Parts）。
2. 使用 UploadId 上传剩余的分块（Upload Part）。
3. 完成分块上传（Complete Multipart Upload）。
注意：
除了最后一块 Part，其他 Part 的大小不能小于1MB，否则会导致调用 Complete Multipart Upload 接口失败。
要上传的文件切分成 Part 之后，文件顺序是通过上传过程中指定的 partNumber 来确定的，实际执行中并没有顺序要求，因此可以实现并发上传。
具体的并发个数并不是越多速度越快，要结合用户自身的网络情况和设备负载综合考虑。网络情况较好时，建议增大分片大小。反之，减小分片大小。
默认情况下，已经上传但还没有调用 CompleteMultipartUpload 的 Part 是不会被自动回收的，并且会占用存储空间进而产生存储费用。因此如果要终止上传并删除占用的空间请调用 AbortMultipartUpload。

初始化分块上传

功能说明

初始化 Multipart Upload 上传操作，获取对应的 uploadId（Initiate Multipart Upload）。

示例代码

let request = new InitMultipartUploadRequest("存储桶名称", "上传目标路径");
try {
  let result:InitMultipartUploadResult = await CosXmlBaseService.default().initMultipartUpload(request);
} catch (e) {
}

上传分块

功能说明

分块上传对象（Upload Part）。

示例代码

// 实例化分块信息，每个分块长度、当前分块偏移量、本地文件路径。
let body = new FilePartInfo('length','offset','本地路径');
// partNumber 当前分块下标，从1开始。
let request = new UploadPartRequest("存储桶名称","上传目标路径",(body.index).toString(),body);
try {
  request.onProgress = (progress) => {
    // 进度回调    
  };
  request.onSuccess = (response) => {
    // 分块上传成功  
    let headers = response!.headers;
    if (headers) {
      // 上传成功 将 etag 和 index进行保存。
      // 所有分块上传完后，使用该信息调用完成上传接口。
      let etag = headers[HttpHeader.ETAG];
      let info = new CompleteMultipartUploadPart(parseInt((body.index + 1).toString()),etag);
      this.uploadedParts.add(info);
    }
  };
  request.onFailure = (err: Error) => {
    // 分块上传失败
  };
  CosXmlBaseService.default().partUpload(request);
} catch (e) {
}

查询已上传的分块

功能说明

查询特定分块上传操作中的已上传的块（List Parts）。

示例代码

// 查询特定分块上传中的已上传的块的方法.
// 标识本次分块上传的uploadId
let request = new ListPartsRequest("存储桶名称","上传目标路径",uploadId);
try{
    result = await CosXmlBaseService.default().listParts(request);
}catch(e){
}

完成分块上传

功能说明

完成整个文件的分块上传（Complete Multipart Upload）。

示例代码

let request = new CompleteMultiUploadRequest("存储桶名称","上传目标路径",uploadId);
// 对所有分块信息进行排序。
this.uploadedParts.sort((obj1:CompleteMultipartUploadPart,obj2:CompleteMultipartUploadPart)=>{
  if (obj1.partNumber < obj2.partNumber) {
    return -1;
  }else{
    return 1;
  }
})


// 初始化 CompleteMultipartUpload；
let completeInput = new CompleteMultipartUpload();
completeInput.part = this.uploadedParts;
request.completeMultipartUpload = completeInput;
try {
  let result = await CosXmlBaseService.default().completeMultiUpload(request);
} catch (e) {
}

终止分块上传

功能说明

终止一个分块上传操作并删除已上传的块（Abort Multipart Upload）。

示例代码

// 舍弃一个分块上传且删除已上传的分片块的方法.
let request = new AbortMultiUploadRequest("存储桶名称","上传目标路径",uploadId);
try {
  await CosXmlBaseService.default().abortMultiUpload(request);
} catch (e) {
  this.onFail(this.request,e);
}

中国站
文档反馈
文档活动
message-icon联系我们
目录