全部产品
阿里云办公

分片上传

更新时间:2018-08-15 21:52:32

分片上传(Multipart Upload)分为以下三个步骤:

  1. 初始化一个分片上传事件。
    调用ossClient.initiateMultipartUpload方法返回OSS创建的全局唯一的uploadId。

  2. 上传分片。
    调用ossClient.uploadPart方法上传分片数据。需要注意:

    • 对于同一个uploadId,分片号(partNumber)标识了该分片在整个文件内的相对位置。如果使用同一个分片号上传了新的数据,那么OSS上这个分片已有的数据将会被覆盖。
    • OSS将收到的分片数据的MD5值放在ETag头内返回给用户。
    • SDK自动设置Content-MD5。OSS计算上传数据的MD5值,并与SDK计算的MD5值比较,如果不一致则返回InvalidDigest错误码。
  3. 完成分片上传。
    所有分片上传完成后,调用ossClient.completeMultipartUpload方法将所有分片合并成完整的文件。

以下通过一个完整的示例对分片上传的流程进行逐步解析:

  1. // Endpoint以杭州为例,其它Region请按实际情况填写。
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. String bucketName = "<yourBucketName>";
  7. String objectName = "<yourObjectName>";
  8. // 创建OSSClient实例。
  9. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  10. /* 步骤1:初始化一个分片上传事件。
  11. */
  12. InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName);
  13. InitiateMultipartUploadResult result = ossClient.initiateMultipartUpload(request);
  14. // 返回uploadId,它是分片上传事件的唯一标识,您可以根据这个ID来发起相关的操作,如取消分片上传、查询分片上传等。
  15. String uploadId = result.getUploadId();
  16. /* 步骤2:上传分片。
  17. */
  18. // partETags是PartETag的集合。PartETag由分片的ETag和分片号组成。
  19. List<PartETag> partETags = new ArrayList<PartETag>();
  20. // 计算文件有多少个分片。
  21. final long partSize = 1 * 1024 * 1024L; // 1MB
  22. final File sampleFile = new File("<localFile>");
  23. long fileLength = sampleFile.length();
  24. int partCount = (int) (fileLength / partSize);
  25. if (fileLength % partSize != 0) {
  26. partCount++;
  27. }
  28. // 遍历分片上传。
  29. for (int i = 0; i < partCount; i++) {
  30. long startPos = i * partSize;
  31. long curPartSize = (i + 1 == partCount) ? (fileLength - startPos) : partSize;
  32. InputStream instream = new FileInputStream(sampleFile);
  33. // 跳过已经上传的分片。
  34. instream.skip(startPos);
  35. UploadPartRequest uploadPartRequest = new UploadPartRequest();
  36. uploadPartRequest.setBucketName(bucketName);
  37. uploadPartRequest.setKey(objectName);
  38. uploadPartRequest.setUploadId(uploadId);
  39. uploadPartRequest.setInputStream(instream);
  40. // 设置分片大小。除了最后一个分片没有大小限制,其他的分片最小为100KB。
  41. uploadPartRequest.setPartSize(curPartSize);
  42. // 设置分片号。每一个上传的分片都有一个分片号,取值范围是1~10000,如果超出这个范围,OSS将返回InvalidArgument的错误码。
  43. uploadPartRequest.setPartNumber( i + 1);
  44. // 每个分片不需要按顺序上传,甚至可以在不同客户端上传,OSS会按照分片号排序组成完整的文件。
  45. UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
  46. // 每次上传分片之后,OSS的返回结果会包含一个PartETag。PartETag将被保存到partETags中。
  47. partETags.add(uploadPartResult.getPartETag());
  48. }
  49. /* 步骤3:完成分片上传。
  50. */
  51. // 排序。partETags必须按分片号升序排列。
  52. Collections.sort(partETags, new Comparator<PartETag>() {
  53. public int compare(PartETag p1, PartETag p2) {
  54. return p1.getPartNumber() - p2.getPartNumber();
  55. }
  56. });
  57. // 在执行该操作时,需要提供所有有效的partETags。OSS收到提交的partETags后,会逐一验证每个分片的有效性。当所有的数据分片验证通过后,OSS将把这些分片组合成一个完整的文件。
  58. CompleteMultipartUploadRequest completeMultipartUploadRequest =
  59. new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);
  60. ossClient.completeMultipartUpload(completeMultipartUploadRequest);
  61. // 关闭OSSClient。
  62. ossClient.shutdown();

分片上传的完整代码请参见GitHub

取消分片上传事件

您可以调用ossClient.abortMultipartUpload方法来取消分片上传事件。当一个分片上传事件被取消后,无法再使用这个uploadId做任何操作,已经上传的分片数据会被删除。

以下代码用于取消分片上传事件:

  1. // Endpoint以杭州为例,其它Region请按实际情况填写。
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // 创建OSSClient实例。
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // 取消分片上传,其中uploadId来自于InitiateMultipartUpload。
  9. AbortMultipartUploadRequest abortMultipartUploadRequest =
  10. new AbortMultipartUploadRequest("<yourBucketName>", "<yourObjectName>", "<uploadId>");
  11. ossClient.abortMultipartUpload(abortMultipartUploadRequest);
  12. // 关闭OSSClient。
  13. ossClient.shutdown();

列举已上传的分片

调用ossClient.listParts方法列举出指定uploadId下所有已经上传成功的分片。

简单列举已上传的分片

以下代码用于简单列举已上传的分片:

  1. // Endpoint以杭州为例,其它Region请按实际情况填写。
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // 创建OSSClient实例。
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // 列举已上传的分片,其中uploadId来自于InitiateMultipartUpload返回的结果。
  9. ListPartsRequest listPartsRequest = new ListPartsRequest("<yourBucketName>", "<yourObjectName>", "<uploadId>");
  10. // 设置uploadId。
  11. //listPartsRequest.setUploadId(uploadId);
  12. // 设置分页时每一页中分片数量为100个。默认列举1000个分片。
  13. listPartsRequest.setMaxParts(100);
  14. // 指定List的起始位置。只有分片号大于该参数值的分片会被列出。
  15. listPartsRequest.setPartNumberMarker(2);
  16. PartListing partListing = ossClient.listParts(listPartsRequest);
  17. for (PartSummary part : partListing.getParts()) {
  18. // 获取分片号。
  19. part.getPartNumber();
  20. // 获取分片数据大小。
  21. part.getSize();
  22. // 获取分片的ETag。
  23. part.getETag();
  24. // 获取分片的最后修改时间。
  25. part.getLastModified();
  26. }
  27. // 关闭OSSClient。
  28. ossClient.shutdown();

列举所有已上传的分片

默认情况下,listParts只能一次列举1000个分片。当分片数量大于1000时,请使用以下代码列举所有已上传的分片。

  1. // Endpoint以杭州为例,其它Region请按实际情况填写。
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // 创建OSSClient实例。
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // 列举所有已上传的分片。
  9. PartListing partListing;
  10. ListPartsRequest listPartsRequest = new ListPartsRequest("<yourBucketName>", "<yourObjectName>", "<uploadId>");
  11. do {
  12. partListing = ossClient.listParts(listPartsRequest);
  13. for (PartSummary part : partListing.getParts()) {
  14. // 获取分片号。
  15. part.getPartNumber();
  16. // 获取分片数据大小。
  17. part.getSize();
  18. // 获取分片的ETag。
  19. part.getETag();
  20. // 获取分片的最后修改时间。
  21. part.getLastModified();
  22. }
  23. // 指定List的起始位置,只有分片号大于该参数值的分片会被列出。
  24. listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
  25. } while (partListing.isTruncated());
  26. // 关闭OSSClient。
  27. ossClient.shutdown()

分页列举所有已上传的分片

以下代码用于指定每页分片的数量,分页列举所有分片。

  1. // Endpoint以杭州为例,其它Region请按实际情况填写。
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // 创建OSSClient实例。
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // 分页列举已上传的分片。
  9. PartListing partListing;
  10. ListPartsRequest listPartsRequest = new ListPartsRequest("<yourBucketName>", "<yourObjectName>", "<uploadId>");
  11. // 设置分页时每一页100个分片。
  12. listPartsRequest.setMaxParts(100);
  13. do {
  14. partListing = ossClient.listParts(listPartsRequest);
  15. for (PartSummary part : partListing.getParts()) {
  16. // 获取分片号。
  17. part.getPartNumber();
  18. // 获取分片数据大小。
  19. part.getSize();
  20. // 获取分片的ETag。
  21. part.getETag();
  22. // 获取分片的最后修改时间。
  23. part.getLastModified();
  24. }
  25. listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
  26. } while (partListing.isTruncated());
  27. // 关闭OSSClient。
  28. ossClient.shutdown();

列举分片上传事件

调用ossClient.listMultipartUploads方法列举出所有执行中的分片上传事件,即已初始化但尚未完成或已取消的分片上传事件。可设置的参数如下:

参数 作用 如何设置
prefix 限定返回的文件名称必须以指定的prefix作为前缀。注意使用prefix查询时,返回的文件名称中仍会包含prefix。 ListMultipartUploadsRequest.setPrefix(String prefix)
delimiter 用于对文件名称进行分组的一个字符。所有名称包含指定的前缀且第一次出现delimiter字符之间的文件作为一组元素。 ListMultipartUploadsRequest.setDelimiter(String delimiter)
maxUploads 限定此次返回分片上传事件的最大数目,默认值和最大值均为1000。 ListMultipartUploadsRequest.setMaxUploads(Integer maxUploads)
keyMarker 所有文件名称的字母序大于keyMarker参数值的分片上传事件。可以与uploadIdMarker参数一同使用来指定返回结果的起始位置。 ListMultipartUploadsRequest.setKeyMarker(String keyMarker)
uploadIdMarker 与keyMarker参数一同使用来指定返回结果的起始位置。 如果未设置keyMarker参数,则此参数无效。如果设置了keyMarker参数,则查询结果中包含:
- 名称的字母序大于keyMarker参数值的所有文件。
- 文件名称等于keyMarker参数值且uploadId比uploadIdMarker参数值大的所有分片上传事件。
ListMultipartUploadsRequest.setUploadIdMarker(String uploadIdMarker)

简单列举分片上传事件

以下代码用于列举分片上传事件:

  1. // Endpoint以杭州为例,其它Region请按实际情况填写。
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. String bucketName = "<yourBucketName>";
  7. // 创建OSSClient实例。
  8. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  9. // 列举分片上传事件。默认列举1000个分片。
  10. ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
  11. MultipartUploadListing multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);
  12. for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
  13. // 获取uploadId。
  14. multipartUpload.getUploadId();
  15. // 获取Key。
  16. multipartUpload.getKey();
  17. // 获取分片上传的初始化时间。
  18. multipartUpload.getInitiated();
  19. }
  20. // 关闭OSSClient。
  21. ossClient.shutdown();

返回结果中isTruncated为false,返回nextKeyMarker和nextUploadIdMarker作为下次读取的起点。如果没有一次性获取所有的上传事件,可以采用分页列举的方式。

列举全部分片上传事件

默认情况下,listMultipartUploads 只能一次列举1000个分片。当分片数量大于1000时,请使用以下代码列举全部分片上传事件。

  1. // Endpoint以杭州为例,其它Region请按实际情况填写。
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. String bucketName = "<yourBucketName>";
  7. // 创建OSSClient实例。
  8. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  9. // 列举分片上传事件。
  10. MultipartUploadListing multipartUploadListing;
  11. ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
  12. do {
  13. multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);
  14. for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
  15. // 获取uploadId。
  16. multipartUpload.getUploadId();
  17. // 获取文件名称。
  18. multipartUpload.getKey();
  19. // 获取分片上传的初始化时间。
  20. multipartUpload.getInitiated();
  21. }
  22. listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());
  23. listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());
  24. } while (multipartUploadListing.isTruncated());
  25. // 关闭OSSClient。
  26. ossClient.shutdown();

分页列举全部上传事件

以下代码用于分页列举所有上传事件:

  1. // Endpoint以杭州为例,其它Region请按实际情况填写。
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. String bucketName = "<yourBucketName>";
  7. // 创建OSSClient实例。
  8. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  9. // 列举分片上传事件。
  10. MultipartUploadListing multipartUploadListing;
  11. ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
  12. // 设置每页列举的分片上传事件数目。
  13. listMultipartUploadsRequest.setMaxUploads(50);
  14. do {
  15. multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);
  16. for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
  17. // 获取uploadId。
  18. multipartUpload.getUploadId();
  19. // 获取Key。
  20. multipartUpload.getKey();
  21. // 获取分片上传的初始化时间。
  22. multipartUpload.getInitiated();
  23. }
  24. listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());
  25. listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());
  26. } while (multipartUploadListing.isTruncated());
  27. // 关闭OSSClient。
  28. ossClient.shutdown();