OSSClient是OSS的Java客户端,用于管理存储空间和文件等OSS资源。使用Java SDK发起OSS请求,您需要初始化一个OSSClient实例,并根据需要修改ClientConfiguration的默认配置项。
注意事项
初始化OSSClient前,您需要配置访问凭证,本文以从环境变量读取访问凭证为例,详情请参见配置访问凭证。
新建OSSClient
OSSClient是线程安全的,允许多线程访问同一实例。您可以结合业务需求,复用同一个OSSClient实例,也可以创建多个OSSClient实例,分别使用。
OSSClient实例内部维持一个连接池。当OSSClient实例不再使用时,请调用shutdown方法将其关闭,避免创建过多的OSSClient实例导致资源耗尽。
V4签名(推荐)
推荐您使用更安全的V4签名算法。
使用V4签名算法初始化OSSClient时,您需要指定 Endpoint,示例值:https://oss-cn-hangzhou.aliyuncs.com。
您需要指定阿里云通用Region ID作为发起请求地域的标识,示例值:cn-hangzhou。
您需要在代码中显式声明使用 V4 签名算法,示例值:SignVersion.V4。
OSS Java SDK 3.17.4及以上版本支持V4签名。
使用OSS域名新建OSSClient
以下是使用OSS域名新建OSSClient并使用V4签名的示例代码。
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
public class OSSClientV4 {
public static void main(String[] args) throws Exception {
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填写Endpoint对应的Region信息,例如cn-hangzhou。
String region = "cn-hangzhou";
// 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建OSSClient实例。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
// 关闭OSSClient。
ossClient.shutdown();
}
}
专有云或专有域环境新建OSSClient
以下代码使用专有云或专有域环境新建OSSClient。
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
public class OSSClientV4 {
public static void main(String[] args) throws Exception {
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填写Endpoint对应的Region信息,例如cn-hangzhou。
String region = "cn-hangzhou";
// 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建OSSClient实例。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
// 关闭CNAME选项。
clientBuilderConfiguration.setSupportCname(false);
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
// 关闭OSSClient。
ossClient.shutdown();
}
}
使用自定义域名新建OSSClient
以下代码使用自定义域名新建OSSClient。关于使用自定义域名访问OSS的更多信息,请参见绑定自定义域名至Bucket默认域名。
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
public class OSSClientV4 {
public static void main(String[] args) throws Exception {
// yourEndpoint填写自定义域名。
String endpoint = "yourEndpoint";
// 填写Endpoint对应的Region信息,例如cn-hangzhou。
String region = "cn-hangzhou";
// 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建OSSClient实例。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
// 开启CNAME选项。
clientBuilderConfiguration.setSupportCname(true);
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
// 关闭OSSClient。
ossClient.shutdown();
}
}
使用IP新建OSSClient
以下代码使用IP新建OSSClient。
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
public class OSSClientV4 {
public static void main(String[] args) throws Exception {
// 某些特殊情况(例如专有域)下,您需要将IP地址作为Endpoint使用,请根据实际IP地址填写。
String endpoint = "https://10.10.10.10";
// 填写Endpoint对应的Region信息,例如cn-hangzhou。
String region = "cn-hangzhou";
// 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建OSSClient实例。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
// 开启二级域名访问OSS,默认不开启。OSS Java SDK 2.1.2及之前的版本需要设置此值,OSS Java SDK 2.1.2及之后的版本会自动检测到IP地址,不需要再设置此值。
clientBuilderConfiguration.setSLDEnabled(true);
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
// 关闭OSSClient。
ossClient.shutdown();
}
}
V1签名(不推荐)
阿里云对象存储OSS自2024年12月1日起不再对新用户(即新UID )开放使用V1签名,并将于2025年06月01日起停止更新与维护且不再对新增Bucket开放使用V1签名。请尽快切换到V4签名,避免影响服务。更多信息,请参见公告说明。
使用OSS域名新建OSSClient
以下代码使用OSS域名新建OSSClient。关于不同地域的OSS域名,请参见OSS地域和访问域名。
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
// 关闭OSSClient。
ossClient.shutdown();
使用自定义域名新建OSSClient
以下代码使用自定义域名新建OSSClient。关于使用自定义域名访问OSS的更多信息,请参见绑定自定义域名至Bucket默认域名。
使用自定义域名时无法使用ossClient.listBuckets方法。
// yourEndpoint填写自定义域名。
String endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建ClientBuilderConfiguration实例,您可以根据实际情况修改默认参数。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// 设置是否支持CNAME。CNAME用于将自定义域名绑定到目标Bucket。
conf.setSupportCname(true);
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf);
// 关闭OSSClient。
ossClient.shutdown();
使用STS新建OSSClient
以下代码使用STS新建OSSClient。
关于搭建STS服务的具体操作,请参见使用STS临时访问凭证访问OSS。
您可以通过调用STS服务的AssumeRole接口或者使用各语言STS SDK来获取临时访问凭证。
临时访问凭证包括临时访问密钥(AccessKeyId和AccessKeySecret)和安全令牌(SecurityToken)。临时访问凭证有效时间单位为秒,最小值为900,最大值以当前角色设定的最大会话时间为准。更多信息,请参见设置RAM角色最大会话时间。
完整代码示例,请参见使用签名URL下载。
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 从环境变量中获取STS的访问密钥(AccessKey ID和AccessKey Secret)和安全令牌(SecurityToken)作为访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
// 关闭OSSClient。
ossClient.shutdown();
使用STSAssumeRole新建OSSClient
以下代码使用STSAssumeRole新建OSSClient。
// 授权STSAssumeRole访问的Region。以华东1(杭州)为例,其它Region请根据实际情况填写。
String region = "cn-hangzhou";
// 从环境变量中获取RAM用户的访问密钥(AccessKeyId和AccessKeySecret)。运行本代码示例之前,请先配置环境变量。
String accessKeyId = System.getenv("ALIYUN_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("ALIYUN_ACCESS_KEY_SECRET");
// 从环境变量中获取RAM角色的RamRoleArn。运行本代码示例之前,请先配置环境变量。
String roleArn = System.getenv("ALIYUN_STS_ROLE_ARN");
// 创建STSAssumeRoleSessionCredentialsProvider实例。
STSAssumeRoleSessionCredentialsProvider credentialsProvider = CredentialsProviderFactory.newSTSAssumeRoleSessionCredentialsProvider(
region, accessKeyId, accessKeySecret, roleArn);
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 创建ClientBuilderConfiguration实例。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf);
// 关闭OSSClient。
ossClient.shutdown();
使用EcsRamRole新建OSSClient
在云服务器ECS上,您可以通过实例RAM角色的方式访问OSS。实例RAM角色允许您将一个角色关联到云服务器实例,在实例内部基于临时凭证STS访问OSS。临时凭证由系统自动生成和更新,应用程序可以使用指定的实例元数据URL获取临时凭证,无需特别管理。
以下代码用于使用EcsRamRole新建OSSClient。
// 以华东1(杭州)为例,其它endpoint请根据实际情况填写。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 通过ECS RAM角色获取访问凭证,例如以角色名(ecs-ram-role)访问为例。
InstanceProfileCredentialsProvider credentialsProvider = CredentialsProviderFactory.newInstanceProfileCredentialsProvider("ecs-ram-role");
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, new ClientBuilderConfiguration());
// 关闭OSSClient。
ossClient.shutdown();
专有云或专有域环境新建OSSClient
以下代码使用专有云或专有域环境新建OSSClient。
// yourEndpoint填写Bucket所在地域对应的Endpoint。
String endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建ClientBuilderConfiguration实例,您可以根据实际情况修改默认参数。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// 关闭CNAME选项。
conf.setSupportCname(false);
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf);
// 关闭OSSClient。
ossClient.shutdown();
使用IP新建OSSClient
以下代码使用IP新建OSSClient。
// 某些特殊情况(例如专有域)下,您需要将IP地址作为Endpoint使用,请根据实际IP地址填写。
String endpoint = "https://10.10.10.10";
// 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建ClientBuilderConfiguration。
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, credentialsProvider, conf);
// 关闭OSSClient。
ossClient.shutdown();
配置OSSClient
ClientConfiguration类是OSSClient的配置类,您可以通过此类来配置OSSClient的代理、连接超时、最大连接数等参数。
以下代码展示了使用ClientConfiguration类配置OSSClient的更多参数:
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
public class Demo {
public static void main(String[] args) throws Exception {
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填写Bucket所在地域。以华东1(杭州)为例,Region填写为cn-hangzhou。
String region = "cn-hangzhou";
// 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建ClientBuilderConfiguration。
// ClientBuilderConfiguration是OSSClient的配置类,可配置代理、连接超时、最大连接数等参数。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
// 设置OSSClient允许打开的最大HTTP连接数,默认为1024个。
conf.setMaxConnections(200);
// 设置用户代理,指HTTP的User-Agent头,默认为aliyun-sdk-java。
conf.setUserAgent("aliyun-sdk-java");
// 设置代理服务器IP,请将"<yourProxyHost>"替换为代理服务器的IP地址(如"196.128.xxx.xxx")。
conf.setProxyHost("<yourProxyHost>");
// 设置代理服务器验证的用户名,请将"<yourProxyUserName>"替换为代理服务器的用户名(如"root")。
conf.setProxyUsername("<yourProxyUserName>");
// 设置代理服务器验证的密码,请将"<yourProxyPassword>"替换为该用户的验证密码。
conf.setProxyPassword("<yourProxyPassword>");
// 创建OSSClient实例。
conf.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(conf)
.region(region)
.build();
// 关闭OSSClient。
ossClient.shutdown();
}
}
其中,ClientConfiguration类的常用方法列举如下:
方法 | 描述 |
ClientConfiguration.setMaxConnections | 设置允许打开的最大HTTP连接数。默认为1024。 |
ClientConfiguration.setSocketTimeout | 设置Socket层传输数据的超时时间(单位:毫秒)。默认为50000毫秒。 |
ClientConfiguration.setConnectionTimeout | 设置建立连接的超时时间(单位:毫秒)。默认为50000毫秒。 |
ClientConfiguration.setConnectionRequestTimeout | 设置从连接池中获取连接的超时时间(单位:毫秒)。默认不超时。 |
ClientConfiguration.setIdleConnectionTime | 设置连接空闲超时时间,超时则关闭连接(单位:毫秒)。默认为60000毫秒。 说明 关于超时时间设置的更多信息,请参见阿里云OSS Java SDK超时时间设置。 |
ClientConfiguration.setSupportCname | 是否支持CNAME作为Endpoint,默认支持CNAME。 |
ClientConfiguration.setSLDEnabled | 是否开启二级域名(Second Level Domain)的访问方式,默认不开启。 |
ClientConfiguration.setProtocol | 连接OSS所采用的协议(HTTP或HTTPS),默认为HTTP。 |
ClientConfiguration.setUserAgent | 用户代理,指HTTP的User-Agent头。默认为 |
ClientConfiguration.setProxyHost | 代理服务器主机地址。 |
ClientConfiguration.setProxyPort | 代理服务器端口。 |
ClientConfiguration.setProxyUsername | 代理服务器验证的用户名。 |
ClientConfiguration.setProxyPassword | 代理服务器验证的密码。 |
ClientConfiguration.setRedirectEnable | 是否开启HTTP重定向。 说明 Java SDK 3.10.1及以上版本支持设置是否开启HTTP重定向,默认开启。 |
ClientConfiguration.setVerifySSLEnable | 是否开启SSL证书校验。 说明 Java SDK 3.10.1及以上版本支持设置是否开启SSL证书校验,默认开启。 |
ClientConfiguration.setMaxErrorRetry | 请求失败后最大的重试次数。默认3次。 说明 当请求出现异常时,根据请求类型不同,OSS将采取不同的默认重试策略。
|
ClientConfiguration.setRetryStrategy() | 设置自定义重试策略,一般不建议设置。 |