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

管理文件

更新时间:2018-05-27 23:07:35

在OSS中,您可以通过一系列的接口管理存储空间(Bucket)下的文件(Object),比如 setObjectAcl、getObjectAcl、listObjects、deleteObject、copyObject、doesObjectExist等。

判断文件是否存在

以下代码用于判断指定存储空间下指定的文件是否存在:

  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. // Object是否存在。
  9. boolean found = ossClient.doesObjectExist("<yourBucketName>", "<yourObjectName>");
  10. System.out.println(found);
  11. // 关闭Client。
  12. ossClient.shutdown();

文件的访问权限

文件的访问权限(ACL)有以下四种:

权限 描述
Default(默认) Object默认遵循Bucket的访问权限。
Private(私有读写) Object是私有资源,即只有该Object的Owner拥有该Object的读写权限,其他的用户没有权限操作该Object。
PublicRead(公共读私有写) Object是公共读资源,即非Object Owner只有Object的读权限,而Object Owner拥有该Object的读写权限。
PublicReadWrite(公共读写) Object是公共读写资源,即所有用户拥有对该Object的读写权限。

Object的权限优先级高于Bucket的权限。例如Bucket的权限是私有读写的,而Object的访问权限是公共读写,则所有用户都拥有这个Object的访问权限,即使这个Bucket的权限是私有读写的。如果某个Object没有设置过访问权限,则默认遵循Bucket的访问权限。

设置文件的访问权限

您可以通过ossClient.setObjectAcl设置文件的访问权限。

权限 Java SDK对应值
私有读写 CannedAccessControlList.Private
公共读私有写 CannedAccessControlList.PublicRead
公共读写 CannedAccessControlList.PublicReadWrite

以下代码用于设置指定存储空间下指定文件的访问权限:

  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. // 设置Object权限。
  9. ossClient.setObjectAcl("<yourBucketName>", "<yourObjectName>", CannedAccessControlList.PublicRead);
  10. // 关闭Client。
  11. 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. //读取Object ACL。
  9. ObjectAcl objectAcl = ossClient.getObjectAcl("<yourBucketName>", "<yourObjectName>");
  10. System.out.println(objectAcl.getPermission().toString());
  11. // 关闭Client。
  12. ossClient.shutdown();

设置元信息

文件元信息(Object Meta)详情请参见文件元信息

设定HTTP Header

OSS允许用户自定义HTTP Header。

以下代码用于设置HTTP Header:

  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 content = "Hello OSS";
  7. // 创建上传Object的Metadata,ObjectMetadata提供常用的HTTP Header的设置信息。
  8. ObjectMetadata meta = new ObjectMetadata();
  9. String md5 = BinaryUtil.toBase64String(BinaryUtil.calculateMd5(content.getBytes()));
  10. // 指定上传MD5校验,指定了该参数后OSS会启用文件内容MD5校验,把您提供的MD5与文件的MD5比较,不一致会抛出错误。
  11. meta.setContentMD5(md5);
  12. // 指定上传的内容类型,指文件的MIME,用于定义文件的类型及网页编码,决定浏览器将以什么形式、什么编码读取文件。如果用户没有指定则根据Key或文件名的扩展名生成,如果没有扩展名则填默认值application/octet-stream。
  13. meta.setContentType("text/plain");
  14. // 设置内容被下载时的名称。Content-disposition是MIME协议的扩展,MIME协议指示MIME客户端如何显示附加的文件。
  15. meta.setContentDisposition("Download File Name");
  16. //设置上传文件的长度。如超过此长度,则会被截断,为设置的长度。如不足,则为上传文件的实际长度。
  17. meta.setContentLength(content.length());
  18. //设置内容被下载时网页的缓存行为。
  19. meta.setCacheControl("Download Action");
  20. //设置缓存过期时间,格式是格林威治时间(GMT)。
  21. meta.setExpirationTime(DateUtil.parseIso8601Date("2022-10-12T00:00:00.000Z"));
  22. //设置被下载时的内容编码格式。
  23. meta.setContentEncoding("utf-8");
  24. //设置Header。
  25. meta.setHeader("<yourHeader>", "<yourHeaderValue>");
  26. // 创建OSSClient实例。
  27. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  28. // 上传文件。
  29. ossClient.putObject("<yourBucketName>", "<yourObjectName>", new ByteArrayInputStream(content.getBytes()), meta);
  30. // 关闭Client。
  31. ossClient.shutdown();

HTTP Header请参见RFC2616

用户自定义元信息

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. String content = "Hello OSS";
  7. // 创建OSSClient实例。
  8. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  9. // 创建上传Object的Metadata。
  10. ObjectMetadata meta = new ObjectMetadata();
  11. // 设置自定义元信息property值为property-value。
  12. meta.addUserMetadata("property", "property-value");
  13. // 上传文件。
  14. ossClient.putObject("<yourBucketName>", "<yourObjectName>", new ByteArrayInputStream(content.getBytes()), meta);
  15. //获取文件的元信息。
  16. ossClient.getObjectMetadata("<yourBucketName>", "<yourObjectName>");
  17. // 关闭Client。
  18. ossClient.shutdown();

说明:

  • 下载文件时,文件的元信息也会同时下载。
  • 一个文件可以有多个元信息,总大小不能超过8KB。

获取文件元信息

获取文件元信息两种方法如下:

方法 描述 优势
ossClient.getSimplifiedObjectMeta 获取文件的ETag、Size(文件大小)、 LastModified(最后修改时间)。 更轻量、更快
ossClient.getObjectMetadata 获取文件的全部元信息。

以下代码用于获取文件元信息:

  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. SimplifiedObjectMeta objectMeta = ossClient.getSimplifiedObjectMeta("<yourBucketName>", "<yourObjectName>");
  10. System.out.println(objectMeta.getSize());
  11. System.out.println(objectMeta.getETag());
  12. System.out.println(objectMeta.getLastModified());
  13. // 获取文件的全部元信息。
  14. ObjectMetadata metadata = ossClient.getObjectMetadata("<yourBucketName>", "<yourObjectName>");
  15. System.out.println(metadata.getContentType());
  16. System.out.println(metadata.getLastModified());
  17. System.out.println(metadata.getExpirationTime());
  18. // 关闭Client。
  19. ossClient.shutdown();

列举存储空间下的文件

可以通过ossClient.listObjects列出存储空间下的文件。listObjects有以下三类参数格式:

  • ObjectListing listObjects(String bucketName)
  • ObjectListing listObjects(String bucketName, String prefix)
  • ObjectListing listObjects(ListObjectsRequest listObjectsRequest)

前两类称为简单列举,最多返回100个Object,参数prefix是指定返回Object的前缀。最后一类提供多种过滤功能,可以实现灵活的查询功能。

ObjectListing的参数如下:

参数 描述 方法
ObjectSummaries 限定返回的Object Meta。 List<OSSObjectSummary> getObjectSummaries()
Prefix 本次查询结果的开始前缀。 String getPrefix()
Delimiter 对Object名字进行分组的一个字符。 String getDelimiter()
Marker 标明这次List Object的起点。 String getMarker()
MaxKeys 响应请求内返回结果的最大数目。 int getMaxKeys()
NextMarker 下一次List Object的起点。 String getNextMarker()
IsTruncated 指明是否所有的结果都已经返回。 boolean isTruncated()
CommonPrefixes 如果请求中指定了Delimiter参数,则返回的结果包含CommonPrefixes元素。该元素标明以Delimiter结尾,并有共同前缀的Object的集合。 List<String> getCommonPrefixes()
EncodingType 指明返回结果中编码使用的类型。 String getEncodingType()

listObjects的完整代码请参见GitHub

简单列举文件

以下代码用于列举指定存储空间下的文件,默认列举100个文件。

  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 KeyPrifex = "<yourKeyPrifex>";
  8. // 创建OSSClient实例。
  9. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  10. // 列举Object。 如KeyPrifex参数为空,则列举Bucket下所有的Object。如KeyPrifex参数不为空,则列举包含指定前缀的Object。
  11. ObjectListing objectListing = ossClient.listObjects(bucketName, KeyPrifex);
  12. List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
  13. for (OSSObjectSummary s : sums) {
  14. System.out.println("\t" + s.getKey());
  15. }
  16. // 关闭Client。
  17. ossClient.shutdown();

通过ListObjectsRequest列举文件

可以通过设置ListObjectsReques的参数实现各种灵活的查询功能。ListObjectsReques的可设置参数如下:

参数 描述 方法
Prefix 限定返回的Object必须以Prefix作为前缀。 setPrefix(String prefix)
Delimiter 对Object名字进行分组的一个字符。所有名字包含指定的前缀且第一次出现Delimiter字符之间的Object作为一组元素(CommonPrefixes)。 setDelimiter(String delimiter)
Marker 设定结果从Marker之后按字母排序的第一个开始返回。 setMarker(String marker)
MaxKeys 限定返回的Object的最大个数。如果不设定,默认为100个。Maxkeys取值不能大于1000。 setMaxKeys(Integer maxKeys)
EncodingType 请求响应体中Object名称采用的编码方式,目前支持url setEncodingType(String encodingType)

列举指定个数的文件

以下代码用于列举指定存储空间下指定个数的文件,限定返回文件的最大个数(Maxkeys)。

  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. final int maxKeys = 200;
  11. // 列举Object。
  12. ObjectListing objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withMaxKeys(maxKeys));
  13. List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
  14. for (OSSObjectSummary s : sums) {
  15. System.out.println("\t" + s.getKey());
  16. }
  17. // 关闭Client。
  18. ossClient.shutdown();

列举指定前缀的文件

以下代码用于列举指定存储空间下包含指定前缀(Prefix)的文件。如果不指定前缀则不过滤前缀信息。默认列举100个文件。

  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. final String keyPrefix = "<yourkeyPrefix>";
  11. ObjectListing objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withPrefix(keyPrefix));
  12. List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
  13. for (OSSObjectSummary s : sums) {
  14. System.out.println("\t" + s.getKey());
  15. }
  16. // 关闭Client。
  17. ossClient.shutdown();

列举指定keyMarker之后的文件

以下代码用于列举指定存储空间下指定keyMarker之后的所有文件,限定返回结果从keyMarker之后按字母排序的第一个开始返回。不设定keyMarker则从头开始返回。默认列举100个文件。

  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. final String keyMarker = "<yourkeyMarker>";
  10. ObjectListing objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withMarker(keyMarker));
  11. List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
  12. for (OSSObjectSummary s : sums) {
  13. System.out.println("\t" + s.getKey());
  14. }
  15. // 关闭Client。
  16. ossClient.shutdown();

分页列举所有文件

以下代码用于分页列举指定存储空间下的所有文件。每页列举的文件个数通过MaxKeys指定。

  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. final int maxKeys = 200;
  10. String nextMarker = null;
  11. ObjectListing objectListing;
  12. do {
  13. objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withMarker(nextMarker).withMaxKeys(maxKeys));
  14. List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
  15. for (OSSObjectSummary s : sums) {
  16. System.out.println("\t" + s.getKey());
  17. }
  18. nextMarker = objectListing.getNextMarker();
  19. } while (objectListing.isTruncated());
  20. // 关闭Client。
  21. ossClient.shutdown();

分页列举所有指定Marker之后的文件

以下代码用于分页列举指定存储空间下所有指定Maker之后的文件。每页列举的文件个数通过MaxKeys指定。

  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. final int maxKeys = 200;
  10. String nextMarker = "<yourNextMarker>";
  11. ObjectListing objectListing;
  12. do {
  13. objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withMarker(nextMarker).withMaxKeys(maxKeys));
  14. List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
  15. for (OSSObjectSummary s : sums) {
  16. System.out.println("\t" + s.getKey());
  17. }
  18. nextMarker = objectListing.getNextMarker();
  19. } while (objectListing.isTruncated());
  20. // 关闭Client。
  21. ossClient.shutdown();

分页列举所有包含指定前缀的文件

以下代码用于分页列举指定存储空间下所有包含指定前缀的文件,每页MaxKeys个文件。

  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. final int maxKeys = 200;
  10. final String keyPrefix = "<yourkeyPrefix>";
  11. String nextMarker = "<yourNextMarker>";
  12. ObjectListing objectListing;
  13. do {
  14. objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).
  15. withPrefix(keyPrefix).withMarker(nextMarker).withMaxKeys(maxKeys));
  16. List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
  17. for (OSSObjectSummary s : sums) {
  18. System.out.println("\t" + s.getKey());
  19. }
  20. nextMarker = objectListing.getNextMarker();
  21. } while (objectListing.isTruncated());
  22. // 关闭Client。
  23. ossClient.shutdown();

指定文件名字编码

如果文件名字含有特殊字符,如 ' " & < >中文 等,需要进行编码传输。OSS目前支持 url 编码。

以下代码用于指定文件名字编码:

  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. final int maxKeys = 200;
  10. final String keyPrefix = "<yourkeyPrefix>";
  11. String nextMarker = "<yourNextMarker>";
  12. ObjectListing objectListing;
  13. do {
  14. ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
  15. listObjectsRequest.setPrefix(keyPrefix);
  16. listObjectsRequest.setMaxKeys(maxKeys);
  17. listObjectsRequest.setMarker(nextMarker);
  18. // 指定Object名称编码传输。
  19. listObjectsRequest.setEncodingType("url");
  20. objectListing = ossClient.listObjects(listObjectsRequest);
  21. // Object解码。
  22. for (OSSObjectSummary objectSummary: objectListing.getObjectSummaries()) {
  23. System.out.println("Key:" + URLDecoder.decode(objectSummary.getKey(), "UTF-8"));
  24. }
  25. // CommonPrefixe解码。
  26. for (String commonPrefixes: objectListing.getCommonPrefixes()) {
  27. System.out.println("CommonPrefixes:" + URLDecoder.decode(commonPrefixes, "UTF-8"));
  28. }
  29. // NextMarker解码。
  30. if (objectListing.getNextMarker() != null) {
  31. nextMarker = URLDecoder.decode(objectListing.getNextMarker(), "UTF-8");
  32. }
  33. } while (objectListing.isTruncated());
  34. // 关闭Client。
  35. ossClient.shutdown();

文件夹功能

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

通过 Delimiter 和 Prefix 两个参数可以模拟出文件夹功能:

  • 如果设置 Prefix 为某个文件夹名,则会列举以此 Prefix 开头的文件,即该文件夹下所有的文件和子文件夹(目录)。文件名在Contents中显示。
  • 如果再设置 Delimiter 为 “/” ,则只列举该文件夹下的文件和子文件夹(目录),该文件夹下的子文件夹(目录)返回在 CommonPrefixes 部分,子文件夹下的文件和文件夹不显示。

文件夹详情请参见文件夹功能。创建文件的完整代码请参见GitHub

假设Bucket中有4个文件: oss.jpg、fun/test.jpg、fun/movie/001.avi、fun/movie/007.avi,“/” 作为文件夹的分隔符。下面的示例展示了如何模拟文件夹功能。

列举存储空间下所有文件

以下代码用于列举指定存储空间下的所有文件:

  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. // 构造ListObjectsRequest请求。
  10. ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
  11. // 列出Object 。
  12. ObjectListing listing = ossClient.listObjects(listObjectsRequest);
  13. // 遍历所有Object。
  14. System.out.println("Objects:");
  15. for (OSSObjectSummary objectSummary : listing.getObjectSummaries()) {
  16. System.out.println(objectSummary.getKey());
  17. }
  18. // 遍历所有CommonPrefix。
  19. System.out.println("CommonPrefixs:");
  20. for (String commonPrefix : listing.getCommonPrefixes()) {
  21. System.out.println(commonPrefix);
  22. }
  23. // 关闭Client。
  24. ossClient.shutdown();

返回结果如下:

  1. Objects:
  2. fun/movie/001.avi
  3. fun/movie/007.avi
  4. fun/test.jpg
  5. oss.jpg
  6. CommonPrefixs:

列举指定目录下所有文件

以下代码用于列举指定目录下的所有文件:

  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. // 构造ListObjectsRequest请求。
  10. ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
  11. //设置 Prefix 参数来获取某个目录(fun/)下的所有文件
  12. listObjectsRequest.setPrefix("fun/");
  13. // 递归列出fun目录下的所有文件。
  14. ObjectListing listing = ossClient.listObjects(listObjectsRequest);
  15. // 遍历所有Object。
  16. System.out.println("Objects:");
  17. for (OSSObjectSummary objectSummary : listing.getObjectSummaries()) {
  18. System.out.println(objectSummary.getKey());
  19. }
  20. // 遍历所有CommonPrefix。
  21. System.out.println("\nCommonPrefixs:");
  22. for (String commonPrefix : listing.getCommonPrefixes()) {
  23. System.out.println(commonPrefix);
  24. }
  25. // 关闭Client。
  26. ossClient.shutdown();

返回结果如下:

  1. Objects:
  2. fun/movie/001.avi
  3. fun/movie/007.avi
  4. fun/test.jpg
  5. CommonPrefixs:

列举目录下的文件和子目录

以下代码用于列举指定目录(fun/)下的文件和文件夹:

  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. // 构造ListObjectsRequest请求。
  10. ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
  11. // "/" 为文件夹的分隔符。
  12. listObjectsRequest.setDelimiter("/");
  13. // 列出fun目录下的所有文件和文件夹。
  14. listObjectsRequest.setPrefix("fun/");
  15. ObjectListing listing = ossClient.listObjects(listObjectsRequest);
  16. // 遍历所有Object。
  17. System.out.println("Objects:");
  18. //ObjectSummaries 的列表中给出的是fun目录下的文件。
  19. for (OSSObjectSummary objectSummary : listing.getObjectSummaries()) {
  20. System.out.println(objectSummary.getKey());
  21. }
  22. // 遍历所有CommonPrefix。
  23. System.out.println("\nCommonPrefixs:");
  24. //CommonPrefixs列表中给出的是fun目录下的所有子文件夹。fun/movie/001.avi 和 fun/movie/007.avi 两个文件并没有被列出来,因为它们属于fun文件夹下的movie目录。
  25. for (String commonPrefix : listing.getCommonPrefixes()) {
  26. System.out.println(commonPrefix);
  27. }
  28. // 关闭Client。
  29. ossClient.shutdown();

返回结果如下:

  1. Objects:
  2. fun/test.jpg
  3. CommonPrefixs:
  4. fun/movie/

删除文件

删除单个文件

以下代码用于删除单个文件:

  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. // 删除Object。
  11. ossClient.deleteObject(bucketName, objectName);
  12. // 关闭Client。
  13. ossClient.shutdown();

删除多个文件

每次最多删除1000个Object。有两种返回模式:详细(Verbose)模式和简单(Quiet)模式:

  • 详细模式:返回删除成功的Object列表。默认为详细模式。
  • 简单模式:返回删除删除失败的Object列表。

DeleteObjectsRequest可设置的参数如下:

参数 描述 方法
Keys 需要删除的Objects setKeys(List<String>)
Quiet 返回模式。true表示简单模式,false表示详细模式。默认为详细模式。 setQuiet(boolean)
EncodingType 指定对返回的Key进行编码,目前支持url setEncodingType(String)

DeleteObjectsResult的参数如下:

参数 描述 方法
deletedObjects 删除结果。详细模式下为删除成功的Object列表,简单模式下为删除失败的Object列表。 List<String> getDeletedObjects()
EncodingType deletedObjects中Key的编码,为空表示没有编码。 getEncodingType()

以下代码用于批量删除文件:

  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. // 删除Objects。
  10. List<String> keys = new ArrayList<String>();
  11. keys.add("key0");
  12. keys.add("key1");
  13. keys.add("key2");
  14. DeleteObjectsResult deleteObjectsResult = ossClient.deleteObjects(new DeleteObjectsRequest(bucketName).withKeys(keys));
  15. List<String> deletedObjects = deleteObjectsResult.getDeletedObjects();
  16. // 关闭Client。
  17. ossClient.shutdown();

批量删除文件的完整代码请参见GitHub

拷贝文件

您可以通过ossClient.copyObject方法将Object从一个Bucket(源Bucket)复制到同一地域的另一个Bucket(目标Bucket)。此方法有两种参数指定方式:

参数指定方式 描述
CopyObjectResult copyObject(String sourceBucketName, String sourceKey, String destinationBucketName, String destinationKey) 允许指定源Bucket和源Object,以及目标Bucket和目标Object。拷贝后,目标Object的内容及元信息与源Object相同,称为简单拷贝。
CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest) 允许指定目标Object的元信息和拷贝的限制条件。如果拷贝操作的源Object地址和目标Object地址相同,则直接替换源Object的元信息。

CopyObjectRequest可设置的参数如下:

参数 描述 方法
sourceBucketName 源Bucket的名称。 setSourceBucketName(String sourceBucketName)
sourceKey 源Object的名称。 setSourceKey(String sourceKey)
destinationBucketName 目标Bucket的名称。 setDestinationBucketName(String destinationBucketName)
destinationKey 目标Object的名称。 setDestinationKey(String destinationKey)
newObjectMetadata 目标Object的元信息。 setNewObjectMetadata(ObjectMetadata newObjectMetadata)
matchingETagConstraints 拷贝的限制条件。如果源Object的ETag值和提供的ETag值相等,则执行拷贝操作;否则返回错误。 setMatchingETagConstraints(List<String> matchingETagConstraints)
nonmatchingEtagConstraints 拷贝的限制条件。如果源Object的ETag值和用户提供的ETag值不相等,则执行拷贝操作;否则返回错误。 setNonmatchingETagConstraints(List<String> nonmatchingEtagConstraints)
unmodifiedSinceConstraint 拷贝的限制条件。如果传入参数中的时间等于或者晚于文件实际修改时间,则执行拷贝操作;否则返回错误。 setUnmodifiedSinceConstraint(Date unmodifiedSinceConstraint)
modifiedSinceConstraint 拷贝的限制条件。如果源Object在用户指定的时间之后被修改过,则执行拷贝操作;否则返回错误。 setModifiedSinceConstraint(Date modifiedSinceConstraint)

CopyObjectRequest的参数如下:

参数 描述 方法
etag OSS Object唯一性标志 String getETag()
lastModified Object最后修改时间 Date getLastModified()

此操作的限制条件如下:

  • 用户有源Object的读写权限。
  • 不支持跨Region拷贝。例如,不支持将杭州Bucket里的Object拷贝到青岛。
  • Object的大小不能超过1GB。

简单拷贝

以下代码用于简单拷贝:

  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 sourceBucketName = "<yourSourceBucketName>";
  7. String sourceObjectName = "<yourSourceObjectName>";
  8. String destinationBucketName = "<yourDestinationBucketName>";
  9. String destinationObjectName = "<yourDestinationObjectName>";
  10. // 创建OSSClient实例。
  11. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  12. // 拷贝Object。
  13. CopyObjectResult result = ossClient.copyObject(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
  14. System.out.println("ETag: " + result.getETag() + " LastModified: " + result.getLastModified());
  15. // 关闭Client。
  16. ossClient.shutdown();

通过CopyObjectRequest拷贝

你可以通过CopyObjectRequest拷贝文件,代码如下:

  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 sourceBucketName = "<yourSourceBucketName>";
  7. String sourceObjectName = "<yourSourceObjectName>";
  8. String destinationBucketName = "<yourDestinationBucketName>";
  9. String destinationObjectName = "<yourDestinationObjectName>";
  10. // 创建OSSClient实例。
  11. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  12. // 创建CopyObjectRequest对象。
  13. CopyObjectRequest copyObjectRequest = new CopyObjectRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
  14. // 设置新的Metadata。
  15. ObjectMetadata meta = new ObjectMetadata();
  16. meta.setContentType("text/html");
  17. copyObjectRequest.setNewObjectMetadata(meta);
  18. // 复制Object。
  19. CopyObjectResult result = ossClient.copyObject(copyObjectRequest);
  20. System.out.println("ETag: " + result.getETag() + " LastModified: " + result.getLastModified());
  21. // 关闭Client。
  22. ossClient.shutdown();

拷贝大文件

CopyObject只能Copy小于1GB的文件,大文件需要使用分片拷贝(UploadPartCopy)。分片拷贝分为三步:

  1. 通过ossClient.initiateMultipartUpload初始化分片拷贝任务。
  2. 通过ossClient.uploadPartCopy进行分片拷贝。除最后一个分片外,其它分片都要大于100KB。
  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 sourceBucketName = "<yourSourceBucketName>";
  7. String sourceObjectName = "<yourSourceObjectName>";
  8. String destinationBucketName = "<yourDestinationBucketName>";
  9. String destinationObjectName = "<yourDestinationObjectName>";
  10. // 得到被拷贝Object大小。
  11. ObjectMetadata objectMetadata = ossClient.getObjectMetadata(sourceBucketName, sourceObjectName);
  12. long contentLength = objectMetadata.getContentLength();
  13. // 分片大小,10MB。
  14. long partSize = 1024 * 1024 * 10;
  15. // 计算分片数目。
  16. int partCount = (int) (contentLength / partSize);
  17. if (contentLength % partSize != 0) {
  18. partCount++;
  19. }
  20. System.out.println("total part count:" + partCount);
  21. // 初始化拷贝任务。可以通过InitiateMultipartUploadRequest指定目标object的元信息。
  22. InitiateMultipartUploadRequest initiateMultipartUploadRequest = new InitiateMultipartUploadRequest(destinationBucketName, destinationObjectName);
  23. InitiateMultipartUploadResult initiateMultipartUploadResult = ossClient.initiateMultipartUpload(initiateMultipartUploadRequest);
  24. String uploadId = initiateMultipartUploadResult.getUploadId();
  25. // 分片拷贝。
  26. List<PartETag> partETags = new ArrayList<PartETag>();
  27. for (int i = 0; i < partCount; i++) {
  28. // 计算每个分片的大小。
  29. long skipBytes = partSize * i;
  30. long size = partSize < contentLength - skipBytes ? partSize : contentLength - skipBytes;
  31. // 创建UploadPartCopyRequest。可以通过UploadPartCopyRequest指定限定条件。
  32. UploadPartCopyRequest uploadPartCopyRequest =
  33. new UploadPartCopyRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
  34. uploadPartCopyRequest.setUploadId(uploadId);
  35. uploadPartCopyRequest.setPartSize(size);
  36. uploadPartCopyRequest.setBeginIndex(skipBytes);
  37. uploadPartCopyRequest.setPartNumber(i + 1);
  38. UploadPartCopyResult uploadPartCopyResult = ossClient.uploadPartCopy(uploadPartCopyRequest);
  39. // 将返回的PartETag保存到List中。
  40. partETags.add(uploadPartCopyResult.getPartETag());
  41. }
  42. // 提交分片拷贝任务。
  43. CompleteMultipartUploadRequest completeMultipartUploadRequest = new CompleteMultipartUploadRequest(
  44. destinationBucketName, destinationObjectName, uploadId, partETags);
  45. ossClient.completeMultipartUpload(completeMultipartUploadRequest);
  46. // 关闭Client。
  47. ossClient.shutdown();

分片拷贝更详细的说明请参见UploadPartCopy。分片拷贝的完整代码请参见GitHub

解冻归档文件

归档类型(Archive)的Object需要解冻(Restore)之后才能读取。非归档类型的文件,不要调用 restoreObject

归档文件的状态变换过程如下:

  1. 归档类型的文件初始时处于冷冻状态。
  2. 提交解冻(Restore)操作后,服务端执行解冻,文件处于解冻中。
  3. 完成解冻后,可以读取Object。解冻状态默认持续1天,最多延长7天,之后文件又回到冷冻状态。

以下代码用于解冻归档文件:

  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. ObjectMetadata objectMetadata = ossClient.getObjectMetadata(bucketName, objectName);
  11. // check whether the object is archive class
  12. StorageClass storageClass = objectMetadata.getObjectStorageClass();
  13. if (storageClass == StorageClass.Archive) {
  14. // restore object
  15. ossClient.restoreObject(bucketName, objectName);
  16. // wait for restore completed
  17. do {
  18. Thread.sleep(1000);
  19. objectMetadata = ossClient.getObjectMetadata(bucketName, objectName);
  20. } while (!objectMetadata.isRestoreCompleted());
  21. }
  22. // get restored object
  23. OSSObject ossObject = ossClient.getObject(bucketName, objectName);
  24. ossObject.getObjectContent().close();
  25. // 关闭Client。
  26. ossClient.shutdown();

详细说明请参见归档存储。解冻归档文件的完整代码请参见GitHUb

创建符号链接

符号链接是一种特殊的Object,它指向某个具体的Object,类似于Windows上使用的快捷方式。OSS支持用户自定义Object的元信息。

以下代码用于创建符号链接:

  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 symLink = "<yourSymLink>";
  8. String destinationObjectName = "<yourDestinationObjectName>";
  9. // 创建OSSClient实例。
  10. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  11. // 创建上传Object的Metadata。
  12. ObjectMetadata metadata = new ObjectMetadata();
  13. metadata.setContentType("text/plain");
  14. // 设置自定义元信息property的值为property-value。
  15. metadata.addUserMetadata("property", "property-value");
  16. //创建CreateSymlinkRequest。
  17. CreateSymlinkRequest createSymlinkRequest = new CreateSymlinkRequest(bucketName, symLink, destinationObjectName);
  18. //设置Metadata。
  19. createSymlinkRequest.setMetadata(metadata);
  20. //创建Symlink。
  21. ossClient.createSymlink(createSymlinkRequest);
  22. // 关闭Client。
  23. ossClient.shutdown();

更详细的解释请参见PutSymlink

获取符号链接所指向的文件内容

此操作要求用户对该符号链接有读权限。以下代码用于获取符号链接所指向的文件内容:

  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 symLink = "<yourSymLink>";
  8. // 创建OSSClient实例。
  9. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  10. //获取Symlink。
  11. OSSSymlink symbolicLink = ossClient.getSymlink(bucketName, symLink);
  12. System.out.println(symbolicLink.getSymlink());
  13. System.out.println(symbolicLink.getTarget());
  14. System.out.println(symbolicLink.getRequestId());
  15. // 关闭Client。
  16. ossClient.shutdown();

更详细的解释请参见GetSymlink

本文导读目录