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

新建OSSClient

重要
  • OSSClient是线程安全的，允许多线程访问同一实例。您可以结合业务需求，复用同一个OSSClient实例，也可以创建多个OSSClient实例，分别使用。
  • OSSClient实例内部维持一个连接池。当OSSClient实例不再使用时，请调用shutdown方法将其关闭，避免创建过多的OSSClient实例导致资源耗尽。
  • 新建OSSClient时，需要指定Endpoint。关于Endpoint的更多信息，请参见访问域名和数据中心。

您可以通过以下多种方式新建OSSClient。

使用OSS域名新建OSSClient

以下代码用于使用OSS域名新建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";

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// 关闭OSSClient。
ossClient.shutdown();

使用自定义域名新建OSSClient

以下代码用于使用自定义域名新建OSSClient。

关于使用自定义域名访问OSS的更多信息，请参见绑定自定义域名。

// yourEndpoint填写自定义域名。
String endpoint = "yourEndpoint";
// 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";

// 创建ClientConfiguration实例，您可以根据实际情况修改默认参数。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// 设置是否支持CNAME。CNAME用于将自定义域名绑定到目标Bucket。
conf.setSupportCname(true);

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);

// 关闭OSSClient。
ossClient.shutdown();
重要 使用自定义域名时无法使用ossClient.listBuckets方法。

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

以下代码用于使用专有云或专有域环境新建OSSClient。

// yourEndpoint填写Bucket所在地域对应的Endpoint。
String endpoint = "yourEndpoint";
// 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";

// 创建ClientConfiguration实例，您可以根据实际情况修改默认参数。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// 关闭CNAME选项。
conf.setSupportCname(false);

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);

// 关闭OSSClient。
ossClient.shutdown();

使用IP新建OSSClient

以下代码用于使用IP新建OSSClient。

// 某些特殊情况（例如专有域）下，您需要将IP地址作为Endpoint使用，请根据实际IP地址填写。
String endpoint = "https://10.10.10.10";
// 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";

// 创建ClientConfiguration。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// 开启二级域名访问OSS，默认不开启。OSS Java SDK 2.1.2及之前的版本需要设置此值，OSS Java SDK 2.1.2及之后的版本会自动检测到IP地址，不需要再设置此值。
conf.setSLDEnabled(true);

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);

// 关闭OSSClient。
ossClient.shutdown();

使用STS新建OSSClient

以下代码用于使用STS新建OSSClient。

说明 关于搭建STS服务的具体操作，请参见使用STS临时访问凭证访问OSS。您可以通过调用STS服务的AssumeRole接口或者使用各语言STS SDK来获取临时访问凭证。临时访问凭证包括临时访问密钥（AccessKeyId和AccessKeySecret）和安全令牌（SecurityToken）。临时访问凭证有效时间单位为秒，最小值为900，最大值以当前角色设定的最大会话时间为准。更多信息，请参见设置角色最大会话时间。
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 从STS服务获取的临时访问密钥（AccessKey ID和AccessKey Secret）。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 从STS服务获取的安全令牌（SecurityToken）。
String securityToken = "yourSecurityToken";

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, securityToken);

// 关闭OSSClient。
ossClient.shutdown();

更多信息，请参见授权访问。

使用STSAssumeRole新建OSSClient

以下代码用于使用STSAssumeRole新建OSSClient。

// 授权STSAssumeRole访问的Region。以华东1（杭州）为例，其它Region请根据实际情况填写。
String region = "cn-hangzhou";
// 填写RAM用户的访问密钥（AccessKeyId和AccessKeySecret）。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 填写角色的ARN信息，即需要扮演的角色ID。格式为acs:ram::$accountID:role/$roleName。
// $accountID为阿里云账号ID。您可以通过登录阿里云控制台，将鼠标悬停在右上角头像的位置，直接查看和复制账号ID，或者单击基本资料查看账号ID。
// $roleName为RAM角色名称。您可以通过登录RAM控制台，单击左侧导航栏的RAM角色管理，在RAM角色名称列表下进行查看。
String roleArn = "acs:ram::17464958********:role/ossststest";   
// 创建STSAssumeRoleSessionCredentialsProvider实例。
STSAssumeRoleSessionCredentialsProvider provider = CredentialsProviderFactory.newSTSAssumeRoleSessionCredentialsProvider(
region, accessKeyId, accessKeySecret, roleArn);
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 创建ClientConfiguration实例。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();

 
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, provider, conf);

// 关闭OSSClient。
ossClient.shutdown();

更多信息，请参见使用STS临时访问凭证访问OSS。

使用EcsRamRole新建OSSClient

在云服务器ECS上，您可以通过实例RAM角色的方式访问OSS。实例RAM角色允许您将一个角色关联到云服务器实例，在实例内部基于临时凭证STS访问OSS。临时凭证由系统自动生成和更新，应用程序可以使用指定的实例元数据URL获取临时凭证，无需特别管理。

以下代码用于使用EcsRamRole新建OSSClient.

// 通过ECS RAM角色访问OSS。
// 以华东1（杭州）为例，其它endpoint请根据实际情况填写。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";     

// 通过ECS RAM角色获取访问凭证，例如以角色名（ecs-ram-role）访问为例。
InstanceProfileCredentialsProvider provider = CredentialsProviderFactory.newInstanceProfileCredentialsProvider("ecs-ram-role");

// 创建OSSClient实例。
 OSS ossClient = new OSSClientBuilder().build(endpoint, provider, new ClientBuilderConfiguration());

// 关闭OSSClient。
ossClient.shutdown();

配置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-java。ClientConfiguration.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将采取不同的默认重试策略。
  • 当请求为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();