全部产品
对象存储 OSS

初始化

更新时间:2017-07-24 14:58:41   分享:   

OSSClient是OSS服务的Java客户端,它为调用者提供一系列与OSS进行交互的接口,用于管理、操作存储空间(Bucket)和文件(Object)等OSS资源。使用Java SDK发起OSS请求,您需要初始化一个OSSClient实例,并根据需要修改ClientConfiguration的默认配置项。

确定Endpoint

请先阅读开发人员指南中关于访问域名和数据中心自定义访问域名的部分,理解Endpoint相关的概念。

Endpoint可以有以下几种形式:

示例 说明
http://oss-cn-hangzhou.aliyuncs.com 以HTTP协议,公网访问杭州区域的Bucket
https://oss-cn-beijing.aliyuncs.com 以HTTPS协议,公网范围北京区域的Bucket
http://my-domain.com 以HTTP协议,通过用户自定义域名(CNAME)访问特定Bucket

配置密钥

要接入阿里云OSS,您需要拥有一个有效的 Access Key(包括AccessKeyId和AccessKeySecret)用来进行签名认证。可以通过如下步骤获得:

获取AccessKeyId和AccessKeySecret之后,您便可以按照以下步骤进行初始化。

新建OSSClient

使用OSS域名新建OSSClient

新建一个OSSClient代码如下:

  1. // endpoint以杭州为例,其它region请按实际情况填写
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 云账号AccessKey有所有API访问权限,建议遵循阿里云安全最佳实践,创建并使用RAM子账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // 创建OSSClient实例
  7. OSSClient client = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // 使用访问OSS
  9. // 关闭client
  10. client.shutdown();

说明:

  • 您的工程中可以有多个OSSClient,也可以只有一个OSSClient。
  • OSSClient可以并发使用。
  • OSS支持HTTPS,当您的安全需求更高时,可以使用HTTPS。
  • OSSClient.shutdown之后不能再使用。

使用自定义域名(CNAME)新建OSSClient

下面的代码让客户端使用CNAME访问OSS服务,CNAME更详细的信息请参考OSS自定义域名

  1. String endpoint = "<yourEndpoint>";
  2. // 云账号AccessKey有所有API访问权限,建议遵循阿里云安全最佳实践,创建并使用RAM子账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建
  3. String accessKeyId = "<yourAccessKeyId>";
  4. String accessKeySecret = "<yourAccessKeySecret>";
  5. // 创建ClientConfiguration实例,按照您的需要修改默认参数
  6. ClientConfiguration conf = new ClientConfiguration();
  7. // 开启支持CNAME选项
  8. conf.setSupportCname(true);
  9. // 创建OSSClient实例
  10. OSSClient client = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
  11. // 使用访问OSS
  12. // 关闭client
  13. client.shutdown();

注意:使用CNAME时无法使用ListBuckets接口。

使用IP新建OSSClient

某些特殊情况(比如专有域)下,您需要IP地址做作为endpoint。OSS Java sdk 2.1.2及以后版本,会自动检测到IP地址,不需要再调用setSLDEnabled设置;OSS Java sdk 2.1.2以前的版本,IP地址初始化时需要设置setSLDEnabled,代码如下:

  1. // 请按照实际IP填写
  2. String endpoint = "http://10.10.10.10";
  3. // 云账号AccessKey有所有API访问权限,建议遵循阿里云安全最佳实践,创建并使用RAM子账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // 创建ClientConfiguration实例,按照您的需要修改默认参数
  7. ClientConfiguration conf = new ClientConfiguration();
  8. // 开启二级域名访问OSS,默认不开启
  9. conf.setSLDEnabled(true)
  10. // 创建OSSClient实例
  11. OSSClient client = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
  12. // 使用访问OSS
  13. // 关闭client
  14. client.shutdown();

使用STS新建OSSClient

使用STS新建一个OSSClient代码如下,STS的详细信息请参考RAM和STS介绍

  1. // endpoint以杭州为例,其它region请按实际情况填写
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 临时账号accessKeyId/accessKeySecret/securityToken
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. String securityToken = "<yourSecurityToken>";
  7. // 创建OSSClient实例
  8. OSSClient client = new OSSClient(endpoint, accessKeyId, accessKeySecret, securityToken);
  9. // 使用访问OSS
  10. // 关闭client
  11. client.shutdown();

说明: Java sdk的STS过期自动处理功能,请参见授权访问

配置OSSClient

如果您需要修改OSSClient的一些默认配置,请在构造OSSClient的时候传入ClientConfiguration实例。ClientConfiguration是OSSClient的配置类,可配置代理、连接超时、最大连接数等参数。通过ClientConfiguration可以设置的参数见下表:

参数 描述 方法
MaxConnections 允许打开的最大HTTP连接数。默认为1024 ClientConfiguration.setMaxConnections
SocketTimeout Socket层传输数据的超时时间(单位:毫秒)。默认为50000毫秒 ClientConfiguration.setSocketTimeout
ConnectionTimeout 建立连接的超时时间(单位:毫秒)。默认为50000毫秒 ClientConfiguration.setConnectionTimeout
ConnectionRequestTimeout 从连接池中获取连接的超时时间(单位:毫秒)。默认不超时 ClientConfiguration.setConnectionRequestTimeout
IdleConnectionTime 如果空闲时间超过此参数的设定值,则关闭连接(单位:毫秒)。默认为60000毫秒 ClientConfiguration.setIdleConnectionTime
MaxErrorRetry 请求失败后最大的重试次数。默认3次 ClientConfiguration.setMaxErrorRetry
SupportCname 是否支持CNAME作为Endpoint,默认支持CNAME ClientConfiguration.setSupportCname
SLDEnabled 是否开启二级域名(Second Level Domain)的访问方式,默认不开启 ClientConfiguration.setSLDEnabled
Protocol 连接OSS所采用的协议(HTTP/HTTPS),默认为HTTP ClientConfiguration.setProtocol
UserAgent 用户代理,指HTTP的User-Agent头。默认为”aliyun-sdk-java” ClientConfiguration.setUserAgent
ProxyHost 代理服务器主机地址 ClientConfiguration.setProxyHost
ProxyPort 代理服务器端口 ClientConfiguration.setProxyPort
ProxyUsername 代理服务器验证的用户名 ClientConfiguration.setProxyUsername
ProxyPassword 代理服务器验证的密码 ClientConfiguration.setProxyPassword

使用ClientConfiguration设置OSSClient参数代码如下:

  1. // endpoint以杭州为例,其它region请按实际情况填写
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // 云账号AccessKey有所有API访问权限,建议遵循阿里云安全最佳实践,创建并使用RAM子账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // 创建ClientConfiguration实例
  7. ClientConfiguration conf = new ClientConfiguration();
  8. // 设置OSSClient使用的最大连接数,默认1024
  9. conf.setMaxConnections(200);
  10. // 设置请求超时时间,默认50秒
  11. conf.setSocketTimeout(10000);
  12. // 设置失败请求重试次数,默认3次
  13. conf.setMaxErrorRetry(5);
  14. // 创建OSSClient实例
  15. OSSClient client = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
  16. // 使用访问OSS
  17. // 关闭OSSClient
  18. client.shutdown();

说明:Java SDK超时设置的详细内容,请参见 Aliyun OSS Java SDK超时时间设置

本文导读目录
本文导读目录
以上内容是否对您有帮助?