SDK 手册 Java-SDK 前言 SDK 下载 - Java SDK 开发包最新版本 2.2.3:java_sdk_ zip; - github 地址 : 版本迭代详情参考这里 简介 - O

Transcription

1 对象存储 OSS SDK 手册

2 SDK 手册 Java-SDK 前言 SDK 下载 - Java SDK 开发包最新版本 2.2.3:java_sdk_ zip; - github 地址 : 版本迭代详情参考这里 简介 - OSS Java SDK 适用于 JDK 6 及以上版本 ; - 本文档主要介绍 OSS Java SDK 的安装 使用及注意事项 ; - 并且假设您已经开通了阿里云 OSS 服务, 并创建了 AccessKeyId 和 AccessKeySecret - 如果您还没有开通或者还不了解阿里云 OSS 服务, 请登录 OSS 产品主页了解 - 如果还没有创建 AccessKeyId 和 AccessKeySecret, 请到阿里云 Access Key 管理创建 Access Key 兼容性 对于 2.. 系列 SDK: - 接口 : 兼容 - 命名空间 : - 接口 : 兼容 对于 1.0. 系列 SDK: 1

3 兼容 - 命名空间 : 不兼容 :2.0.0 版本移除 1.0.x 版本中 OTS 相关代码, 调整包结构, 将包名称 com.aliyun.openservices. 与 com.aliyun.openservices.oss. 更换为 com.aliyun.oss.* 安装 环境准备 - 适用于 JDK 6 及以上版本 安装方式 方式一 : 在 Maven 项目中加入依赖项 ( 推荐方式 ) 在 Maven 工程中使用 OSS Java SDK 只需在 pom.xml 中加入相应依赖即可 以 版本为例, 在 dependencies 标签内加入如下内容 : <dependency> <groupid>com.aliyun.oss</groupid> <artifactid>aliyun-sdk-oss</artifactid> <version>2.2.3</version> </dependency> 方式二 : 在 Eclipse 项目中导入 JAR 包 以 版本为例, 步骤如下 : - 下载 Java SDK 开发包版本号 2.2.3:java_sdk_ zip; - 解压该开发包 ; - 将解压后文件夹中的文件 : aliyun-sdk-oss-<versionid>.jar 以及 lib 文件夹下的所有文件拷贝到您的项目中 ; - 在 Eclipse 中选择您的工程, 右击 -> Properties -> Java Build Path -> Add JARs; - 选中您在第三步拷贝的所有 JAR 文件 ; - 经过以上几步, 您就可以在 Eclipse 项目中使用 OSS Java SDK 示例工程 OSS Java SDK 提供了基于 maven ant 的示例工程, 您可以在本地设备上编译运行示例工程 您也可以以示例 2

4 工程为基础开发您的应用 - mvn 示例工程 - ant 示例工程 提示 : - 编译运行前, 请修改 HelloOSS.java 中 endpoint/accesskeyid/accesskeysecret/bucketname 为您的真实信息 ; - 工程的编译运行方法, 参看工程目录下 README.md 示例程序 OSS Java SDK 提供丰富的示例程序, 方便用户参考或直接使用 您可以通过以下两种方式获取示例程序 : - github 查看下载,OSS Java SDK github 下的 src/samples 为示例程序 ; - 下载 OSS Java SDK 开发包, 如 2.2.3, 解压后 aliyun_java_sdk_ /samples 为示例程序 ; 初始化 OSSClient 是 OSS 服务的 Java 客户端, 它为调用者提供一系列与 OSS 进行交互的接口, 用于管理 操作存储空间 (Bucket) 和文件 (Object) 等 OSS 资源 使用 Java SDK 发起 OSS 请求, 您需要初始化一个 OSSClient 实例, 并根据需要修改 ClientConfiguration 的默认配置项 确定 Endpoint 请先阅读开发人员指南中关于访问域名和数据中心和自定义访问域名的部分, 理解 Endpoint 相关的概念 Endpoint 可以有以下几种形式 : 示例 说明 以 HTTP 协议, 公网访问杭州区域的 Bucket 以 HTTPS 协议, 公网范围北京区域的 Bucket 以 HTTP 协议, 通过用户自定义域名 (CNAME) 访问特定 Bucket 配置密钥 要接入阿里云 OSS, 您需要拥有一个有效的 Access Key( 包括 AccessKeyId 和 AccessKeySecret) 用来进行签名 认证 可以通过如下步骤获得 : 3

5 - 注册阿里云帐号 - 申请 AccessKey 获取 AccessKeyId 和 AccessKeySecret 之后, 您便可以按照以下步骤进行初始化 新建 OSSClient 使用 OSS 域名新建 OSSClient 新建一个 OSSClient 代码如下 : // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient client = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 使用访问 OSS // 关闭 client client.shutdown(); 提示 : - 您的工程中可以有多个 OSSClient, 也可以只有一个 OSSClient; - OSSClient 可以并发使用 ; - OSS 支持 https, 当您的安全需求更高时, 可以使用 https; - OSSClient.shutdown 之后不能再使用 使用自定义域名 (CNAME) 新建 OSSClient 下面的代码让客户端使用 CNAME 访问 OSS 服务,CNAME 更详细的信息请参考 OSS 自定义域名 String endpoint = "<yourendpoint>"; String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 ClientConfiguration 实例, 按照您的需要修改默认参数 ClientConfiguration conf = new ClientConfiguration(); // 开启支持 CNAME 选项 conf.setsupportcname(true); // 创建 OSSClient 实例 OSSClient client = new OSSClient(endpoint, accesskeyid, accesskeysecret, conf); 4

6 // 使用访问 OSS // 关闭 client client.shutdown(); 注意 : - 使用 CNAME 时无法使用 ListBuckets 接口 使用 IP 新建 OSSClient 某些特殊情况 ( 比如专有域 ) 下, 您需要 IP 地址做作为 endpoint OSS Java sdk 及以后版本, 会自动失败 IP 地址, 初始化同域名相同 ;OSS Java sdk 以前的版本, 初始化时需要设置 setsldenabled, 代码如下 : // 请按照实际 IP 填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 ClientConfiguration 实例, 按照您的需要修改默认参数 ClientConfiguration conf = new ClientConfiguration(); // 开启二级域名访问 OSS, 默认不开启 conf.setsldenabled(true) // 创建 OSSClient 实例 OSSClient client = new OSSClient(endpoint, accesskeyid, accesskeysecret, conf); // 使用访问 OSS // 关闭 client client.shutdown(); 使用 STS 新建 OSSClient 使用 STS 新建一个 OSSClient 代码如下,STS 的详细信息请参考 RAM 和 STS 介绍 : // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // 临时账号 accesskeyid/accesskeysecret/securitytoken String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String securitytoken = "<yoursecuritytoken>"; // 创建 OSSClient 实例 OSSClient client = new OSSClient(endpoint, accesskeyid, accesskeysecret, securitytoken); 5

7 // 使用访问 OSS // 关闭 client client.shutdown(); 提示 : - Java sdk 的 STS 过期自动处理功能, 请参看授权访问 配置 OSSClient 如果您需要修改 OSSClient 的一些默认配置, 请在构造 OSSClient 的时候传入 ClientConfiguration 实例 ClientConfiguration 是 OSSClient 的配置类, 可配置代理 连接超时 最大连接数等参数 通过 ClientConfiguration 可以设置的参数见下表 : 参数描述方法 MaxConnections SocketTimeout ConnectionTimeout ConnectionRequestTimeout IdleConnectionTime MaxErrorRetry SupportCname SLDEnabled Protocol UserAgent ProxyHost ProxyPort 允许打开的最大 HTTP 连接数 默认为 1024 Socket 层传输数据的超时时间 ( 单位 : 毫秒 ) 默认为 毫秒 建立连接的超时时间 ( 单位 : 毫秒 ) 默认为 毫秒 从连接池中获取连接的超时时间 ( 单位 : 毫秒 ) 默认不超时 关闭空闲该时长的连接 ( 单位 : 毫秒 ) 默认为 毫秒 请求失败后最大的重试次数 默认 3 次 是否支持 CNAME 作为 Endpoint, 默认支持 CNAME 是否开启二级域名 (Second Level Domain) 的访问方式, 默认不开启 连接 OSS 所采用的协议 (HTTP/HTTPS), 默认为 HTTP 用户代理, 指 HTTP 的 User- Agent 头 默认为 "aliyun-sdkjava" 代理服务器主机地址 代理服务器端口 ClientConfiguration.setMaxC onnections ClientConfiguration.setSocke ttimeout ClientConfiguration.setConn ectiontimeout ClientConfiguration.setConn ectionrequesttimeout ClientConfiguration.setIdleCo nnectiontime ClientConfiguration.setMaxEr rorretry ClientConfiguration.setSupp ortcname ClientConfiguration.setSLDEn abled ClientConfiguration.setProto col ClientConfiguration.setUserA gent ClientConfiguration.setProxy Host ClientConfiguration.setProxy Port 6

8 ProxyUsername ProxyPassword ProxyDomain ProxyWorkstation 代理服务器验证的用户名 代理服务器验证的密码 访问 NTLM 验证的代理服务器的 Windows 域名 NTLM 代理服务器的 Windows 工作站名称 ClientConfiguration.setProxy Username ClientConfiguration.setProxy Password ClientConfiguration.setProxy Domain ClientConfiguration.setProxy Workstation 使用 ClientConfiguration 设置 OSSClient 参数代码如下 : // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 ClientConfiguration 实例 ClientConfiguration conf = new ClientConfiguration(); // 设置 OSSClient 使用的最大连接数, 默认 1024 conf.setmaxconnections(200); // 设置请求超时时间, 默认 50 秒 conf.setsockettimeout(10000); // 设置失败请求重试次数, 默认 3 次 conf.setmaxerrorretry(5); // 创建 OSSClient 实例 OSSClient client = new OSSClient(endpoint, accesskeyid, accesskeysecret, conf); // 使用访问 OSS // 关闭 OSSClient client.shutdown(); 快速入门 请确认您已经熟悉 OSS 的基本概念, 如 Bucket Object Endpoint AccessKeyId 和 AccessKeySecret 等 本节您将看到如何快速使用 OSS Java SDK, 完成进行常见操作, 如创建存储空间 上传文件 下载文件等 初始化 OSSClient 向 OSS 发送任一 HTTP 请求之前, 必须先创建一个 OSSClient 实例 : 7

9 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 使用访问 OSS // 关闭 ossclient ossclient.shutdown(); 提示 : - 更多 OSSClient 初始化的内容请参考初始化 创建 Bucket 存储空间 (Bucket) 是 OSS 全局命名空间, 相当于数据的容器, 可以存储若干文件 (Object) 以下代码展示如何 新建一个 Bucket: ossclient.createbucket("<bucketname>"); 提示 : - Bucket 的命名规范, 参见 Bucket 中的命名规范 - 更多创建 Bucket 的信息, 请参见管理 Bucket 上传 Object 以下代码展示如何上传文件 (object) 至 OSS: String content = "Hello OSS"; ossclient.putobject("<bucketname>", "<key>", new ByteArrayInputStream(content.getBytes())); 提示 : - Java SDK 通过 InputStream 上传 Object 至 OSS - 更多上传 Object 的信息, 请参见上传文件 下载 Object 8

10 以下代码展示如何获取 Object 的文本内容 : OSSObject ossobject = ossclient.getobject("<bucketname>", "<key>")); InputStream content = ossobject.getobjectcontent(); if (content!= null) BufferedReader reader = new BufferedReader(new InputStreamReader(content)); while (true) String line = reader.readline(); if (line == null) break; System.out.println("\n" + line); content.close(); 提示 : - 调用 OSSClient.GetObject 返回一个 OSSObject 实例, 该实例包含文件内容及其元信息 (meta) - 调用 OSSObject.GetObjectContent 获取文件输入流, 可读取此输入流获取其内容, 用完之后关闭请这个流 - 更多下载 Object 的信息, 请参见下载文件 列举 Object 当完成一系列上传 Object 操作后, 可能需要查看 Bucket 下包含哪些 Object 以下代码展示如何列举指定 Bucket 下的 Object: ObjectListing objectlisting = ossclient.listobjects("<bucketname>"); for (OSSObjectSummary objectsummary : objectlisting.getobjectsummaries()) System.out.println(" - " + objectsummary.getkey() + " " + "(size = " + objectsummary.getsize() + ")"); 调用 OSSClient#listObjects 返回 ObjectListing 实例, 该实例包含此次 listobject 请求的返回结果, 可通过 ObjetListing#getObjectSummaries 获取所有 Object 的描述信息 提示 : - 上面的代码默认列举 100 个 object - 更丰富的列举功能, 请参见管理文件中的列出存储空间中的文件 删除 Object 以下代码展示如何删除指定 Object: 9

11 ossclient.deleteobject("<bucketname>", "<key>") 提示 : - OSS Java SDK 操作成功完成时, 没有异常抛出, 返回值有效 ; 抛出异常说明操作失败, 此时返回的数据无效 ; - 完整代码请参考 :GitHub 管理 Bucket 创建 Bucket 您可以使用 OSSClient.createBucket 创建 Bucket 如下代码展示如何新建一个 Bucket: // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 创建 bucket String bucketname = "<your-oss-bucket-name>"; ossclient.createbucket(bucketname); // 关闭 client ossclient.shutdown(); 提示 : - Bucket 的命名规范, 参见基本概念中的命名规范 - Bucket 的名字是全局唯一的, 所以您需要保证 Bucket 名称不与别人重复 上面代码创建的 bucket, 权限是私有读写 创建 bucket 时可以指定 bucket 权限, 如下的示例代码 : CreateBucketRequest createbucketrequest= new CreateBucketRequest(bucketName); // 设置 bucket 权限 createbucketrequest.setcannedacl(cannedaccesscontrollist.publicread); ossclient.createbucket(createbucketrequest); 10

12 列举 Bucket 您可以使用 OSSClient.listBuckets 列举指定用户下的 Bucket 简单列举 以下代码展示如何采用简单方式列举指定用户的 Bucket 列表 : // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 列举 bucket List<Bucket> buckets = ossclient.listbuckets(); for (Bucket bucket : buckets) System.out.println(" - " + bucket.getname()); // 关闭 client ossclient.shutdown(); 上面的代码最多只能返回 100 个 bucket, 已经能满足用户的需求 列举 bucket 时, 通过指定 prefix marker maxkeys 参数, 可以过滤 bucket 列表, 实现灵活的查询功能 参数 prefix marker max keys 作用 限定返回的 bucket name 必须以 prefix 作为前缀, 可以不设定, 不设定时不过滤前缀信息 设定结果从 marker 之后按字母排序的第一个开始返回, 可以不设定, 不设定时从头开始返回 限定此次返回 bucket 的最大数, 如果不设定, 默认为 100,max-keys 取值不能大于 1000 指定前缀列举 ListBucketsRequest listbucketsrequest = new ListBucketsRequest(); listbucketsrequest.setprefix("<yourbucketprefix>"); for (Bucket bucket : ossclient.listbuckets()) System.out.println(" - " + bucket.getname()); 11

13 指定 max keys 列举 ListBucketsRequest listbucketsrequest = new ListBucketsRequest(); listbucketsrequest.setmaxkeys(500); for (Bucket bucket : ossclient.listbuckets()) System.out.println(" - " + bucket.getname()); 删除 Bucket 您可以使用 OSSClient.deleteBucket 删除 Bucket 以下代码展示如何删除一个 Bucket: // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 删除 bucket ossclient.deletebucket("<bucketname>"); // 关闭 client ossclient.shutdown(); 提示 : - 如果存储空间不为空 ( 存储空间中有文件或者分片上传碎片 ), 则存储空间无法删除 ; - 必须先删除存储空间中的所有文件后, 存储空间才能成功删除 判断 Bucket 是否存在 您可以使用 OSSClient.doesBucketExist 接口判断该 Bucket 是否已存在 以下代码展示如何判断指定 Bucket 是 否存在 : // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); 12

14 boolean exists = ossclient.doesbucketexist("<bucketname>"); // 关闭 client ossclient.shutdown(); 设置 Bucket ACL Bucket 的 ACL 包含三类 :Private( 私有读写 ), PublicRead( 公共读私有写 ), PublicReadWrite( 公共读写 ) 您可以通过 OSSClient.setBucketAcl 设置 bucket 的权限 权限私有读写公共读私有写公共读写 Java SDK 对应值 CannedAccessControlList.Private CannedAccessControlList.PublicRead CannedAccessControlList.PublicReadWrite 以下代码展示如何设置 Bucket 的权限 : // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 设置 bucket 权限 ossclient.setbucketacl("<bucketname>", CannedAccessControlList.Private); // 关闭 client ossclient.shutdown(); 获取 Bucket ACL 您可以通过 OSSClient.getBucketAcl 获取 bucket 的权限 以下代码展示如何获取 Bucket 的 ACL: // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); AccessControlList acl = ossclient.getbucketacl("<bucketname>"); // bucket 权限 13

15 System.out.println(acl.toString()); // 关闭 client ossclient.shutdown(); 获取 Bucket Location Bucket Location 即 Bucket Region, 详细请参看基本概念中的 Region( 区域 ) 您可以通过 OSSClient.getBucketLocation 获取 bucket 的权限 以下代码展示如何获取 Bucket 的 Location: // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); String location = ossclient.getbucketlocation("<bucketname>"); System.out.println(location); // 关闭 client ossclient.shutdown(); 获取 Bucket Info Bucket 的 Info 包括 Location CreationDate Owner 及权限等信息 以下代码展示如何获取 Bucket 的 Info: // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); BucketInfo info = ossclient.getbucketinfo("<bucketname>"); // Location info.getbucket().getlocation(); // 创建日期 info.getbucket().getcreationdate(); // owner info.getbucket().getowner(); // 权限 info.getgrants(); // 关闭 client ossclient.shutdown(); 14

16 上传文件 在 OSS 中, 用户操作的基本数据单元是文件 (Object) OSS Java SDK 提供了丰富的文件上传接口, 可以通过以下方式上传文件 : - 流式上传 - 文件上传 - 追加上传 - 分片上传 - 断点续传上传流式上传 文件上传 追加上传的文件 (Object) 最大不能超过 5GB 当文件较大时, 请使用分片上传, 分片上传文件大小不能超过 48.8TB 断点续传上传, 支持并发 断点续传 自定义分片大小, 断点续传是分片上传封装和加强 文件上传推荐使用断点续传 简单上传 流式上传 文件上传称为简单上传 流式上传, 使用 InputStream 作为 Object 数据源 ; 文件上传使用本地文件 作为 Object 数据源 提示 : - 简单上传的完整代码请参考 :GitHub 流式上传 您可以使用 OSSClient.putObject 上传您的数据流到 OSS 上传字符串 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 上传字符串 String content = "Hello OSS"; ossclient.putobject("<yourbucketname>", "<yourkey>", new ByteArrayInputStream(content.getBytes())); 15

17 // 关闭 client ossclient.shutdown(); 上传 byte 数组 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid,accesskeysecret); // 上传 byte[] content = "Hello OSS".getBytes(); ossclient.putobject("<yourbucketname>", "<yourkey>", new ByteArrayInputStream(content)); // 关闭 client ossclient.shutdown(); 上传网络流 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 上传 InputStream inputstream = new URL(" ossclient.putobject("<yourbucketname>", "<yourkey>", inputstream); // 关闭 client ossclient.shutdown(); 上传文件流 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 上传文件流 16

18 InputStream inputstream = new FileInputStream("localFile"); ossclient.putobject("<yourbucketname>", "<yourkey>", inputstream); // 关闭 client ossclient.shutdown(); 上传本地文件 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 上传文件 ossclient.putobject("<yourbucketname>", "<yourkey>", new File("localFile")); // 关闭 client ossclient.shutdown(); 设置元信息 文件元信息 (Object Meta), 是对用户上传到 OSS 的文件的属性描述, 分为两种 :HTTP 标准属性 (HTTP Headers) 和 User Meta( 用户自定义元信息 ) 文件元信息可以在各种方式上传 ( 流上传 文件上传 追加上传 分片上传 断点续传 ), 或拷贝文件时进行设置 元信息的名称大小写不敏感 更多文件元信息的介绍, 请参看文件元信息 设定 Http Header OSS 允许用户自定义 Http header Http header 请参考 RFC2616 几个常用的 http header 说明如下 : 名称描述默认值 Content-MD5 Content-Type Content-Disposition 文件数据校验, 设置了该值后 OSS 会启用文件内容 MD5 校验, 把您提供的 MD5 与文件的 MD5 比较, 不一致会抛出错误 文件的 MIME, 定义文件的类型及网页编码, 决定浏览器将以什么形式 什么编码读取文件 如果用户没有指定则根据 Key 或文件名的扩展名生成, 如果没有扩展名则填默认值 指示 MINME 用户代理如何显示附加的文件, 打开或下载, 及文件名称 无 application/octet-stream 无 Content-Length 上传的文件的长度, 超过流 / 文流 / 文件时间长度 17

19 Expires Cache-Control 件的长度会截断, 不足为实际值 缓存过期时间,OSS 未使用, 格式是格林威治时间 (GMT) 指定该 Object 被下载时的网页的缓存行为 无 无 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String content = "Hello OSS"; // 创建上传 Object 的 Metadata ObjectMetadata meta = new ObjectMetadata(); // 设置上传文件长度 meta.setcontentlength(content.length()); // 设置上传 MD5 校验 String md5 = BinaryUtil.toBase64String(BinaryUtil.calculateMd5(content.getBytes())); meta.setcontentmd5(md5); // 设置上传内容类型 meta.setcontenttype("text/plain"); // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 上传文件 ossclient.putobject("<yourbucketname>", "<yourkey>", new ByteArrayInputStream(content.getBytes()), meta); // 关闭 client ossclient.shutdown(); 提示 : - ObjectMetadata 提供常用的 HTTP Header 的设置, 比如 Content-MD5 Content-Type Content-Length Content-Disposition Content-Encoding Expires 等 ; - ObjectMetadata 中没有直接设置函数的, 请使用 ObjectMetadata.setHeader(String key, Object value) 设置 用户自定义元信息 OSS 支持用户自定义 Object 的元信息, 对 Object 进行描述 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; 18

20 String content = "Hello OSS"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 创建上传 Object 的 Metadata ObjectMetadata meta = new ObjectMetadata(); // 设置自定义元信息 name 的值为 my-data meta.addusermetadata("property", "property-value"); // 上传文件 ossclient.putobject("<yourbucketname>", "<yourkey>", new ByteArrayInputStream(content.getBytes()), meta); // 关闭 client ossclient.shutdown(); 提示 : - 在上面代码中, 用户自定义了一个名称为 "property", 值为 "property-value" 的元信息 ; - 文件的元信息可以通过 OSSClient.getObjectMetadata 获取 ; - 下载文件的时, 文件的元信息也会同时下载 ; - 一个文件可以有多个元信息, 总大小不能超过 8KB 创建模拟文件夹 OSS 是没有文件夹这个概念的, 所有元素都是以 Object 来存储 创建模拟文件夹本质上来说是创建了一个 size 为 0 的 Object 对于这个 Object 可以上传下载, 只是控制台会对以 "/" 结尾的 Object 以文件夹的方式展示 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); final String keysuffixwithslash = "parent_directory/"; ossclient.putobject("<bucketname>", keysuffixwithslash, new ByteArrayInputStream(new byte[0])); // 关闭 client ossclient.shutdown(); 提示 : - 创建模拟文件夹本质上来说是创建了一个名字以 "/" 结尾的文件 ; - 对于这个文件照样可以上传下载, 只是控制台会对以 "/" 结尾的文件以文件夹的方式展示 ; - 多级目录创建最后一级即可, 比如 dir1/dir2/dir3/, 创建 dir1/dir2/dir3/ 即可,dir1/ 19

21 dir1/dir2/ 不需要创建 ; - 更多内容请参考 (doc/[5]sdk/java-sdk/ 管理文件.md) 追加上传 简单上传, 分片上传, 断点续传上传, 创建的 Object 都是 Normal 类型, 这种 Object 在上传结束之后内容就是固定的, 只能读取, 不能修改 如果 Object 内容发生了改变, 只能重新上传同名的 Object 来覆盖之前的内容, 这也是 OSS 和普通文件系统使用的一个重大区别 正因为这种特性, 在很多应用场景下会很不方便, 典型比如视频监控 视频直播领域等, 视频数据在实时的不断产生 OSS 提供了用户通过追加上传 (Append Object) 的方式在一个 Object 后面直接追加内容的功能 通过这种方式操作的 Object 的类型为 Appendable Object, 而其他的方式上传的 Object 类型为 Normal Object 每次追加上传的数据都能够即时可读 您可以使用 OSSClient.appendObject 追加上传文件 AppendObjectResult appendobject(appendobjectrequest appendobjectrequest) AppendObjectRequest 可设置参数如下 : 参数作用方法 BucketName bucket 名称 setbucketname(string bucketname) Key object 名称 setkey(string key) InputStream File ObjectMetadata 待追加的内容,InputStream/File 二选一 待追加的内容,InputStream/File 二选一 指定 Object 的元信息, 第一次追加时有效 setinputstream(inputstream inputstream) setfile(file file) setmetadata(objectmetadata metadata) Position Object 追加位置 setposition(long position) AppendObjectResult 的参数如下 : 参数含义方法 nextposition objectcrc64 指明下一次请求应当提供的 position 实际上就是当前 Object 长度 Object 的 64 位 CRC 值 该 64 位 CRC 根据 ECMA-182 标准计算得出 Long getnextposition() String getobjectcrc64() 20

22 提示 : - 追加上传的完整代码请参考 :GitHub // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String content = "Hello OSS"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); AppendObjectRequest appendobjectrequest = new AppendObjectRequest("<yourBucketName>", "<yourkey>", new ByteArrayInputStream(content.getBytes())); // 第一次追加 appendobjectrequest.setposition(0l); AppendObjectResult appendobjectresult = ossclient.appendobject(appendobjectrequest); // 第二次追加 appendobjectrequest.setposition(appendobjectresult.getnextposition()); appendobjectresult = ossclient.appendobject(appendobjectrequest); // 第三次追加 appendobjectrequest.setposition(appendobjectresult.getnextposition()); appendobjectresult = ossclient.appendobject(appendobjectrequest); // 关闭 client ossclient.shutdown(); 提示 : - 追加上传的次数没有限制, 文件大小上限为 5GB 更大的文件请使用分片上传; - 追加类型的文件 (Append Object) 暂时不支持 copyobject 操作 断点续传上传 当上传大文件时, 如果网络不稳定或者程序崩溃了, 则整个上传就失败了 用户不得不重头再来, 这样做不仅浪费资源, 在网络不稳定的情况下, 往往重试多次还是无法完成上传 通过 OSSClient.uploadFile 接口来实现断点续传上传, 参数是 UploadFileRequest, 该请求有以下参数 : - bucket 存储空间名字, 必选参数, 通过构造方法设置 - key 上传到 OSS 的 Object 名字, 必选参数, 通过构造方法设置 - uploadfile 待上传的本地文件, 必选参数, 通过构造方法或 setuploadfile 设置 - partsize 分片大小, 从 100KB 到 5GB, 单位是 Byte, 可选参数, 默认 100K, 通过 setpartsize 设置 - tasknum 分片上传并发数, 可选参数, 默认为 1, 通过 settasknum 设置 21

23 - enablecheckpoint 上传是否开启断点续传, 可选参数, 默认断点续传功能关闭, 通过 setenablecheckpoint 设置 - checkpointfile 开启断点续传时, 需要在本地记录分片上传结果, 如果上传失败, 下次不会再上传已经成功的分片, 可选参数, 默认与待上传的本地文件同目录, 为 uploadfile.ucp, 可以通过 setcheckpointfile 设置 - objectmetadata,object 的元数据, 可选参数, 用户可以通过 setobjectmetadata 设置 - callback 上传成功后的回调, 可选参数, 用户可以通过 setcallback 设置 其实现的原理是将要上传的文件分成若干个分片分别上传, 最后所有分片都上传成功后, 完成整个文件的上传 在上传的过程中会记录当前上传的进度信息( 记录在 checkpoint 文件中 ), 如果上传过程中某一分片上传失败, 再次上传时会从 checkpoint 文件中记录的点继续上传 这要求再次调用时要指定与上次相同的 checkpoint 文件 上传完成后,checkpoint 文件会被删除 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 设置断点续传请求 UploadFileRequest uploadfilerequest = new UploadFileRequest("<yourBucketName>", "<yourkey>"); // 指定上传的本地文件 uploadfilerequest.setuploadfile("<yourlocalfile>"); // 指定上传并发线程数 uploadfilerequest.settasknum(5); // 指定上传的分片大小 uploadfilerequest.setpartsize(1 * 1024 * 1024); // 开启断点续传 uploadfilerequest.setenablecheckpoint(true); // 断点续传上传 ossclient.uploadfile(uploadfilerequest); // 关闭 client ossclient.shutdown(); 提示 : - 断点续传是分片上传的封装和加强, 是用分片上传实现的 ; - 文件较大或网络环境较差时, 推荐使用分片上传 ; - 断点续传支持指定 ObjectMetadata, 支持上传完成回调 callback 分片上传 对于大文件上传, 可以切分成片上传 用户可以在如下的应用场景内 ( 但不仅限于此 ), 使用分片上传 22

24 (Multipart Upload) 模式 : - 需要支持断点上传 - 上传超过 100MB 大小的文件 - 网络条件较差, 和 OSS 的服务器之间的链接经常断开 - 上传文件之前, 无法确定上传文件的大小 分片上传 (Multipart Upload) 分为如下 3 个步骤 : - 初始化一个分片上传任务 (InitiateMultipartUpload) - 逐个或并行上传分片 (UploadPart) - 完成分片上传 (CompleteMultipartUpload) 或取消分片上传 (AbortMultipartUpload) 分步完成 Multipart Upload 提示 : - 分片上传的完整代码请参考 :GitHub 初始化 Multipart Upload 使用 Multipart Upload 模式传输数据前, 必须先通知 OSS 初始化一个 Multipart Upload 事件 该操作会返回一个 OSS 服务器创建的全局唯一的 Upload ID, 用于标识本次 Multipart Upload 事件 用户可以根据这个 ID 来发起相关的操作, 如中止 Multipart Upload 查询 Multipart Upload 等 调用 OSSClient.initiateMultipartUpload 初始化一个分片上传事件 : // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; String key = "yourkey"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, key); InitiateMultipartUploadResult result = ossclient.initiatemultipartupload(request); String uploadid = result.getuploadid(); 提示 : - 用 InitiateMultipartUploadRequest 指定上传文件的名字和所属存储空间 (Bucket); - 在 InitiateMultipartUploadRequest 中, 您也可以设置 ObjectMeta; - initiatemultipartupload 的返回结果中含有 UploadId, 它是区分分片上传事件的唯一标识, 在 23

25 后面的操作中将用到它 上传分片 初始化一个 Multipart Upload 之后, 可以根据指定的 Object 名和 Upload ID 来分片 (Part) 上传数据 每一个上传的 Part 都有一个标识它的号码 -- 分片号 (part number, 范围是 1~10,000) 对于同一个 Upload ID, 该分片号不但唯一标识这一块数据, 也标识了这块数据在整个文件内的相对位置 如果你用同一个分片号码, 上传了新的数据, 那么 OSS 上已有的这个分片的数据将被覆盖 除了最后一块 Part 以外, 其他的 part 最小为 100KB; 最后一块 Part 没有大小限制 每个分片不需要按顺序上传, 甚至可以在不同进程 不同机器上上传,OSS 会按照分片号排序组成大文件 调用 OSSClient.uploadPart 上传分片 : List<PartETag> partetags = new ArrayList<PartETag>(); InputStream instream = new FileInputStream(new File("<localFile>")); UploadPartRequest uploadpartrequest = new UploadPartRequest(); uploadpartrequest.setbucketname(bucketname); uploadpartrequest.setkey(key); uploadpartrequest.setuploadid(uploadid); uploadpartrequest.setinputstream(instream); // 设置分片大小, 除最后一个分片外, 其它分片要大于 100KB uploadpartrequest.setpartsize(100 * 1024); // 设置分片号, 范围是 1~10000, uploadpartrequest.setpartnumber(1); UploadPartResult uploadpartresult = ossclient.uploadpart(uploadpartrequest); partetags.add(uploadpartresult.getpartetag()); 注意 : - UploadPart 方法要求除最后一个 Part 以外, 其他的 Part 大小都要大于 100KB 但是 Upload Part 接口并不会立即校验上传 Part 的大小 ( 因为不知道是否为最后一块 ); 只有当 Complete Multipart Upload 的时候才会校验 - OSS 会将服务器端收到 Part 数据的 MD5 值放在 ETag 头内返回给用户 - 为了保证数据在网络传输过程中不出现错误,SDK 会自动设置 Content-MD5,OSS 会计算上传数据的 MD5 值与 SDK 计算的 MD5 值比较, 如果不一致返回 InvalidDigest 错误码 - Part 号码的范围是 1~10000 如果超出这个范围,OSS 将返回 InvalidArgument 的错误码 - 每次上传 part 时都要把流定位到此次上传块开头所对应的位置 - 每次上传 part 之后,OSS 的返回结果会包含一个 PartETag 对象, 他是上传块的 ETag 与块编号 (PartNumber) 的组合, - 在后续完成分片上传的步骤中会用到它, 因此我们需要将其保存起来 一般来讲我们将这些 PartETag 对象保存到 List 中 完成分片上传 所有分片上传完成后, 需要调用 Complete Multipart Upload 来完成整个文件的 Multipart Upload 在执行该 24

26 操作时, 需要提供所有有效的分片列表 ( 包括分片号和分片 ETAG);OSS 收到提交的分片列表后, 会逐一验证 每个分片的有效性 当所有的数据 Part 验证通过后,OSS 将把这些分片组合成一个完整的 Object 调用 OSSClient.completeMultipartUpload 完成分片上传 : Collections.sort(partETags, new public int compare(partetag p1, PartETag p2) return p1.getpartnumber() - p2.getpartnumber(); ); CompleteMultipartUploadRequest completemultipartuploadrequest = new CompleteMultipartUploadRequest(bucketName, key, uploadid, partetags); ossclient.completemultipartupload(completemultipartuploadrequest); 注意 : - 上面代码中的 partetags 就是进行分片上传中保存的 partetag 的列表, 它必须是按分片号升序排序 ; - 分片可以是不连续的 取消分片上传事件 该接口可以根据 Upload ID 中止对应的 Multipart Upload 事件 当一个 Multipart Upload 事件被中止后, 就不 能再使用这个 Upload ID 做任何操作, 已经上传的 Part 数据也会被删除 调用 OSSClient.abortMultipartUpload 取消分片上传事件 : // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 上传字符串 String content = "Hello OSS"; ossclient.putobject("<yourbucketname>", "<yourkey>", new ByteArrayInputStream(content.getBytes())); // 取消分片上传, 其中 uploadid 来自于 initiatemultipartupload AbortMultipartUploadRequest abortmultipartuploadrequest = new AbortMultipartUploadRequest("<yourBucketName>", "<yourkey>", "<uploadid>"); ossclient.abortmultipartupload(abortmultipartuploadrequest); // 关闭 client ossclient.shutdown(); 25

27 获取已上传的分片 获取上传的分片可以罗列出指定 Upload ID 所属的所有已经上传成功的分片 可以调用 OSSClient.listParts 获取某个上传事件所有已上传分片 listparts 的可设置的参数如下 : 参数作用方法 UploadId MaxParts PartNumberMarker Upload Id,initiateMultipartUpload 返回的结果获取 OSS 响应中的最大 Part 数目, 即分页时每一页中 Part 数目 指定 List 的起始位置, 只有 Part Number 数目大于该参数的 Part 会被列出 ListPartsRequest.setUploadId (String uploadid) ListPartsRequest.setMaxParts (int maxparts) ListPartsRequest.setPartNum bermarker(integer partnumbermarker) 简单列举 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 列举已上传的分片, 其中 uploadid 来自于 initiatemultipartupload ListPartsRequest listpartsrequest = new ListPartsRequest("<yourBucketName>", "<yourkey>", "<uploadid>"); PartListing partlisting = ossclient.listparts(listpartsrequest); for (PartSummary part : partlisting.getparts()) // 分片号, 上传时候指定 part.getpartnumber(); // 分片数据大小 part.getsize(); // Part 的 ETag part.getetag(); // Part 的最后修改上传 part.getlastmodified(); // 关闭 client ossclient.shutdown(); 提示 : - 默认情况下, 如果存储空间中的分片上传事件的数量大于 1000, 则只会返回 1000 个 Multipart Upload 信息, 且返回结果中 IsTruncated 为 false, 并返回 NextPartNumberMarker 作为下此读取的起点 26

28 - 如果没有一次性获取所有的上传分片, 可以采用分页列举的方式 获取所有已上传分片 默认情况下,listParts 只能列举 1000 个分片, 如果分片数量大于 1000, 列举所有分片请参考如下示例 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 列举所有已上传的分片 PartListing partlisting; ListPartsRequest listpartsrequest = new ListPartsRequest("<yourBucketName>", "<yourkey>", "<uploadid>"); do partlisting = ossclient.listparts(listpartsrequest); for (PartSummary part : partlisting.getparts()) // 分片号, 上传时候指定 part.getpartnumber(); // 分片数据大小 part.getsize(); // Part 的 ETag part.getetag(); // Part 的最后修改上传 part.getlastmodified(); listpartsrequest.setpartnumbermarker(partlisting.getnextpartnumbermarker()); while (partlisting.istruncated()); // 关闭 client ossclient.shutdown() 分页获取所有分片 默认情况下,listParts 一次列举 1000 个分片, 上面的获取所有已上传分片也是分页的一种特殊情况, 每页 1000 个分片 如果需要指定每页分片的数量, 即一次列举的分片数量, 请参考以下代码 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 27

29 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 分页列举已上传的分片 PartListing partlisting; ListPartsRequest listpartsrequest = new ListPartsRequest("<yourBucketName>", "<yourkey>", "<uploadid>"); // 每页 100 个分片 listpartsrequest.setmaxparts(100); do partlisting = ossclient.listparts(listpartsrequest); for (PartSummary part : partlisting.getparts()) // 分片号, 上传时候指定 part.getpartnumber(); // 分片数据大小 part.getsize(); // Part 的 ETag part.getetag(); // Part 的最后修改上传 part.getlastmodified(); listpartsrequest.setpartnumbermarker(partlisting.getnextpartnumbermarker()); while (partlisting.istruncated()); // 关闭 client ossclient.shutdown(); 获取存储空间内所有分片上传事件 列举分片上传事件可以罗列出所有执行中的分片上传事件, 即已经初始化的尚未 Complete 或者 Abort 的分片上 传事件 列举分片上传的可设置的参数如下 : 参数作用方法 Prefix Delimiter MaxUploads KeyMarker 限定返回的文件名 (object) 必须以 Prefix 作为前缀 注意使用 Prefix 查询时, 返回的文件名 (Object) 中仍会包含 Prefix 用于对 Object 名字进行分组的字符 所有名字包含指定的前缀且第一次出现 delimiter 字符之间的 object 作为一组元素 限定此次返回分片上传事件的最大数目, 默认为 1000,MaxUploads 取值不能大于 1000 所有 Object 名字的字典序大于 KeyMarker 参数值的 Multipart 事件 可以与 UploadIdMarker 参数一同使用来指定返回结果的起始位置 ListMultipartUploadsRequest.setPrefix(String prefix) ListMultipartUploadsRequest.setDelimiter(String delimiter) ListMultipartUploadsRequest.setMaxUploads(Integer maxuploads) ListMultipartUploadsRequest.setKeyMarker(String keymarker) 28

30 UploadIdMarker 与 KeyMarker 参数一同使用来指定返回结果的起始位置 如果 KeyMarker 参数未设置, 则 OSS 忽略 UploadIdMarker 参数 如果 KeyMarker 参数被设置, 查询结果中包含 : 所有 Object 名字的字典序大于 KeyMarker 参数值和 Object 名字等于 KeyMarker 参数值且 Upload ID 比 UploadIdMarker 参数值大的分片上传事件 ListMultipartUploadsRequest.setUploadIdMarker(String uploadidmarker) 调用 OSSClient.listMultipartUploads 获取存储空间内分片上传事件 简单列举分片上传事件 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 列举分片上传事件 ListMultipartUploadsRequest listmultipartuploadsrequest = new ListMultipartUploadsRequest(bucketName); MultipartUploadListing multipartuploadlisting = ossclient.listmultipartuploads(listmultipartuploadsrequest); for (MultipartUpload multipartupload : multipartuploadlisting.getmultipartuploads()) // Upload Id multipartupload.getuploadid(); // Key multipartupload.getkey(); // Date of initiate multipart upload multipartupload.getinitiated(); // 关闭 client ossclient.shutdown(); 提示 : - 默认情况下, 如果存储空间中的分片上传事件的数量大于 1000, 则只会返回 1000 个文件, 且返回结果中 IsTruncated 为 false, 返回 NextKeyMarker 和 NextUploadIdMarker 作为下次读取的起点 - 如果没有一次性获取所有的上传事件, 可以采用分页列举的方式 29

31 列举全部上传事件 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 列举分片上传事件 MultipartUploadListing multipartuploadlisting; ListMultipartUploadsRequest listmultipartuploadsrequest = new ListMultipartUploadsRequest(bucketName); do multipartuploadlisting = ossclient.listmultipartuploads(listmultipartuploadsrequest); for (MultipartUpload multipartupload : multipartuploadlisting.getmultipartuploads()) // Upload Id multipartupload.getuploadid(); // Key multipartupload.getkey(); // Date of initiate multipart upload multipartupload.getinitiated(); listmultipartuploadsrequest.setkeymarker(multipartuploadlisting.getnextkeymarker()); listmultipartuploadsrequest.setuploadidmarker(multipartuploadlisting.getnextuploadidmarker()); while (multipartuploadlisting.istruncated()); // 关闭 client ossclient.shutdown(); 分页列举全部上传事件 默认情况下,listMultipartUploads 一次列举 1000 个上传事件, 上面的列举全部上传事件是分页的一种特殊情 况, 每页 1000 个事件 如果需要指定每页事件的数量, 即一次列举的事件数量, 请参考以下代码 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 列举分片上传事件 MultipartUploadListing multipartuploadlisting; 30

32 ListMultipartUploadsRequest listmultipartuploadsrequest = new ListMultipartUploadsRequest(bucketName); // 每个页中事件数目 listmultipartuploadsrequest.setmaxuploads(50); do multipartuploadlisting = ossclient.listmultipartuploads(listmultipartuploadsrequest); for (MultipartUpload multipartupload : multipartuploadlisting.getmultipartuploads()) // Upload Id multipartupload.getuploadid(); // Key multipartupload.getkey(); // Date of initiate multipart upload multipartupload.getinitiated(); listmultipartuploadsrequest.setkeymarker(multipartuploadlisting.getnextkeymarker()); listmultipartuploadsrequest.setuploadidmarker(multipartuploadlisting.getnextuploadidmarker()); while (multipartuploadlisting.istruncated()); // 关闭 client ossclient.shutdown(); Post 上传 OSS Java SDK 目前暂不支持 Post 上传 Object, 示例提供了 PostObject 的示例程序, 您可以直接使用或再示例基础上修改, 请参考 PostObjectSample 如果您对 Put Object 有疑惑请参考 OSS Post Object 的 API, 请参考 PostObject 让您在修改或实现 Post Object 过程中有问题或疑问, 请参考 JAVA 模拟 PostObject 表单上传 OSS 上传进度条 OSS Java sdk 支持进度条功能, 指示上传 / 下载的进度 下面的代码以 OSSClient.putObject 为例, 说明进度条 功能的使用 提示 : - 上传进度条的完整代码请参考 :GitHub static class PutObjectProgressListener implements ProgressListener private long byteswritten = 0; private long totalbytes = -1; private boolean succeed = public void progresschanged(progressevent progressevent) long bytes = progressevent.getbytes(); ProgressEventType eventtype = progressevent.geteventtype(); 31

33 switch (eventtype) case TRANSFER_STARTED_EVENT: System.out.println("Start to upload..."); break; case REQUEST_CONTENT_LENGTH_EVENT: this.totalbytes = bytes; System.out.println(this.totalBytes + " bytes in total will be uploaded to OSS"); break; case REQUEST_BYTE_TRANSFER_EVENT: this.byteswritten += bytes; if (this.totalbytes!= -1) int percent = (int)(this.byteswritten * / this.totalbytes); System.out.println(bytes + " bytes have been written at this time, upload progress: " + percent + "%(" + this.byteswritten + "/" + this.totalbytes + ")"); else System.out.println(bytes + " bytes have been written at this time, upload ratio: unknown" + "(" + this.byteswritten + "/...)"); break; case TRANSFER_COMPLETED_EVENT: this.succeed = true; System.out.println("Succeed to upload, " + this.byteswritten + " bytes have been transferred in total"); break; case TRANSFER_FAILED_EVENT: System.out.println("Failed to upload, " + this.byteswritten + " bytes have been transferred"); break; default: break; public boolean issucceed() return succeed; public static void main(string[] args) String endpoint = " String accesskeyid = "<accesskeyid>"; String accesskeysecret = "<accesskeysecret>"; String bucketname = "<bucketname>"; String key = "object-get-progress-sample"; OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); try // 带进度条的上传 ossclient.putobject(new PutObjectRequest(bucketName, key, new FileInputStream("<yourLocalFile>")). <PutObjectRequest>withProgressListener(new PutObjectProgressListener())); catch (Exception e) e.printstacktrace(); ossclient.shutdown(); 32

34 提示 : - putobject/getobject/uploadpart 都支持进度条功能 ; - uploadfile/downloadfile 不支持进度条功能 上传回调 OSS 在上传文件完成的时候可以提供回调 (Callback) 给应用服务器 用户只需要在发送给 OSS 的请求中携带相应的 Callback 参数, 即能实现回调 现在支持 CallBack 的接口有 :PutObject PostObject CompleteMultipartUpload 上传回调的一种典型应用场景是与授权第三方上传同时使用, 客户端在上传文件到 OSS 的时候指定到服务器端的回调, 当客户端的上传任务在 OSS 执行完毕之后,OSS 会向应用服务器端主动发起 HTTP 请求进行回调, 这样服务器端就可以及时得到上传完成的通知从而可以完成诸如数据库修改等操作, 当回调请求接收到服务器端的响应之后 OSS 才会将状态返回给客户端 您想了解上传回调的更详细信息, 请参考上传回调 下面以 PutObject 为例说明上传回调的用法 提示 : - 上传回调的完整代码请参考 :GitHub // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; // 您的回调服务器地址, 如 或 String callbackurl = "<yourcallbackserverurl>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); String content = "Hello OSS"; PutObjectRequest putobjectrequest = new PutObjectRequest(bucketName, "key", new ByteArrayInputStream(content.getBytes())); // 上传回调参数 Callback callback = new Callback(); callback.setcallbackurl(callbackurl); callback.setcallbackhost("oss-cn-hangzhou.aliyuncs.com"); callback.setcallbackbody("\\\"mimetype\\\":$mimetype,\\\"size\\\":$size"); callback.setcalbackbodytype(calbackbodytype.json); callback.addcallbackvar("x:var1", "value1"); callback.addcallbackvar("x:var2", "value2"); putobjectrequest.setcallback(callback); 33

35 PutObjectResult putobjectresult = ossclient.putobject(putobjectrequest); // 读取上传回调返回的消息内容 byte[] buffer = new byte[1024]; putobjectresult.getcallbackresponsebody().read(buffer); // 一定要 close, 否则会造成连接资源泄漏 putobjectresult.getcallbackresponsebody().close(); // 关闭 client ossclient.shutdown(); 提示 : - 上传回调的中的参数, 请参考上传回调中的说明 ; - 上传回调返回的消息体一定要 close, 否则会造成连接资源泄漏 下载文件 OSS Java SDK 提供了丰富的文件下载接口, 用户可以通过以下方式从 OSS 中下载文件 : - 流式下载 - 下载到本地文件 - 断点续传下载 - 范围下载 流式下载 在进行大文件下载时, 往往不希望一次性处理全部内容, 而是希望流式地处理, 一次处理一部分内容 提示 : - 流式下载的完整代码请参考 :GitHub // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); OSSObject ossobject = ossclient.getobject(bucketname, "yourkey"); 34

36 // 读 Object 内容 System.out.println("Object content:"); BufferedReader reader = new BufferedReader(new InputStreamReader(ossObject.getObjectContent())); while (true) String line = reader.readline(); if (line == null) break; System.out.println("\n" + line); reader.close(); // 关闭 client ossclient.shutdown(); 提示 : - OSSObject 实例包含文件所在的存储空间 (Bucket) 文件的名称 Object Metadata 以及一个输入流 ; - 通过操作输入流将文件的内容读取到文件或者内存中 而 Object Metadata 包含 ETag HTTP Header 及自定义的元信息 ; - OSSClient.getObject 获取的流一定要显示的 close, 否则会造成资源泄露 下载到本地文件 把 Object 的内容下载到指定的本地文件中 如果指定的本地文件不存在则会新建 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 下载 object 到文件 ossclient.getobject(new GetObjectRequest(bucketName, "<yourkey>"), new File("<yourLocalFile>")); // 关闭 client ossclient.shutdown(); 范围下载 如果 OSS 文件较大, 并且只需要其中一部分数据, 可以使用范围下载, 下载指定范围的数据 如果指定的下载 范围是 0-100, 则返回第 0 到第 100 个字节的数据, 包括第 100 个, 共 101 字节的数据, 即 [0, 100] 如果指定 的范围无效, 则传送整个文件 35

37 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); GetObjectRequest getobjectrequest = new GetObjectRequest(bucketName, "<yourkey>"); // 获取 0~1000 字节范围内的数据, 包括 0 和 1000, 共 1001 个字节的数据 getobjectrequest.setrange(0, 1000); // 范围下载 OSSObject ossobject = ossclient.getobject(getobjectrequest); // 读取数据 byte[] buf = new byte[64]; InputStream in = ossobject.getobjectcontent(); for (int n = 0; n!= -1; ) n = in.read(buf, 0, buf.length); // InputStream 数据读完成后, 一定要 close, 否则会造成连接泄漏 in.close(); // 关闭 client ossclient.shutdown(); 断点续传下载 当下载大文件时, 如果网络不稳定或者程序崩溃了, 则整个下载就失败了 用户不得不重头再来, 这样做不仅浪费资源, 在网络不稳定的情况下, 往往重试多次还是无法完成下载 通过 OSSClient.downloadFile 接口来实现断点续传分片下载, 参数是 DownloadFileRequest, 该请求有以下参数 : - bucket 存储空间名字, 必选参数, 通过构造方法设置 - key 下载到 OSS 的 Object 名字, 必选参数, 通过构造方法设置 - downloadfile 本地文件, 下载到该文件, 可选参数, 默认是 key, 通过构造方法或 setdownloadfile 设置 - partsize 分片大小, 从 1B 到 5GB, 单位是 Byte, 可选参数, 默认 100K, 通过 setpartsize 设置 - tasknum 分片下载并发数, 可选参数, 默认为 1, 通过 settasknum 设置 - enablecheckpoint 下载是否开启断点续传, 可选参数, 默认断点续传功能关闭, 通过 setenablecheckpoint 设置 - checkpointfile 开启断点续传时, 需要在本地记录分片下载结果, 如果下载失败, 下次不会再下载已经成功的分片, 可选参数, 默认与 downloadfile 同目录, 为 downloadfile.ucp, 可以通过 setcheckpointfile 设置其实现的原理是将要下载的 Object 分成若干个分片分别下载, 最后所有分片都下载成功后, 完成整个文件的下 36

38 载 在下载的过程中会记录当前下载的进度信息 ( 记录在 checkpoint 文件中 ) 和已下载的分片, 如果下载过 程中某一分片下载失败, 再次下载时会从 checkpoint 文件中记录的点继续下载 这要求再次调用时要指定与上 次相同的 checkpoint 文件 下载完成后,checkpoint 文件会被删除 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 下载请求,10 个任务并发下载, 启动断点续传 DownloadFileRequest downloadfilerequest = new DownloadFileRequest("bucketName", "key"); downloadfilerequest.setdownloadfile("downloadfile"); downloadfilerequest.settasknum(10); downloadfilerequest.setenablecheckpoint(true); // 下载文件 DownloadFileResult downloadres = ossclient.downloadfile(downloadfilerequest); // 下载成功时, 会返回文件的元信息 downloadres.getobjectmetadata(); // 关闭 client ossclient.shutdown(); 限定条件下载 下载文件时, 可以指定一个或多个限定条件, 满足限定条件时下载, 不满足时报错, 不下载文件 可以使用的 限定条件如下 : 参数 If-Modified-Since If-Unmodified-Since If-Match If-None-Match 说明 如果指定的时间早于实际修改时间, 则正常传送 否则返回错误 如果传入参数中的时间等于或者晚于文件实际修改时间, 则正常传输文件 ; 否则返回错误 如果传入期望的 ETag 和 object 的 ETag 匹配, 则正常传输 ; 否则返回错误 如果传入的 ETag 值和 Object 的 ETag 不匹配, 则正常传输 ; 否则返回错误 注意 : - 如果 If-Modified-Since 设定的时间不符合规范, 直接返回文件, 并返回 200 OK; - If-Modified-Since 和 If-Unmodified-Since 可以同时存在,If-Match 和 If-None-Match 也可以 37

39 同时存在 ; - 如果包含 If-Unmodified-Since 并且不符合或者包含 If-Match 并且不符合, 返回 412 precondition failed; - 如果包含 If-Modified-Since 并且不符合或者包含 If-None-Match 并且不符合, 返回 304 Not Modified // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; String bucketname = "<yourbucketname>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); GetObjectRequest request = new GetObjectRequest(bucketName, "<yourkey>"); request.setmodifiedsinceconstraint(new Date()); // 下载 object 到文件 ossclient.getobject(request, new File("<yourLocalFile>")); // 关闭 client ossclient.shutdown(); 提示 : - ETag 的值可以通过 OSSClient.getObjectMetadata 获取 ; - OSSClient.getObject,OSSClient.downloadFile 都支持限定条件 下载进度条 OSS Java sdk 支持进度条功能, 指示上传 / 下载的进度 下面的代码以 OSSClient.getObject 为例, 说明进度条 功能的使用 提示 : - 下载进度条的完整代码请参考 :GitHub static class GetObjectProgressListener implements ProgressListener private long bytesread = 0; private long totalbytes = -1; private boolean succeed = public void progresschanged(progressevent progressevent) 38

40 long bytes = progressevent.getbytes(); ProgressEventType eventtype = progressevent.geteventtype(); switch (eventtype) case TRANSFER_STARTED_EVENT: System.out.println("Start to download..."); break; case RESPONSE_CONTENT_LENGTH_EVENT: this.totalbytes = bytes; System.out.println(this.totalBytes + " bytes in total will be downloaded to a local file"); break; case RESPONSE_BYTE_TRANSFER_EVENT: this.bytesread += bytes; if (this.totalbytes!= -1) int percent = (int)(this.bytesread * / this.totalbytes); System.out.println(bytes + " bytes have been read at this time, download progress: " + percent + "%(" + this.bytesread + "/" + this.totalbytes + ")"); else System.out.println(bytes + " bytes have been read at this time, download ratio: unknown" + "(" + this.bytesread + "/...)"); break; case TRANSFER_COMPLETED_EVENT: this.succeed = true; System.out.println("Succeed to download, " + this.bytesread + " bytes have been transferred in total"); break; case TRANSFER_FAILED_EVENT: System.out.println("Failed to download, " + this.bytesread + " bytes have been transferred"); break; default: break; public boolean issucceed() return succeed; public static void main(string[] args) String endpoint = " String accesskeyid = "<accesskeyid>"; String accesskeysecret = "<accesskeysecret>"; String bucketname = "<bucketname>"; String key = "object-get-progress-sample"; OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); try // 带进度条的下载 client.getobject(new GetObjectRequest(bucketName, key). <GetObjectRequest>withProgressListener(new GetObjectProgressListener()), new File("<yourLocalFile>")); catch (Exception e) e.printstacktrace(); 39

41 ossclient.shutdown(); 提示 : - putobject/getobject/uploadpart 都支持进度条功能 ; - uploadfile/downloadfile 不支持进度条功能 管理文件 在 OSS 中, 用户可以通过一系列的接口管理存储空间 (Bucket) 中的文件 (Object), 比如 SetObjectAcl,GetObjectAcl,ListObjects,DeleteObject,CopyObject,DoesObjectExist 等 Object 的 名字又称为 key 或 object key Object 是否存在 通过 OSSClient.doesObjectExist 判断文件 (object) 是否存在 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // Object 是否存在 boolean found = ossclient.doesobjectexist("<bucketname>", "<key>") // 关闭 client ossclient.shutdown(); Object ACL Object 有四种访问权限 :Default( 默认 ),Private( 私有读写 ), PublicRead( 公共读私有写 ), PublicReadWrite( 公共读写 ), 含义如下 : 权限 默认 私有读写 描述 Objec 是遵循 Bucket 的读写权限, 即 Bucket 是什么权限,Object 就是什么权限,Object 的默认权限 Object 是私有资源, 即只有该 Object 的 Owner 拥有该 Object 的读写权限, 其他的用户没有权限操作 40

42 该 Object 公共读私有写 公共读写 Object 是公共读资源, 即非 Object Owner 只有 Object 的读权限, 而 Object Owner 拥有该 Object 的读写权限 Object 是公共读写资源, 即所有用户拥有对该 Object 的读写权限 Object 的权限优先级高于 Bucket 例如 Bucket 是 private 的, 而 Object ACL 是公共读写, 则访问这个 Object 时, 先判断 Object 的 ACL, 所有用户都拥有这个 Object 的访问权限, 即使这个 Bucket 是 private 如果某个 Object 从来没设置过 ACL, 则访问权限遵循 Bucket ACL 设置 Object ACL 您可以通过 OSSClient.setObjectAcl 设置 Object 的权限 权限私有读写公共读私有写公共读写 Java SDK 对应值 CannedAccessControlList.Private CannedAccessControlList.PublicRead CannedAccessControlList.PublicReadWrite 下面代码为 Object 设置 ACL: // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 设置 Object 权限 ossclient.setobjectacl("<bucketname>", "<key>", CannedAccessControlList.PublicRead) // 关闭 client ossclient.shutdown(); 获取 Object ACL 您可以通过 OSSClient.getObjectAcl 获取 Object 的权限 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; 41

43 // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 读取 Object ACL ObjectAcl objectacl = ossclient.getobjectacl("<bucketname>", "<key>"); System.out.println(objectAcl.getPermission().toString()); // 关闭 client ossclient.shutdown(); 获取文件元信息 (Object Meta) 文件元信息 (Object Meta), 是对用户上传到 OSS 的文件的属性描述, 分为两种 :HTTP 标准属性 (HTTP Headers) 和 User Meta( 用户自定义元信息 ) 文件元信息可以在各种方式上传或者拷贝文件时进行设置 更多文件元信息的介绍, 请参看文件元信息 获取文件元信息可以使用 OSSClient.getSimplifiedObjectMeta 或 OSSClient.getObjectMetadata getsimplifiedobjectmeta 只能获取文件的 ETag Size( 文件大小 ) LastModified( 最后修改时间 ); getobjectmetadata 能获取文件的全部元数据 getsimplifiedobjectmeta 更轻量 更快 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 获取文件的部分元信息 SimplifiedObjectMeta objectmeta = ossclient.getsimplifiedobjectmeta("<bucketname>", "<key>"); System.out.println(objectMeta.getSize()); System.out.println(objectMeta.getETag()); System.out.println(objectMeta.getLastModified()); // 获取文件的全部元信息 ObjectMetadata metadata = ossclient.getobjectmetadata("<bucketname>", "<key>"); System.out.println(metadata.getContentType()); System.out.println(metadata.getLastModified()); System.out.println(metadata.getExpirationTime()); // 关闭 client ossclient.shutdown(); 列出存储空间中的文件 可以通过 OSSClient.listObjects 列出 bucket 里的 Objects listobjects 有三类参数格式 : - ObjectListing listobjects(string bucketname) 42

44 - 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 CommonPrefixes EncodingType 指明是否所有的结果都已经返回 如果请求中指定了 delimiter 参数, 则返回的包含 CommonPrefixes 元素 该元素标明以 delimiter 结尾, 并有共同前缀的 object 的集合 指明返回结果中编码使用的类型 boolean istruncated() List<String> getcommonprefixes() String getencodingtype() 提示 : - listobjects 的完整代码请参考 :GitHub 简单列举 列举出 Bucket 下的 Object, 最多 100 条 object // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); 43

45 // 列举 Object ObjectListing objectlisting = ossclient.listobjects("<bucketname>", "<KeyPrifex>"); List<OSSObjectSummary> sums = objectlisting.getobjectsummaries(); for (OSSObjectSummary s : sums) System.out.println("\t" + s.getkey()); // 关闭 client ossclient.shutdown(); 列举出 Bucket 下的指定前缀的 Object, 最多 100 条 object ObjectListing objectlisting = ossclient.listobjects("<bucketname>", "<KeyPrifex>"); List<OSSObjectSummary> sums = objectlisting.getobjectsummaries(); for (OSSObjectSummary s : sums) System.out.println("\t" + s.getkey()); 通过 ListObjectsRequest 列出文件 可以通过设置 ListObjectsReques 的参数实现各种灵活的查询功能 ListObjectsReques 的可设置的参数如下 : 参数作用方法 Prefix Delimiter Marker MaxKeys EncodingType 限定返回的 object key 必须以 prefix 作为前缀 是一个用于对 Object 名字进行分组的字符 所有名字包含指定的前缀且第一次出现 delimiter 字符之间的 object 作为一组元素 -- CommonPrefixes 设定结果从 marker 之后按字母排序的第一个开始返回 限定此次返回 object 的最大数, 如果不设定, 默认为 100,max-keys 取值不能大于 1000 请求响应体中 Object 名称采用的编码方式, 目前支持 url setprefix(string prefix) setdelimiter(string delimiter) setmarker(string marker) setmaxkeys(integer maxkeys) setencodingtype(string encodingtype) 指定最大返回条数 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; 44

46 // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); final int maxkeys = 30; // 列举 Object ObjectListing objectlisting = ossclient.listobjects(new ListObjectsRequest("<bucketName>").withMaxKeys(maxKeys)); List<OSSObjectSummary> sums = objectlisting.getobjectsummaries(); for (OSSObjectSummary s : sums) System.out.println("\t" + s.getkey()); // 关闭 client ossclient.shutdown(); 返回指定前缀的 object 最多返回 100 条 final String keyprefix = "<keyprefix>" ObjectListing objectlisting = ossclient.listobjects(new ListObjectsRequest("<bucketName>").withPrefix(keyPrefix)); List<OSSObjectSummary> sums = objectlisting.getobjectsummaries(); for (OSSObjectSummary s : sums) System.out.println("\t" + s.getkey()); 从指定 Object 后返回 不包括指定的 Object, 最多返回 100 条 final String keymarker = "<keymarker>" ObjectListing objectlisting = ossclient.listobjects(new ListObjectsRequest("<bucketName>").withMarker(keyMarker)); List<OSSObjectSummary> sums = objectlisting.getobjectsummaries(); for (OSSObjectSummary s : sums) System.out.println("\t" + s.getkey()); 分页获取所有 Object 分页获取所有 Object, 每页 maxkeys 条 Object final int maxkeys = 30; String nextmarker = null; do objectlisting = ossclient.listobjects(new ListObjectsRequest("<bucketName>").withMarker(nextMarker).withMaxKeys(maxKeys)); 45

47 List<OSSObjectSummary> sums = objectlisting.getobjectsummaries(); for (OSSObjectSummary s : sums) System.out.println("\t" + s.getkey()); nextmarker = objectlisting.getnextmarker(); while (objectlisting.istruncated()); 分页获取所有特定 Object 后的 Object 分页获取所有特定 Object 后的 Object, 每页 maxkeys 条 Object final int maxkeys = 30; String nextmarker = "<nextmarker>"; do objectlisting = ossclient.listobjects(new ListObjectsRequest("<bucketName>").withMarker(nextMarker).withMaxKeys(maxKeys)); List<OSSObjectSummary> sums = objectlisting.getobjectsummaries(); for (OSSObjectSummary s : sums) System.out.println("\t" + s.getkey()); nextmarker = objectlisting.getnextmarker(); while (objectlisting.istruncated()); 分页所有获取指定前缀的 Object 分页所有获取指定前缀的 Object, 每页 maxkeys 条 Object final int maxkeys = 30; final String keyprefix = "<keyprefix>"; String nextmarker = "<nextmarker>"; do objectlisting = ossclient.listobjects(new ListObjectsRequest("<bucketName>"). withprefix(keyprefix).withmarker(nextmarker).withmaxkeys(maxkeys)); List<OSSObjectSummary> sums = objectlisting.getobjectsummaries(); for (OSSObjectSummary s : sums) System.out.println("\t" + s.getkey()); nextmarker = objectlisting.getnextmarker(); while (objectlisting.istruncated()); 模拟文件夹功能 46

48 OSS 是没有文件夹这个概念的, 所有元素都是以 Object 来存储 创建模拟文件夹本质上来说是创建了一个 size 为 0 的 Object 对于这个 Object 可以上传下载, 只是控制台会对以 "/" 结尾的 Object 以文件夹的方式展示 您可以通过 Delimiter 和 Prefix 参数的配合模拟出文件夹功能 Delimiter 和 Prefix 的组合效果是这样的 : - 如果把 Prefix 设为某个文件夹名, 就可以罗列以此 Prefix 开头的文件, 即该文件夹下递归的所有的文件和子文件夹 ( 目录 ) 文件名在 Contents 中显示 - 如果再把 Delimiter 设置为 "/" 时, 返回值就只罗列该文件夹下的文件和子文件夹 ( 目录 ), 该文件夹下的子文件名 ( 目录 ) 返回在 CommonPrefixes 部分, 子文件夹下递归的文件和文件夹不被显示 提示 : - 模拟文件更新详细的说明, 请参见文件夹模拟功能 ; - 创建文件的完整代码请参考 :GitHub 假设 Bucket 中有 4 个文件 : oss.jpg, fun/test.jpg, fun/movie/001.avi, fun/movie/007.avi, "/" 作为 文件夹的分隔符 下面的示例展示了如何模拟文件夹功能 列出存储空间内所有文件 当我们需要获取存储空间下的所有文件时, 可以这样写 : // 构造 ListObjectsRequest 请求 ListObjectsRequest listobjectsrequest = new ListObjectsRequest(bucketName); // 列出 Object ObjectListing listing = ossclient.listobjects(listobjectsrequest); // 遍历所有 Object System.out.println("Objects:"); for (OSSObjectSummary objectsummary : listing.getobjectsummaries()) System.out.println(objectSummary.getKey()); // 遍历所有 CommonPrefix System.out.println("CommonPrefixs:"); for (String commonprefix : listing.getcommonprefixes()) System.out.println(commonPrefix); 输出 : Objects: fun/movie/001.avi fun/movie/007.avi fun/test.jpg oss.jpg 47

49 CommonPrefixs: 递归列出目录下所有文件 我们可以通过设置 Prefix 参数来获取某个目录 (fun/) 下所有的文件 : // 构造 ListObjectsRequest 请求 ListObjectsRequest listobjectsrequest = new ListObjectsRequest(bucketName); listobjectsrequest.setprefix("fun/"); // 递归列出 fun 目录下的所有文件 ObjectListing listing = ossclient.listobjects(listobjectsrequest); // 遍历所有 Object System.out.println("Objects:"); for (OSSObjectSummary objectsummary : listing.getobjectsummaries()) System.out.println(objectSummary.getKey()); // 遍历所有 CommonPrefix System.out.println("\nCommonPrefixs:"); for (String commonprefix : listing.getcommonprefixes()) System.out.println(commonPrefix); 输出 : Objects: fun/movie/001.avi fun/movie/007.avi fun/test.jpg CommonPrefixs: 列出目录下的文件和子目录 在 Prefix 和 Delimiter 结合的情况下, 可以列出目录 (fun/) 下的文件和子目录 : // 构造 ListObjectsRequest 请求 ListObjectsRequest listobjectsrequest = new ListObjectsRequest(bucketName); // "/" 为文件夹的分隔符 listobjectsrequest.setdelimiter("/"); // 列出 fun 目录下的所有文件和文件夹 listobjectsrequest.setprefix("fun/"); ObjectListing listing = ossclient.listobjects(listobjectsrequest); // 遍历所有 Object System.out.println("Objects:"); 48

50 for (OSSObjectSummary objectsummary : listing.getobjectsummaries()) System.out.println(objectSummary.getKey()); // 遍历所有 CommonPrefix System.out.println("\nCommonPrefixs:"); for (String commonprefix : listing.getcommonprefixes()) System.out.println(commonPrefix); 输出 : Objects: fun/test.jpg CommonPrefixs: fun/movie/ 提示 : - 返回的结果中, ObjectSummaries 的列表中给出的是 fun 目录下的文件 - 而 CommonPrefixs 的列表中给出的是 fun 目录下的所有子文件夹 可以看出 fun/movie/001.avi, fun/movie/007.avi 两个文件并没有被列出来, 因为它们属于 fun 文件夹下的 movie 目录 删除文件 删除单个文件 : 您可以通过 OSSClient.deleteObject 删除单个文件 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 删除 Object ossclient.deleteobject("<bucketname>", "<key>"); // 关闭 client ossclient.shutdown(); 49

51 删除多个文件 : 您可以通过 OSSClient.deleteObjects 批量删除文件 public DeleteObjectsResult deleteobjects(deleteobjectsrequest deleteobjectsrequest) 每次最多删除 1000 个 Object, 并提供两种返回模式 : 详细 (verbose) 模式和简单 (quiet) 模式 : - 详细模式 : 返回的成功删除 Object 的结果, 即 DeleteObjectsResult.getDeletedObjects, 默认模式 ; - 简单模式 : 返回的删除过程中出错的 Object 结果, 即 DeleteObjectsResult.getDeletedObjects DeleteObjectsRequest 可设置参数如下 : 参数作用方法 Keys 需要删除的 Objects setkeys(list<string>) Quiet EncodingType 返回模式, 默认详细模式 ;true 简单模式,false 详细模式 指定对返回的 Key 进行编码, 目前支持 url setquiet(boolean) setencodingtype(string) DeleteObjectsResult 的参数如下 : 参数含义方法 deletedobjects EncodingType 删除结果, 详细模式时成功删除的 objects, 简单模式时删除失败的 objects deletedobjects 中 Key 的进行编码, 为空没有编码 List<String> getdeletedobjects() getencodingtype() // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 删除 Objects List<String> keys = new ArrayList<String>(); keys.add("key0"); keys.add("key1"); keys.add("key2"); DeleteObjectsResult deleteobjectsresult = ossclient.deleteobjects(new 50

52 DeleteObjectsRequest("<bucketName>").withKeys(keys)); List<String> deletedobjects = deleteobjectsresult.getdeletedobjects(); // 关闭 client ossclient.shutdown(); 提示 : - 批量删除文件的完整代码请参考 :GitHub 拷贝文件 在同一个区域 ( 杭州, 深圳, 青岛等 ) 中, 可以将 Object 从一个 Bucket 复制到另外一个 Bucket 您可以通过 OSSClient.copyObject - CopyObjectResult copyobject(string sourcebucketname, String sourcekey, String destinationbucketname, String destinationkey) - CopyObjectResult copyobject(copyobjectrequest copyobjectrequest) 第一个方法指定源 Bucket/Key 和目标源 Bucket/Key, 目标 object 的内容和元数据与源 object 相同, 称为简单拷贝 第二个方法允许指定目标文件的原因数据 允许指定拷贝的限制条件 如果拷贝操作的源 Object 地址和目标 Object 地址相同, 则直接替换源 Object 的 meta 信息 CopyObjectRequest 可设置参数如下 : 参数作用方法 sourcebucketname sourcekey destinationbucketname destinationkey newobjectmetadata matchingetagconstraints nonmatchingetagconstraints 源 Object 所在的 Bucket 的名称 源 Object 的 Key 目标 Object 所在的 Bucket 的名称 目标 Object 的 Key 目标 Object 的元信息 拷贝的限制条件, 如果源 Object 的 ETAG 值和提供的 ETAG 相等, 则执行拷贝操作 ; 否则返回错误 拷贝的限制条件, 如果源 Object 的 ETAG 值和用户提供的 ETAG 不相等, 则执行拷贝操作 ; 否则返回错误 setsourcebucketname(string sourcebucketname) setsourcekey(string sourcekey) setdestinationbucketname(s tring destinationbucketname) setdestinationkey(string destinationkey) setnewobjectmetadata(obje ctmetadata newobjectmetadata) setmatchingetagconstraints( List<String> matchingetagconstraints) setnonmatchingetagconstra ints(list<string> nonmatchingetagconstraints ) unmodifiedsinceconstraint 拷贝的限制条件, 如果传入参数 setunmodifiedsinceconstrai 51

53 modifiedsinceconstraint 中的时间等于或者晚于文件实际修改时间, 则正常拷贝 ; 否则返回错误 拷贝的限制条件, 如果源 Object 自从用户指定的时间以后被修改过, 则执行拷贝操作 ; 否则返回错误 nt(date unmodifiedsinceconstraint) setmodifiedsinceconstraint( Date modifiedsinceconstraint) CopyObjectRequest 的参数如下 : 参数含义方法 etag OSS Object 唯一性标志 String getetag() lastmodified Object 最后修改时间 Date getlastmodified() 注意 : - 用户需要有源 Object 的操作权限, 否则会无法完成操作 - 该操作不支持跨 Region 拷贝数据 比如 : 不支持将杭州 Bucket 里的 Object 拷贝到青岛 - 该操作支持的最大 Object 大小为 1GB 简单拷贝 // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 拷贝 Object CopyObjectResult result = ossclient.copyobject("<srcbucketname>", "<srckey>", "<destbucketname>", "<destkey>"); System.out.println("ETag: " + result.getetag() + " LastModified: " + result.getlastmodified()); // 关闭 client ossclient.shutdown(); 通过 CopyObjectRequest 拷贝 也可以通过 CopyObjectRequest 实现 Object 的拷贝 : // endpoint 以杭州为例, 其它 region 请按实际情况填写 String endpoint = " // accesskey 请登录 查看 52

54 String accesskeyid = "<youraccesskeyid>"; String accesskeysecret = "<youraccesskeysecret>"; // 创建 OSSClient 实例 OSSClient ossclient = new OSSClient(endpoint, accesskeyid, accesskeysecret); // 创建 CopyObjectRequest 对象 CopyObjectRequest copyobjectrequest = new CopyObjectRequest(srcBucketName, srckey, destbucketname, destkey); // 设置新的 Metadata ObjectMetadata meta = new ObjectMetadata(); meta.setcontenttype("text/html"); copyobjectrequest.setnewobjectmetadata(meta); // 复制 Object CopyObjectResult result = ossclient.copyobject(copyobjectrequest); System.out.println("ETag: " + result.getetag() + " LastModified: " + result.getlastmodified()); // 关闭 client ossclient.shutdown(); 拷贝大文件 CopyObject 只能 copy 小于 1GB 的文件, 大文件需要使用分片拷贝 (Upload Part Copy) 分片拷贝更详细的说明, 请参考 Upload Part Copy 分片拷贝分为三步: - 初始化分片拷贝任务 OSSClient.initiateMultipartUpload; - 分片拷贝 OSSClient.uploadPartCopy, 除最后一个分片外, 其它的分片大小都要大于 100KB; - 提交分片拷贝任务 OSSClient.completeMultipartUpload 提示 : - 分片拷贝的完整代码请参考 :GitHub String sourcebucketname = "<sourcebucketname>"; String sourcekey = "<sourcekey>"; String targetbucketname = "<targetbucketname>"; String targetkey = "<targetkey>"; // 得到被拷贝 object 大小 ObjectMetadata objectmetadata = ossclient.getobjectmetadata(sourcebucketname, sourcekey); long contentlength = objectmetadata.getcontentlength(); // 分片大小,10MB long partsize = 1024 * 1024 * 10; // 计算分块数目 int partcount = (int) (contentlength / partsize); if (contentlength % partsize!= 0) partcount++; 53

55 System.out.println("total part count:" + partcount); // 初始化拷贝任务 InitiateMultipartUploadRequest initiatemultipartuploadrequest = new InitiateMultipartUploadRequest(targetBucketName, targetkey); InitiateMultipartUploadResult initiatemultipartuploadresult = ossclient.initiatemultipartupload(initiatemultipartuploadrequest); String uploadid = initiatemultipartuploadresult.getuploadid(); // 分片拷贝 List<PartETag> partetags = new ArrayList<PartETag>(); for (int i = 0; i < partcount; i++) // 计算每个分块的大小 long skipbytes = partsize * i; long size = partsize < contentlength - skipbytes? partsize : contentlength - skipbytes; // 创建 UploadPartCopyRequest UploadPartCopyRequest uploadpartcopyrequest = new UploadPartCopyRequest(sourceBucketName, sourcekey, targetbucketname, targetkey); uploadpartcopyrequest.setuploadid(uploadid); uploadpartcopyrequest.setpartsize(size); uploadpartcopyrequest.setbeginindex(skipbytes); uploadpartcopyrequest.setpartnumber(i + 1); UploadPartCopyResult uploadpartcopyresult = ossclient.uploadpartcopy(uploadpartcopyrequest); // 将返回的 PartETag 保存到 List 中 partetags.add(uploadpartcopyresult.getpartetag()); // 提交分片拷贝任务 CompleteMultipartUploadRequest completemultipartuploadrequest = new CompleteMultipartUploadRequest( targetbucketname, targetkey, uploadid, partetags); ossclient.completemultipartupload(completemultipartuploadrequest); 提示 : - 分片拷贝时, 可以指定目标 object 的元信息, 通过 InitiateMultipartUploadRequest 指定 ; - 分片拷贝也支持限定条件, 通过 UploadPartCopyRequest 指定 授权访问 使用 STS 服务临时授权 介绍 OSS 可以通过阿里云 STS 服务, 临时进行授权访问 阿里云 STS (Security Token Service) 是为云计算用户提供 54

56 临时访问令牌的 Web 服务 通过 STS, 您可以为第三方应用或联邦用户 ( 用户身份由您自己管理 ) 颁发一个自定义时效和权限的访问凭证 第三方应用或联邦用户可以使用该访问凭证直接调用阿里云产品 API, 或者使用阿里云产品提供的 SDK 来访问云产品 API - 您不需要透露您的长期密钥 (AccessKey) 给第三方应用, 只需要生成一个访问令牌并将令牌交给第三方应用即可 这个令牌的访问权限及有效期限都可以由您自定义 - 您不需要关心权限撤销问题, 访问令牌过期后就自动失效 以 APP 应用为例, 交互流程如下图 : 方案的详细描述如下 : 1. App 用户登录 App 用户身份是客户自己管理 客户可以自定义身份管理系统, 也可以使用外部 Web 账号或 OpenID 对于每个有效的 App 用户来说,AppServer 是可以确切地定义出每个 App 用户的最小访问权限 2. AppServer 请求 STS 服务获取一个安全令牌 (SecurityToken) 在调用 STS 之前,AppServer 需要确定 App 用户的最小访问权限 ( 用 Policy 语法描述 ) 以及授权的过期时间 然后通过调用 STS 的 AssumeRole( 扮演角色 ) 接口来获取安全令牌 角色管理与使用相关内容请参考 RAM 使用指南 中的角色管理 3. STS 返回给 AppServer 一个有效的访问凭证, 包括一个安全令牌 (SecurityToken) 临时访问密钥 (AccessKeyId, AccessKeySecret) 以及过期时间 4. AppServer 将访问凭证返回给 ClientApp ClientApp 可以缓存这个凭证 当凭证失效时,ClientApp 需要向 AppServer 申请新的有效访问凭证 比如, 访问凭证有效期为 1 小时, 那么 ClientApp 可以每 30 分钟向 AppServer 请求更新访问凭证 5. ClientApp 使用本地缓存的访问凭证去请求 Aliyun Service API 云服务会感知 STS 访问凭证, 并会依赖 STS 服务来验证访问凭证, 并正确响应用户请求 STS 安全令牌详情, 请参考 RAM 使用指南 中的角色管理 关键是调用 STS 服务接口 AssumeRole 来获取有效访问凭证即可 也可以直接使用 STS SDK 来调用该方法, 点击查看 使用 STS 凭证构造签名请求 用户的 client 端拿到 STS 临时凭证后, 通过其中安全令牌 (SecurityToken) 以及临时访问密钥 (AccessKeyId, AccessKeySecret) 生成 OSSClient 以上传 Object 为例 : String accesskeyid = "<accesskeyid>"; String accesskeysecret = "<accesskeysecret>"; 55

57 String securitytoken = "<securitytoken>" // 以杭州为例 String endpoint = " OSSClient client = new OSSClient(endpoint, accesskeyid, accesskeysecret, securitytoken); 使用 URL 签名授权访问 生成签名 URL 通过生成签名 URL 的形式提供给用户一个临时的访问 URL 在生成 URL 时, 您可以指定 URL 过期的时间, 从而限制用户长时间访问 生成一个签名的 URL 代码如下 : String bucketname = "your-bucket-name"; String key = "your-object-key"; // 设置 URL 过期时间为 1 小时 Date expiration = new Date(new Date().getTime() * 1000); // 生成 URL URL url = client.generatepresignedurl(bucketname, key, expiration); 生成的 URL 默认以 GET 方式访问, 这样, 用户可以直接通过浏览器访问相关内容 生成其他 Http 方法的 URL 如果您想允许用户临时进行其他操作 ( 比如上传, 删除 Object), 可能需要签名其他方法的 URL, 如下 : // 生成 PUT 方法的 URL URL url = client.generatepresignedurl(bucketname, key, expiration, HttpMethod.PUT); 通过传入 HttpMethod.PUT 参数, 用户可以使用生成的 URL 上传 Object 添加用户自定义参数 (UserMetadata) 如果您想生成签名的 URL 来上传 Object, 并指定 UserMetadata,Content-Type 等头信息, 可以这样做 : // 创建请求 GeneratePresignedUrlRequest generatepresignedurlrequest = new GeneratePresignedUrlRequest(bucketName, key); // HttpMethod 为 PUT generatepresignedurlrequest.setmethod(httpmethod.put); 56

58 // 添加 UserMetadata generatepresignedurlrequest.addusermetadata("author", "baymax"); // 添加 Content-Type request.setcontenttype("application/octet-stream"); // 生成签名的 URL URL url = client.generatepresignedurl(generatepresignedurlrequest); 需要注意的是, 上述过程只是生成了签名的 URL, 您仍需要在 request header 中添加 meta 的信息 可以参考下 面的代码 使用签名 URL 发送请求 现在 java SDK 支持 put object 和 get object 两种方式的 URL 签名请求 使用 URL 签名的方式 getobject // 服务器端生成 url 签名字串 OSSClient Server = new OSSClient(endpoint, accessid, accesskey); Date expiration = DateUtil.parseRfc822Date("Wed, 18 Mar :20:00 GMT"); GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucketName, key, HttpMethod.GET); // 设置过期时间 request.setexpiration(expiration); // 生成 URL 签名 (HTTP GET 请求 ) URL signedurl = Server.generatePresignedUrl(request); System.out.println("signed url for getobject: " + signedurl); // 客户端使用使用 url 签名字串发送请求 OSSClient client = new OSSClient(endpoint, accesskeyid, accesskeysecret); Map<String, String> customheaders = new HashMap<String, String>(); // 添加 GetObject 请求头 customheaders.put("range", "bytes= "); OSSObject object = client.getobject(signedurl,customheaders); 使用 URL 签名的方式 putobject // 服务器端生成 url 签名字串 OSSClient Server = new OSSClient(endpoint, accesskeyid, accesskeysecret); Date expiration = DateUtil.parseRfc822Date("Wed, 18 Mar :20:00 GMT"); GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucketName, key, HttpMethod.PUT); // 设置过期时间 request.setexpiration(expiration); // 设置 Content-Type request.setcontenttype("application/octet-stream"); // 添加 user meta request.addusermetadata("author", "aliy"); // 生成 URL 签名 (HTTP PUT 请求 ) URL signedurl = Server.generatePresignedUrl(request); System.out.println("signed url for putobject: " + signedurl); 57

59 // 客户端使用使用 url 签名字串发送请求 OSSClient client = new OSSClient(endpoint, accesskeyid, accesskeysecret); File f = new File(filePath); FileInputStream fin = new FileInputStream(f); // 添加 PutObject 请求头 Map<String, String> customheaders = new HashMap<String, String>(); customheaders.put("content-type", "application/octet-stream"); // 添加 user meta customheaders.put("x-oss-meta-author", "aliy"); PutObjectResult result = client.putobject(signedurl, fin, f.length(), customheaders); 生命周期管理 (Lifecycle) OSS 允许用户对 Bucket 设置生命周期规则, 以自动淘汰过期掉的文件, 节省存储空间 针对不同前缀的文件, 用户可以同时设置多条规则 一条规则包含 : - 规则 ID, 用于标识一条规则, 不能重复 - 受影响的文件前缀, 此规则只作用于符合前缀的文件 - 过期时间, 有三种指定方式 : i. 指定距文件最后修改时间 N 天过期 ii. 指定日期创建前的文件过期, 之后的不过期 iii. 指定在具体的某一天过期, 即在那天之后符合前缀的文件将会过期, 而不论文件的最后修改时间 不推荐使用 - 是否生效上面的过期规则对用户上传的文件有效 用户通过 uploadpart 上传的分片, 也可以设置过期规则 Multipart 的 Lifecycle 和文件的类似, 过期时间支持 1 2 两种, 不支持 3, 生效是以 init Multipart upload 的时间为准 更多关于生命周期的内容请参考文件生命周期 设置生命周期规则 通过 OSSClient.setBucketLifecycle 来设置生命周期规则 : SetBucketLifecycleRequest request = new SetBucketLifecycleRequest("bucketName"); // 最近修改 3 天后过期 request.addlifecyclerule(new LifecycleRule(ruleId0, matchprefix0, RuleStatus.Enabled, 3)); // 特定日期后过期 request.addlifecyclerule(new LifecycleRule(ruleId1, matchprefix1, RuleStatus.Enabled, DateUtil.parseIso8601Date(" T00:00:00.000Z"))); // 特定日期前创建的文件过期 LifecycleRule rule = new LifecycleRule(ruleId4, matchprefix4, RuleStatus.Enabled); rule.setcreatedbeforedate(dateutil.parseiso8601date(" t00:00:00.000z")); request.addlifecyclerule(rule); // Multipart3 天后过期 58

60 rule = new LifecycleRule(ruleId2, matchprefix2, RuleStatus.Enabled); LifecycleRule.AbortMultipartUpload abortmultipartupload = rule.new AbortMultipartUpload(); abortmultipartupload.setexpirationdays(3); rule.setabortmultipartupload(abortmultipartupload); request.addlifecyclerule(rule); // 特定日期前的 Multipart 过期 rule = new LifecycleRule(ruleId3, matchprefix3, RuleStatus.Enabled); abortmultipartupload = rule.new AbortMultipartUpload(); abortmultipartupload.setcreatedbeforedate(dateutil.parseiso8601date(" t00:00:00.000z")); rule.setabortmultipartupload(abortmultipartupload); request.addlifecyclerule(rule); ossclient.setbucketlifecycle(request); 查看生命周期规则 通过 OSSClient.GetBucketLifecycle 来查看生命周期规则 : List<LifecycleRule> rules = ossclient.getbucketlifecycle("bucketname"); for (LifecycleRule rule : rules) System.out.println(rule.getId()); System.out.println(rule.getPrefix()); System.out.println(rule.getExpirationDays()); 清空生命周期规则 通过 OSSClient.DeleteBucketLifecycle 设置来清空生命周期规则 : ossclient.deletebucketlifecycle("bucketname"); 跨域资源共享设置 跨域资源共享 (CORS) 允许 web 端的应用程序访问不属于本域的资源 OSS 提供接口方便开发者控制跨域访问的 权限 更多关于跨域资源共享的内容请参考跨域访问 设定 CORS 规则 通过 setbucketcors 方法将指定的存储空间上设定一个跨域资源共享 CORS 的规则, 如果原规则存在则覆盖原 规则 具体的规则主要通过 CORSRule 类来进行参数设置 代码如下 : 59

61 SetBucketCORSRequest request = new SetBucketCORSRequest(); request.setbucketname(bucketname); //CORS 规则的容器, 每个 bucket 最多允许 10 条规则 ArrayList<CORSRule> putcorsrules = new ArrayList<CORSRule>(); CORSRule corrule = new CORSRule(); ArrayList<String> allowedorigin = new ArrayList<String>(); // 指定允许跨域请求的来源 allowedorigin.add( " ArrayList<String> allowedmethod = new ArrayList<String>(); // 指定允许的跨域请求方法 (GET/PUT/DELETE/POST/HEAD) allowedmethod.add("get"); ArrayList<String> allowedheader = new ArrayList<String>(); // 控制在 OPTIONS 预取指令中 Access-Control-Request-Headers 头中指定的 header 是否允许 allowedheader.add("x-oss-test"); ArrayList<String> exposedheader = new ArrayList<String>(); // 指定允许用户从应用程序中访问的响应头 exposedheader.add("x-oss-test1"); corrule.setallowedmethods(allowedmethod); corrule.setallowedorigins(allowedorigin); corrule.setallowedheaders(allowedheader); corrule.setexposeheaders(exposedheader); // 指定浏览器对特定资源的预取 (OPTIONS) 请求返回结果的缓存时间, 单位为秒 corrule.setmaxageseconds(10); // 最多允许 10 条规则 putcorsrules.add(corrule); request.setcorsrules(putcorsrules); oss.setbucketcors(request); 提示 : - 每个存储空间最多只能使用 10 条规则 - AllowedOrigins 和 AllowedMethods 都能够最多支持一个 "*" 通配符 "*" 表示对于所有的域来源或者操作都满足 - 而 AllowedHeaders 和 ExposeHeaders 不支持通配符 获取 CORS 规则 我们可以参考存储空间的 CORS 规则, 通过 GetBucketCors 方法 代码如下 : ArrayList<CORSRule> corsrules; // 获得 CORS 规则列表 corsrules = (ArrayList<CORSRule>) oss.getbucketcorsrules(bucketname); for (CORSRule rule : corsrules) 60

62 for (String allowedorigin1 : rule.getallowedorigins()) // 获得允许跨域请求源 System.out.println(allowedOrigin1); for (String allowedmethod1 : rule.getallowedmethods()) // 获得允许跨域请求方法 System.out.println(allowedMethod1); if (rule.getallowedheaders().size() > 0) for (String allowedheader1 : rule.getallowedheaders()) // 获得允许头部列表 System.out.println(allowedHeader1); if (rule.getexposeheaders().size() > 0) for (String exposeheader : rule.getexposeheaders()) // 获得允许头部 System.out.println(exposeHeader); if ( null!= rule.getmaxageseconds()) System.out.println(rule.getMaxAgeSeconds()); 删除 CORS 规则 用于关闭指定存储空间对应的 CORS 并清空所有规则 // 清空 bucket 的 CORS 规则 oss.deletebucketcorsrules(bucketname); 设置访问日志 (Logging) OSS 允许用户对 Bucket 设置访问日志记录, 设置之后对于 Bucket 的访问会被记录成日志, 日志存储在 OSS 上由 用户指定的 Bucket 中, 文件的格式为 : <TargetPrefix><SourceBucket>-YYYY-mm-DD-HH-MM-SS-UniqueString 其中 TargetPrefix 由用户指定 日志规则由以下 2 项组成 : - target_bucket, 存放日志文件的 Bucket - target_prefix, 保存访问日志文件前缀 61

63 更多关于访问日志的内容请参考 Bucket 访问日志 开启 Bucket 日志 通过 OSSClient.setBucketLogging 来开启日志功能 : SetBucketLoggingRequest request = new SetBucketLoggingRequest("sourceBucket"); request.settargetbucket("targetbucket"); request.settargetprefix("targetprefix"); ossclient.setbucketlogging(request); 查看 Bucket 日志设置 通过 OSSClient.getBucketLogging 来查看日志设置 : BucketLoggingResult result = ossclient.getbucketlogging("sourcebucket"); System.out.println(result.getTargetBucket()); System.out.println(result.getTargetPrefix()); 关闭 Bucket 日志 通过 OSSClient.setBucketLogging 来关闭日志功能 : SetBucketLoggingRequest request = new SetBucketLoggingRequest("sourceBucket"); request.settargetbucket(null); request.settargetprefix(null); ossclient.setbucketlogging(request); 托管静态网站 在自定义域名绑定中提到,OSS 允许用户将自己的域名指向 OSS 服务的地址 这样用户访问他的网站的时候, 实际上是在访问 OSS 的 Bucket 对于网站, 需要指定首页 (index) 和出错页 (error) 分别对应的 Bucket 中的文件名 更多关于静态网站托管的内容请参考 OSS 静态网站托管 设置托管页面 62

64 通过 OSSClient.setBucketWebsite 来设置托管页面 : SetBucketWebsiteRequest request = new SetBucketWebsiteRequest("bucketName"); request.setindexdocument("index.html"); request.seterrordocument("error.html"); ossclient.setbucketwebsite(request); 查看托管页面 通过 OSSClient.getBucketWebsite 来查看托管页面 : BucketWebsiteResult result = ossclient.getbucketwebsite("bucketname"); System.out.println(result.getIndexDocument()); System.out.println(result.getErrorDocument()); 清除托管页面 通过 OSSClient.deleteBucketWebsite 来清除托管页面 : ossclient.deletebucketwebsite("bucketname"); 防盗链设置 OSS 是按使用收费的服务, 为了防止用户在 OSS 上的数据被其他人盗链,OSS 支持基于 HTTP header 中表头字 段 referer 的防盗链方法 更多关于防盗链的内容请参考防盗链 设置 Referer 白名单 通过下面代码设置 Referer 白名单 : OSSClient client = new OSSClient(endpoint, accessid, accesskey); List<String> refererlist = new ArrayList<String>(); // 添加 referer 项 refererlist.add(" refererlist.add(" refererlist.add(" // 允许 referer 字段为空, 并设置 Bucket Referer 列表 BucketReferer br = new BucketReferer(true, refererlist); 63

65 client.setbucketreferer(bucketname, br); 注意 : - Referer 参数支持通配符 "*" 和 "?", 更多详细的规则配置可以参考开发人员指南 OSS 防盗链 获取 Referer 白名单 // 获取 Bucket Referer 列表 br = client.getbucketreferer(bucketname); refererlist = br.getrefererlist(); for (String referer : refererlist) System.out.println(referer); 输出结果示例 : 清空 Referer 白名单 Referer 白名单不能直接清空, 只能通过重新设置来覆盖之前的规则 OSSClient client = new OSSClient(endpoint, accessid, accesskey); // 默认允许 referer 字段为空, 且 referer 白名单为空 BucketReferer br = new BucketReferer(); client.setbucketreferer(bucketname, br); 跨区域复制 (Replication) 跨区域复制是跨不同 OSS 数据中心的 Bucket 自动 异步地复制 Object, 它会将对源 Bucket 中的对象的改动 ( 新建 覆盖 删除等 ) 同步到目标 Bucket 该功能能够很好的提供 Bucket 跨区域容灾或满足用户数据复制的需求 目标 Bucket 中的对象是源 Bucket 中对象的精确副本, 它们具有相同的对象名 元数据以及内容 ( 例如, 创建时间 拥有者 用户定义的元数据 Object ACL 对象内容等) 更多跨区域复制的内容请参考跨区域复制 开启跨区域复制 64

66 通过 OSSClient.addBucketReplication 开启跨区域复制 : AddBucketReplicationRequest request = new AddBucketReplicationRequest("bucketName"); request.setreplicationruleid("ruleid"); request.settargetbucketname("targetbucketname"); request.settargetbucketlocation("oss-cn-qingdao"); ossclient.addbucketreplication(request); 提示 : - 开启跨区域复制, 默认会同步历史数据 如果不需要同步历史数据, 使用 AddBucketReplicationRequest.setEnableHistoricalObjectReplication(false) 禁止历史数据同步 查看跨区域复制 通过 OSSClient.getBucketReplication 查看 bucket 上开启的跨区域复制 : List<ReplicationRule> rules = ossclient.getbucketreplication("bucketname"); for (ReplicationRule rule : rules) System.out.println(rule.getReplicationRuleID()); System.out.println(rule.getTargetBucketLocation()); System.out.println(rule.getTargetBucketName()); 删除跨区域复制 通过 OSSClient.deleteBucketReplication 删除已开启的跨区域复制, 删除后目标 bucket 和 object 依然存在 : ossclient.deletebucketreplication("bucketname", "ruleid"); 查看跨区域复制进度 复制进度分为历史数据同步进度 实时数据同步进度 历史数据的同步用百分比表示, 如 0.80 表示完成了 80%, 仅对开启了历史数据同步的 Bucket 有效 实时数据同步用新写入数据的时间点表示, 表示这个时间点之前的数据已同步完成 通过 OSSClient.deleteBucketReplication 查看跨区域复制进度 : BucketReplicationProgress process = ossclient.getbucketreplicationprogress("bucketname", "repruleid"); System.out.println(process.getReplicationRuleID()); // 是否开启了历史数据同步 System.out.println(process.isEnableHistoricalObjectReplication()); 65

67 // 历史数据同步进度 System.out.println(process.getHistoricalObjectProgress()); // 实时数据同步进度 System.out.println(process.getNewObjectProgress()); 查看目标数据中心 通过 OSSClient.getBucketReplicationLocation 获取 Bucket 所在的数据中心可同步到的数据中心 : List<String> locations = ossclient.getbucketreplicationlocation("bucketname"); for (String loc : locations) System.out.println(loc); 异常处理 调用 OSSClient 类的相关接口时, 如果抛出异常, 则表明操作失败, 否则操作成功 抛出异常时, 方法返回的 数据无效 OSS Java SDK 包含两类异常, 一类是服务器端异常 OSSException, 另一类是客户端异常 ClientException, 它们均继承自 RuntimeException 异常处理示例 try // Do some operations with the instance here, such as put object... client.putobject(...); catch (OSSException oe) System.out.println("Caught an OSSException, which means your request made it to OSS, " + "but was rejected with an error response for some reason."); System.out.println("Error Message: " + oe.geterrorcode()); System.out.println("Error Code: " + oe.geterrorcode()); System.out.println("Request ID: " + oe.getrequestid()); System.out.println("Host ID: " + oe.gethostid()); catch (ClientException ce) System.out.println("Caught an ClientException, which means the client encountered " + "a serious internal problem while trying to communicate with OSS, " + "such as not being able to access the network."); System.out.println("Error Message: " + ce.getmessage()); finally if (client!= null) client.shutdown(); ClientException 66

68 ClientException 表示客户端尝试向 OSS 发送请求以及数据传输时遇到的异常 例如, 当发送请求时网络连接不 可用时, 则会抛出 ClientException; 当上传文件时发生 IO 异常时, 也会抛出 ClientException OSSException OSSException 指服务器端错误, 它来自于对服务器错误信息的解析, 包含 OSS 会返回给用户相应的错误码和错误信息, 便于用户定位问题, 并做出适当的处理 OSSException 通常包含以下错误信息 : - Code: OSS 返回给用户的错误码 - Message: OSS 提供的详细错误信息 - RequestId: 用于唯一标识该请求的 UUID; 当您无法解决问题时, 可以凭这个 RequestId 来请求 OSS 开发工程师的帮助 - HostId: 用于标识访问的 OSS 集群, 与用户请求时使用的 Host 一致 OSS 常见错误码 错误码 描述 HTTP 状态码 AccessDenied 拒绝访问 403 BucketAlreadyExists Bucket 已经存在 409 BucketNotEmpty Bucket 不为空 409 EntityTooLarge 实体过大 400 EntityTooSmall 实体过小 400 FileGroupTooLarge 文件组过大 400 FilePartNotExist 文件 Part 不存在 400 FilePartStale 文件 Part 过时 400 InvalidArgument 参数格式错误 400 InvalidAccessKeyId AccessKeyId 不存在 403 InvalidBucketName 无效的 Bucket 名字 400 InvalidDigest 无效的摘要 400 InvalidObjectName 无效的 Object 名字 400 InvalidPart 无效的 Part 400 InvalidPartOrder 无效的 part 顺序 400 InvalidTargetBucketForLoggi ng Logging 操作中有无效的目标 bucket 400 InternalError OSS 内部发生错误 500 MalformedXML XML 格式非法

69 MethodNotAllowed 不支持的方法 405 MissingArgument 缺少参数 411 MissingContentLength 缺少内容长度 411 NoSuchBucket Bucket 不存在 404 NoSuchKey 文件不存在 404 NoSuchUpload Multipart Upload ID 不存在 404 NotImplemented 无法处理的方法 501 PreconditionFailed 预处理错误 412 RequestTimeTooSkewed 发起请求的时间和服务器时间超出 15 分钟 403 RequestTimeout 请求超时 400 SignatureDoesNotMatch 签名错误 403 InvalidEncryptionAlgorithmEr ror 指定的熵编码加密算法错误 400 常见问题 包冲突 如果您在使用 OSS Java SDK 时, 报如下或类似错误 : Exception in thread "main" java.lang.noclassdeffounderror: org/apache/http/ssl/truststrategy at com.aliyun.oss.ossclient.<init>(ossclient.java:268) at com.aliyun.oss.ossclient.<init>(ossclient.java:193) at com.aliyun.oss.demo.hellooss.main(hellooss.java:77) Caused by: java.lang.classnotfoundexception: org.apache.http.ssl.truststrategy at java.net.urlclassloader$1.run(urlclassloader.java:366) at java.net.urlclassloader$1.run(urlclassloader.java:355) at java.security.accesscontroller.doprivileged(native Method) at java.net.urlclassloader.findclass(urlclassloader.java:354) at java.lang.classloader.loadclass(classloader.java:425) at sun.misc.launcher$appclassloader.loadclass(launcher.java:308) at java.lang.classloader.loadclass(classloader.java:358)... 3 more 或 Exception in thread "main" java.lang.nosuchfielderror: INSTANCE at org.apache.http.impl.io.defaulthttprequestwriterfactory.<init>(defaulthttprequestwriterfactory.java:52) at org.apache.http.impl.io.defaulthttprequestwriterfactory.<init>(defaulthttprequestwriterfactory.java:56) 68

70 at org.apache.http.impl.io.defaulthttprequestwriterfactory.<clinit>(defaulthttprequestwriterfactory.java:46) at org.apache.http.impl.conn.managedhttpclientconnectionfactory.<init>(managedhttpclientconnectionfactory.java :82) at org.apache.http.impl.conn.managedhttpclientconnectionfactory.<init>(managedhttpclientconnectionfactory.java :95) at org.apache.http.impl.conn.managedhttpclientconnectionfactory.<init>(managedhttpclientconnectionfactory.java :104) at org.apache.http.impl.conn.managedhttpclientconnectionfactory.<clinit>(managedhttpclientconnectionfactory.ja va:62) at org.apache.http.impl.conn.poolinghttpclientconnectionmanager$internalconnectionfactory.<init>(poolinghttpcli entconnectionmanager.java:572) at org.apache.http.impl.conn.poolinghttpclientconnectionmanager.<init>(poolinghttpclientconnectionmanager.java: 174) at org.apache.http.impl.conn.poolinghttpclientconnectionmanager.<init>(poolinghttpclientconnectionmanager.java: 158) at org.apache.http.impl.conn.poolinghttpclientconnectionmanager.<init>(poolinghttpclientconnectionmanager.java: 149) at org.apache.http.impl.conn.poolinghttpclientconnectionmanager.<init>(poolinghttpclientconnectionmanager.java: 125) at com.aliyun.oss.common.comm.defaultserviceclient.createhttpclientconnectionmanager(defaultserviceclient.java:2 37) at com.aliyun.oss.common.comm.defaultserviceclient.<init>(defaultserviceclient.java:78) at com.aliyun.oss.ossclient.<init>(ossclient.java:268) at com.aliyun.oss.ossclient.<init>(ossclient.java:193) at OSSManagerImpl.upload(OSSManagerImpl.java:42) at OSSManagerImpl.main(OSSManagerImpl.java:63) 您的工程里可能有包冲突 原因是,OSS Java SDK 使用了 Apache httpclient 4.4.1, 您的工程使用了与 Apache httpclient 冲突的 Apache httpclient 或 commons-httpclient 请在您的工程目录下执行 "mvn dependency:tree", 查看工程使用的包及版本 如上述发生错误的工程里, 使用了 Apache httpclient 4.3: 包冲突有以下两种解决方法 : 69

71 - 使用统一版本 如果您的工程里使用与 Apache httpclient 冲突的版本, 请您也使用 版本 在 pom.xml 去掉其它版本的 Apache httpclient 依赖 如果您的工程使用了 commons-httpclient 也可能存在冲突, 请去除 commons-httpclient - 解除依赖冲突 如果您的工程依赖与多个第三方包, 而第三方包又依赖不同版本的 Apache httpclient, 您的工程里会有依赖冲突, 请使用 exclusion 解除 详细请参考 maven guides OSS Java SDK 依赖以下版本的包, 冲突解决办法与 httpclient 类似, 不再赘述 缺少包 编译 / 运行 OSS Java SDK 报如下错误 : Exception in thread "main" java.lang.noclassdeffounderror: org/apache/http/auth/credentials at com.aliyun.oss.ossclient.<init>(ossclient.java:268) at com.aliyun.oss.ossclient.<init>(ossclient.java:193) at com.aliyun.oss.demo.hellooss.main(hellooss.java:76) Caused by: java.lang.classnotfoundexception: org.apache.http.auth.credentials at java.net.urlclassloader$1.run(urlclassloader.java:366) at java.net.urlclassloader$1.run(urlclassloader.java:355) at java.security.accesscontroller.doprivileged(native Method) at java.net.urlclassloader.findclass(urlclassloader.java:354) at java.lang.classloader.loadclass(classloader.java:425) at sun.misc.launcher$appclassloader.loadclass(launcher.java:308) at java.lang.classloader.loadclass(classloader.java:358)... 3 more 或 Exception in thread "main" java.lang.noclassdeffounderror: org/apache/http/protocol/httpcontext at com.aliyun.oss.ossclient.<init>(ossclient.java:268) at com.aliyun.oss.ossclient.<init>(ossclient.java:193) at com.aliyun.oss.demo.hellooss.main(hellooss.java:76) Caused by: java.lang.classnotfoundexception: org.apache.http.protocol.httpcontext at java.net.urlclassloader$1.run(urlclassloader.java:366) at java.net.urlclassloader$1.run(urlclassloader.java:355) at java.security.accesscontroller.doprivileged(native Method) at java.net.urlclassloader.findclass(urlclassloader.java:354) at java.lang.classloader.loadclass(classloader.java:425) at sun.misc.launcher$appclassloader.loadclass(launcher.java:308) 70

72 at java.lang.classloader.loadclass(classloader.java:358)... 3 more 或 Exception in thread "main" java.lang.noclassdeffounderror: org/jdom/input/saxbuilder at com.aliyun.oss.internal.responseparsers.getxmlrootelement(responseparsers.java:645) at at com.aliyun.oss.ossclient.doesbucketexist(ossclient.java:471) at com.aliyun.oss.ossclient.doesbucketexist(ossclient.java:465) at com.aliyun.oss.demo.hellooss.main(hellooss.java:82) Caused by: java.lang.classnotfoundexception: org.jdom.input.saxbuilder at java.net.urlclassloader$1.run(urlclassloader.java:366) at java.net.urlclassloader$1.run(urlclassloader.java:355) at java.security.accesscontroller.doprivileged(native Method) at java.net.urlclassloader.findclass(urlclassloader.java:354) at java.lang.classloader.loadclass(classloader.java:425) at sun.misc.launcher$appclassloader.loadclass(launcher.java:308) at java.lang.classloader.loadclass(classloader.java:358) more 等类似错误, 说明您的工程缺少 OSS Java SDK 编译或运行必须的包 OSS Java SDK 依赖下列包 : - aliyun-sdk-oss jar - hamcrest-core-1.1.jar - jdom-1.1.jar - commons-codec-1.9.jar - httpclient jar - commons-logging-1.2.jar - httpcore jar - log4j jar 其中,log4j jar 是可选的, 需要日志功能的时加入该包 其它包都是必不可少的 解决办法 : 您的工程中在加入 OSS Java SDK 依赖的包, 加入方法如下 : - 如果您的工程是 Eclipse 请参考 Java-SDK 使用手册," 安装 "-> " 方式二 : 在 Eclipse 项目中导入工程依赖的包 "; - 如果您的工程是 Ant 请把 OSS Java SDK 依赖的包, 放入工程 lib 目录 ; - 如果您直接使用 javac/java, 请使用 -classpath/-cp 指定 OSS Java SDK 依赖的包路径, 或把 OSS Java SDK 依赖的包放入 classpath 路经下 连接超时 运行 OSS Java SDK 程序抛出如下异常 : com.aliyun.oss.clientexception: SocketException at com.aliyun.oss.common.utils.exceptionfactory.createnetworkexception(exceptionfactory.java:71) at com.aliyun.oss.common.comm.defaultserviceclient.sendrequestcore(defaultserviceclient.java:116) 71

73 at com.aliyun.oss.common.comm.serviceclient.sendrequestimpl(serviceclient.java:121) at com.aliyun.oss.common.comm.serviceclient.sendrequest(serviceclient.java:67) at com.aliyun.oss.internal.ossoperation.send(ossoperation.java:92) at com.aliyun.oss.internal.ossoperation.dooperation(ossoperation.java:140) at com.aliyun.oss.internal.ossoperation.dooperation(ossoperation.java:111) at com.aliyun.oss.internal.ossbucketoperation.getbucketinfo(ossbucketoperation.java:1152) at com.aliyun.oss.ossclient.getbucketinfo(ossclient.java:1220) at com.aliyun.oss.ossclient.getbucketinfo(ossclient.java:1214) at com.aliyun.oss.demo.hellooss.main(hellooss.java:94) Caused by: org.apache.http.conn.httphostconnectexception: Connect to oss-test.oss-cn-hangzhouinternal.aliyuncs.com:80 [oss-test.oss-cn-hangzhou-internal.aliyuncs.com/ ] failed: Connection timed out: connect at org.apache.http.impl.conn.defaulthttpclientconnectionoperator.connect(defaulthttpclientconnectionoperator.jav a:151) at org.apache.http.impl.conn.poolinghttpclientconnectionmanager.connect(poolinghttpclientconnectionmanager.jav a:353) at org.apache.http.impl.execchain.mainclientexec.establishroute(mainclientexec.java:380) at org.apache.http.impl.execchain.mainclientexec.execute(mainclientexec.java:236) at org.apache.http.impl.execchain.protocolexec.execute(protocolexec.java:184) at org.apache.http.impl.execchain.redirectexec.execute(redirectexec.java:110) at org.apache.http.impl.client.internalhttpclient.doexecute(internalhttpclient.java:184) at org.apache.http.impl.client.closeablehttpclient.execute(closeablehttpclient.java:82) at com.aliyun.oss.common.comm.defaultserviceclient.sendrequestcore(defaultserviceclient.java:113)... 9 more 原因是 endpoint 错误或者网络不通, 如果不能直接找出错误 请使用 OSSProbe 工具检测,OSSProbe 会给出 可能的错误原因 The targe server failed to respond 运行 OSS Java SDK 程序抛出如下异常 : 原因是 : 重用连接前没有检测连接是否有效, 过期的连接重用会导致上述错误 该问题是 Apache httpclient 4.4 的 bug, 详见 HTTPCLIENT-1609,4.4.1 及以后版本修复 Java SDK 前的版本使用的是 Apache httpclient 4.4, 存在上述问题 ;Java SDK 及以后的版本, 使用的是 Apache httpclient 4.4.1, 修复了该问题 如果发现该问题请升级 OSS Java SDK 到 及以后版本 其它错误 其它 OSS 返回错误的排查, 请参看常见错误及排查 72

74 Python-SDK 安装 相关资源 : - github 项目 - SDK API 文档 : 所有的接口, 以及类的细节 - PyPi 主页 环境依赖 此版本的 Python SDK 适用于 Python 版本 首先请根据 python 官网的引导安装合适 的 Python 版本 安装好 Python 后 : 在 Linux Shell 里验证 Python 版本 : $ python -V Python 上面的输出表明您已经成功安装了 Python 版本 Windows CMD 环境下验证 Python 版本 : C:\> python -V Python 上面的输出表明您已经成功安装了 Python 版本 如果提示 " 不是内部或外部命令 ", 请检查配置 " 环境变量 "-"Path", 增加 Python 的安装路径 如图 : 73

75 安装 SDK 通过 pip 安装 pip install oss2 源码安装 从 github 下载相应版本的 SDK 包, 解压后进入目录, 确认目录下有 setup.py 这个文件 : python setup.py install 验证 首先命令行输入 python 并回车, 在 Python 环境下检查 SDK 的版本 : >>> import oss2 >>> oss2. version '2.0.0' 上面的输出表明您已经成功安装了特定版本的 Python SDK( 这里以版本 为例 ) 卸载 SDK 建议通过 pip 卸载 : pip uninstall oss2 历史版本 74