OSSClient是OSS的Java客户端,用于管理存储空间和文件等OSS资源。使用Java SDK发起OSS请求,您需要初始化一个OSSClient实例,并根据需要修改ClientConfiguration的默认配置项。

新建OSSClient

新建OSSClient时,需要指定Endpoint。有关Endpoint的更多信息,请参见访问域名和数据中心和自定义访问域名。

使用OSS域名新建OSSClient



使用自定义域名新建OSSClient



专有云或专有域环境新建OSSClient



使用IP新建OSSClient



使用STS新建OSSClient



使用STSAssumeRole新建OSSClient



使用EcsRamRole新建OSSClient




配置OSSClient

ClientConfiguration是OSSClient的配置类,您可通过此类来配置代理、连接超时、最大连接数等参数。可设置的参数如下:


参数描述方法
MaxConnections允许打开的最大HTTP连接数。默认为1024。ClientConfiguration.setMaxConnections
SocketTimeoutSocket层传输数据的超时时间(单位:毫秒)。默认为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-javaClientConfiguration.setUserAgent
ProxyHost代理服务器主机地址。ClientConfiguration.setProxyHost
ProxyPort代理服务器端口。ClientConfiguration.setProxyPort
ProxyUsername代理服务器验证的用户名。ClientConfiguration.setProxyUsername
ProxyPassword代理服务器验证的密码。ClientConfiguration.setProxyPassword
RedirectEnable是否开启HTTP重定向。说明 Java SDK 3.10.1及以上版本支持设置是否开启HTTP重定向,默认开启。ClientConfiguration.setRedirectEnable
VerifySSLEnable是否开启SSL证书校验。说明 Java SDK 3.10.1及以上版本支持设置是否开启SSL证书校验,默认开启。ClientConfiguration.setVerifySSLEnable

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

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。 String endpoint = "yourEndpoint"; // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。 String accessKeyId = "yourAccessKeyId"; String accessKeySecret = "yourAccessKeySecret"; // 创建ClientConfiguration。ClientConfiguration是OSSClient的配置类,可配置代理、连接超时、最大连接数等参数。 ClientBuilderConfiguration conf = new ClientBuilderConfiguration(); // 设置OSSClient允许打开的最大HTTP连接数,默认为1024个。 conf.setMaxConnections(200); // 设置Socket层传输数据的超时时间,默认为50000毫秒。 conf.setSocketTimeout(10000); // 设置建立连接的超时时间,默认为50000毫秒。 conf.setConnectionTimeout(10000); // 设置从连接池中获取连接的超时时间(单位:毫秒),默认不超时。 conf.setConnectionRequestTimeout(1000); // 设置连接空闲超时时间。超时则关闭连接,默认为60000毫秒。 conf.setIdleConnectionTime(10000); // 设置失败请求重试次数,默认为3次。 conf.setMaxErrorRetry(5); // 设置是否支持将自定义域名作为Endpoint,默认支持。 conf.setSupportCname(true); // 设置是否开启二级域名的访问方式,默认不开启。 conf.setSLDEnabled(true); // 设置连接OSS所使用的协议(HTTP或HTTPS),默认为HTTP。 conf.setProtocol(Protocol.HTTP); // 设置用户代理,指HTTP的User-Agent头,默认为aliyun-sdk-java。 conf.setUserAgent("aliyun-sdk-java"); // 设置代理服务器端口。 conf.setProxyHost("<yourProxyHost>"); // 设置代理服务器验证的用户名。 conf.setProxyUsername("<yourProxyUserName>"); // 设置代理服务器验证的密码。 conf.setProxyPassword("<yourProxyPassword>"); // 设置是否开启HTTP重定向,默认开启。 conf.setRedirectEnable(true); // 设置是否开启SSL证书校验,默认开启。 conf.setVerifySSLEnable(true); // 创建OSSClient实例。 OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf); // 关闭OSSClient。 ossClient.shutdown();

更多信息,请参见阿里云OSS Java SDK超时时间设置。

重试策略

当请求出现异常时,根据请求类型不同,OSS将采取不同的默认重试策略。
  • 当请求为POST类型时,默认不重试。

  • 当请求为非POST类型,且满足以下任意一种情况时,OSS会根据默认重试策略进行重试,最大重试次数为3次。

    • 当异常为ClientException时,错误码(errorCode)为ConnectionTimeout、SocketTimeout、ConnectionRefused、UnknownHost和SocketException。

    • 当异常为OSSException时,返回InvalidResponse以外的错误码。

    • 返回的状态码(statusCode)为500、502和503。

当默认重试策略不满足使用需求时,您可以通过ClientConfiguration配置类来自定义重试策略和最大重试次数,一般不建议自定义重试策略。自定义重试策略的示例如下:
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。 String endpoint = "yourEndpoint"; // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。 String accessKeyId = "yourAccessKeyId"; String accessKeySecret = "yourAccessKeySecret"; // 创建ClientConfiguration。 // ClientConfiguration是OSSClient的配置类,可用于配置重试次数、自定义重试策略、连接超时等参数。 ClientBuilderConfiguration conf= new ClientBuilderConfiguration(); // 设置失败请求重试次数,默认值为3次。 conf.setMaxErrorRetry(5); // 自定义重试策略,一般不建议设置。 // 假设TestRetryStrategy类为您自定义的重试策略,TestRetryStrategy类需要继承RetryStrategy。 conf.setRetryStrategy(new TestRetryStrategy()); // 创建OSSClient实例。 OSS ossClient=new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf); // 关闭OSSClient。 ossClient.shutdown();