全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 智能硬件
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 更多
对象存储 OSS

上传文件

更新时间:2018-06-13 19:32:08

在OSS中,用户操作的基本数据单元是文件(Object)。OSS Java SDK提供了丰富的文件上传方式:

  • 简单上传。包括流式上传和文件上传。最大不能超过5GB。
  • 追加上传。最大不能超过5GB。
  • 断点续传上传。支持并发、断点续传、自定义分片大小。大文件上传推荐使用断点续传。最大不能超过48.8TB。
  • 分片上传。当文件较大时,请使用分片上传,最大不能超过48.8TB。

简单上传

流式上传和文件上传通称为简单上传。流式上传使用InputStream作为文件的数据源。文件上传使用本地文件作为OSS文件的数据源。简单上传的完整代码请参见GitHub

流式上传

使用ossClient.putObject上传数据流到OSS。

上传字符串

以下代码用于上传字符串:

  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. String content = "Hello OSS";
  10. ossClient.putObject("<yourBucketName>", "<yourObjectName>", new ByteArrayInputStream(content.getBytes()));
  11. // 关闭OSSClient。
  12. ossClient.shutdown();

上传Byte数组

以下代码用于上传Byte数组:

  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. // 上传Byte数组。
  9. byte[] content = "Hello OSS".getBytes();
  10. ossClient.putObject("<yourBucketName>", "<yourObjectName>", new ByteArrayInputStream(content));
  11. // 关闭OSSClient。
  12. 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. InputStream inputStream = new URL("https://www.aliyun.com/").openStream();
  10. ossClient.putObject("<yourBucketName>", "<yourObjectName>", inputStream);
  11. // 关闭OSSClient。
  12. ossClient.shutdown();

上传文件流

以下代码用于上传文件流:

  1. // Endpoint以杭州为例,其它Region请按实际情况填写。
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 云账号AccessKey有所有API访问权限,建议遵循阿里云安全最佳实践,创建并使用RAM子账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建。
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // 创建OSSClient实例。
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // 上传文件流。
  9. InputStream inputStream = new FileInputStream("<yourlocalFile>");
  10. ossClient.putObject("<yourBucketName>", "<yourObjectName>", inputStream);
  11. // 关闭OSSClient。
  12. 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. ossClient.putObject("<yourBucketName>", "<yourObjectName>", new File("<yourLocalFile>"));
  10. // 关闭OSSClient。
  11. ossClient.shutdown();

创建文件夹

OSS没有文件夹的概念,所有元素都以文件来存储。创建文件夹本质上来说是创建了一个大小为0并以“/”结尾的文件。控制台会对以“/”结尾的文件以文件夹的方式展示。文件夹可以被上传和下载。

以下代码用于创建文件夹:

  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. // 创建dir1/dir2/dir3/时,已默认为您创建好了dir1/、dir1/dir2/前两级目录。
  9. final String keySuffixWithSlash = "dir1/dir2/dir3/";
  10. ossClient.putObject("<yourBucketName>", keySuffixWithSlash, new ByteArrayInputStream(new byte[0]));
  11. // 关闭OSSClient。
  12. ossClient.shutdown();

关于OSS文件的更多操作,请参见管理文件

追加上传

追加类型的文件(Append Object)暂时不支持copyObject操作。

以下代码用于追加上传文件:

  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 content1 = "Hello OSS A \n";
  7. String content2 = "Hello OSS B \n";
  8. String content3 = "Hello OSS C \n";
  9. // 创建OSSClient实例。
  10. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  11. ObjectMetadata meta = new ObjectMetadata();
  12. // 指定上传的内容类型。
  13. meta.setContentType("text/plain");
  14. // 通过AppendObjectRequest设置多个参数。
  15. AppendObjectRequest appendObjectRequest = new AppendObjectRequest("<yourBucketName>", "<yourObjectName>", new ByteArrayInputStream(content1.getBytes()),meta);
  16. // 通过AppendObjectRequest设置单个参数。
  17. // 设置存储空间名称。
  18. //appendObjectRequest.setBucketName("<yourBucketName>");
  19. // 设置文件名称。
  20. //appendObjectRequest.setKey("<yourObjectName>");
  21. // 设置待追加的内容。有两种可选类型:InputStream类型和File类型。这里为InputStream类型。
  22. //appendObjectRequest.setInputStream(new ByteArrayInputStream(content1.getBytes()));
  23. // 设置待追加的内容。有两种可选类型:InputStream类型和File类型。这里为File类型。
  24. //appendObjectRequest.setFile(new File("<yourLocalFile>"));
  25. // 指定文件的元信息,第一次追加时有效。
  26. //appendObjectRequest.setMetadata(meta);
  27. // 第一次追加。
  28. // 设置文件的追加位置。
  29. appendObjectRequest.setPosition(0L);
  30. AppendObjectResult appendObjectResult = ossClient.appendObject(appendObjectRequest);
  31. // 文件的64位CRC值。此值根据ECMA-182标准计算得出。
  32. System.out.println(appendObjectResult.getObjectCRC());
  33. // 第二次追加。
  34. // nextPosition指明下一次请求中应当提供的Position,即文件当前的长度。
  35. appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
  36. appendObjectRequest.setInputStream(new ByteArrayInputStream(content2.getBytes()));
  37. appendObjectResult = ossClient.appendObject(appendObjectRequest);
  38. // 第三次追加。
  39. appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
  40. appendObjectRequest.setInputStream(new ByteArrayInputStream(content3.getBytes()));
  41. appendObjectResult = ossClient.appendObject(appendObjectRequest);
  42. // 关闭OSSClient。
  43. ossClient.shutdown();

追加上传详情请参见开发指南中的追加上传。追加上传的完整代码请参见GitHub

断点续传上传

断点续传上传将要上传的文件分成若干个分片(Part)分别上传,所有分片都上传完成后,将所有分片合并成完整的文件,完成整个文件的上传。

以下代码用于断点续传上传:

  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. ObjectMetadata meta = new ObjectMetadata();
  9. // 指定上传的内容类型。
  10. meta.setContentType("text/plain");
  11. // 通过UploadFileRequest设置多个参数。
  12. UploadFileRequest uploadFileRequest = new UploadFileRequest("<yourBucketName>","<yourObjectName>");
  13. // 通过UploadFileRequest设置单个参数。
  14. // 设置存储空间名称。
  15. //uploadFileRequest.setBucketName("yourucketname");
  16. // 设置文件名称。
  17. //uploadFileRequest.setKey("<yourObjectName>");
  18. // 指定上传的本地文件。
  19. uploadFileRequest.setUploadFile("<yourLocalFile>");
  20. // 指定上传并发线程数,默认为1。
  21. uploadFileRequest.setTaskNum(5);
  22. // 指定上传的分片大小,范围为100KB~5GB,默认为文件大小/10000。
  23. uploadFileRequest.setPartSize(1 * 1024 * 1024);
  24. // 开启断点续传,默认关闭。
  25. uploadFileRequest.setEnableCheckpoint(true);
  26. // 记录本地分片上传结果的文件。开启断点续传功能时需要设置此参数,上传过程中的进度信息会保存在该文件中,如果某一分片上传失败,再次上传时会根据文件中记录的点继续上传。上传完成后,该文件会被删除。默认与待上传的本地文件同目录,为uploadFile.ucp。
  27. uploadFileRequest.setCheckpointFile("<yourCheckpointFile>");
  28. // 文件的元数据。
  29. uploadFileRequest.setObjectMetadata(meta);
  30. // 设置上传成功回调,参数为Callback类型。
  31. uploadFileRequest.setCallback("<yourCallbackEvent>");
  32. // 断点续传上传。
  33. ossClient.uploadFile(uploadFileRequest);
  34. // 关闭OSSClient。
  35. ossClient.shutdown();

断点续传详情请参见开发指南中的断点续传

分片上传

分片上传(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的集合。partETags由分片的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参数,则OSS忽略uploadIdMarker参数。如果设置了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. // 获取Key。
  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();

Post上传

OSS Java SDK目前暂不支持Post上传文件。PostObject的示例详情请参见PostObjectSample。PutObject详情请参见PutObject。PostObject详情请参见Java模拟PostObject表单上传OSS

上传进度条

进度条用于指示上传或下载的进度。下面的代码以ossClient.putObject方法为例,介绍如何使用进度条。

  1. static class PutObjectProgressListener implements ProgressListener {
  2. private long bytesWritten = 0;
  3. private long totalBytes = -1;
  4. private boolean succeed = false;
  5. @Override
  6. public void progressChanged(ProgressEvent progressEvent) {
  7. long bytes = progressEvent.getBytes();
  8. ProgressEventType eventType = progressEvent.getEventType();
  9. switch (eventType) {
  10. case TRANSFER_STARTED_EVENT:
  11. System.out.println("Start to upload......");
  12. break;
  13. case REQUEST_CONTENT_LENGTH_EVENT:
  14. this.totalBytes = bytes;
  15. System.out.println(this.totalBytes + " bytes in total will be uploaded to OSS");
  16. break;z'z'z'za
  17. case REQUEST_BYTE_TRANSFER_EVENT:
  18. this.bytesWritten += bytes;
  19. if (this.totalBytes != -1) {
  20. int percent = (int)(this.bytesWritten * 100.0 / this.totalBytes);
  21. System.out.println(bytes + " bytes have been written at this time, upload progress: " + percent + "%(" + this.bytesWritten + "/" + this.totalBytes + ")");
  22. } else {
  23. System.out.println(bytes + " bytes have been written at this time, upload ratio: unknown" + "(" + this.bytesWritten + "/...)");
  24. }
  25. break;
  26. case TRANSFER_COMPLETED_EVENT:
  27. this.succeed = true;
  28. System.out.println("Succeed to upload, " + this.bytesWritten + " bytes have been transferred in total");
  29. break;
  30. case TRANSFER_FAILED_EVENT:
  31. System.out.println("Failed to upload, " + this.bytesWritten + " bytes have been transferred");
  32. break;
  33. default:
  34. break;
  35. }
  36. }
  37. public boolean isSucceed() {
  38. return succeed;
  39. }
  40. }
  41. public static void main(String[] args) {
  42. // Endpoint以杭州为例,其它Region请按实际情况填写。
  43. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  44. // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  45. String accessKeyId = "<yourAccessKeyId>";
  46. String accessKeySecret = "<yourAccessKeySecret>";
  47. String bucketName = "<yourBucketName>";
  48. String objectName = "<yourObjectName>";
  49. // 创建OSSClient实例。
  50. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  51. try {
  52. // 带进度条的上传。
  53. ossClient.putObject(new PutObjectRequest(bucketName, objectName, new FileInputStream("<yourLocalFile>")).
  54. <PutObjectRequest>withProgressListener(new PutObjectProgressListener()));
  55. } catch (Exception e) {
  56. e.printStackTrace();
  57. }
  58. // 关闭OSSClient。
  59. ossClient.shutdown();
  60. }

ossClient.putObject、ossClient.getObject和ossClient.uploadPart方法支持进度条功能。ossClient.uploadFile和ossClient.downloadFile方法不支持进度条功能。

上传进度条的完整代码请参见GitHub

上传回调(Callback)

以下代码用于上传回调:

  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. // 您的回调服务器地址,如http://oss-demo.aliyuncs.com或http://127.0.0.1:9090。
  9. String callbackUrl = "<yourCallbackServerUrl>";
  10. // 创建OSSClient实例。
  11. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  12. String content = "Hello OSS";
  13. PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, objectName,new ByteArrayInputStream(content.getBytes()));
  14. // 上传回调参数。
  15. Callback callback = new Callback();
  16. callback.setCallbackUrl(callbackUrl);
  17. // Endpoint以杭州为例,其它Region请按实际情况填写
  18. callback.setCallbackHost("oss-cn-hangzhou.aliyuncs.com");
  19. callback.setCallbackBody("{\\\"mimeType\\\":${mimeType},\\\"size\\\":${size}}");
  20. callback.setCallbackBodyType(CallbackBodyType.JSON);
  21. callback.addCallbackVar("x:var1", "value1");
  22. callback.addCallbackVar("x:var2", "value2");
  23. putObjectRequest.setCallback(callback);
  24. PutObjectResult putObjectResult = ossClient.putObject(putObjectRequest);
  25. // 读取上传回调返回的消息内容。
  26. byte[] buffer = new byte[1024];
  27. putObjectResult.getCallbackResponseBody().read(buffer);
  28. // 数据读取完成后,获取的流必须关闭,否则会造成连接泄漏,导致请求无连接可用,程序无法正常工作。
  29. putObjectResult.getCallbackResponseBody().close();
  30. // 关闭OSSClient。
  31. ossClient.shutdown();

上传回调详情请参见开发指南中的上传回调。上传回调的完整代码请参见GitHub

本文导读目录