如何新建和配置OSSClient实例 - 对象存储 OSS

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自2025年03月01日起不再对新用户（即新UID ）开放使用V1签名，并将于2025年09月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毫秒。说明
ClientConfiguration.setSupportCname	是否支持CNAME作为Endpoint，默认支持CNAME。
ClientConfiguration.setSLDEnabled	是否开启二级域名（Second Level Domain）的访问方式，默认不开启。
ClientConfiguration.setProtocol	连接OSS所采用的协议（HTTP或HTTPS），默认为HTTP。
ClientConfiguration.setUserAgent	用户代理，指HTTP的User-Agent头。默认为`aliyun-sdk-java`。
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将采取不同的默认重试策略。当请求为POST类型时，默认不重试。当请求为非POST类型，且满足以下任意一种情况时，OSS会根据默认重试策略进行重试，最大重试次数为3次。当异常为ClientException时，且错误码（errorCode）为ConnectionTimeout、SocketTimeout、ConnectionRefused、UnknownHost和SocketException。当异常为OSSException时，且返回的错误码不是InvalidResponse。返回的状态码（statusCode）为500、502和503。
ClientConfiguration.setRetryStrategy()	设置自定义重试策略，一般不建议设置。