AI 助理
备案控制台
文档
输入文档关键字查找
首页 对象存储 开发参考 SDK参考 Java 高级配置 配置客户端

如何配置OSSClient

更新时间：
产品详情
我的收藏
重要

本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。

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

注意事项

  • 初始化OSSClient前，您需要配置访问凭证，本文以从环境变量读取访问凭证为例，详情请参见配置访问凭证。

  • 如果您希望获取关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。

  • 如果您希望创建RAM用户的AccessKey，请参见创建AccessKey。

  • 请使用OSS Java SDK 3.17.4及以上版本以支持V4签名，详情请参见安装SDK。

前置条件

警告

在配置客户端前，您需要先使用RAM用户AccessKey完成配置环境变量。

Linux

  1. 在命令行界面执行以下命令来将环境变量设置追加到~/.bashrc 文件中。

    echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

  2. 执行以下命令使变更生效。

    source ~/.bashrc

  3. 执行以下命令检查环境变量是否生效。

    echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

macOS

  1. 在终端中执行以下命令，查看默认Shell类型。

    echo $SHELL

  2. 根据默认Shell类型进行操作。

    Zsh

    1. 执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

    2. 执行以下命令使变更生效。

      source ~/.zshrc

    3. 执行以下命令检查环境变量是否生效。

      echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

    Bash

    1. 执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

    2. 执行以下命令使变更生效。

      source ~/.bash_profile

    3. 执行以下命令检查环境变量是否生效。

      echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

  1. 在CMD中运行以下命令。

    setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

  2. 运行以下命令，检查环境变量是否生效。

    echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%

PowerShell

  1. 在PowerShell中运行以下命令。

    [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

  2. 运行以下命令，检查环境变量是否生效。

    [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

默认配置示例

以下代码示例演示了如何使用V4签名和V1签名配置OSSClient。请注意，以下代码示例默认使用外网bucket默认域名以及RAM用户的AK信息。

V4签名（推荐）

重要

  • 使用V4签名算法初始化OSSClient时，您需要指定 Endpoint。本示例代码使用华东1（杭州）外网Endpoint：https://oss-cn-hangzhou.aliyuncs.com。如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。如需使用其它Endpoint请参见OSS地域和访问域名。

  • 使用V4签名算法初始化OSSClient时，您需要指定阿里云通用Region ID作为发起请求地域的标识，本示例代码使用以华东1（杭州）Region ID：cn-hangzhou。如需查询其它Region ID请参见OSS地域和访问域名。

  • 您需要在代码中显式声明使用 V4 签名算法，示例值：SignVersion.V4。

以下是使用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();
        // 显式声明使用 V4 签名算法
        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域名，请参见OSS地域和访问域名。

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;

public class OSSClientV1 {

    public static void main(String[] args) throws Exception {
        // 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(); 
    }
}

常见场景配置示例

如果您有配置其它域名的需求，请参考以下代码示例。请注意，以下代码示例默认使用V4签名以及RAM用户的AK信息。

内网域名配置示例

当您的应用部署在阿里云的ECS实例上，并且需要频繁访问同地域的OSS资源时，使用内网域名可以降低流量成本并提高访问速度。

以下是使用OSS内网域名配置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-internal.aliyuncs.com。
        String endpoint = "https://oss-cn-hangzhou-internal.aliyuncs.com";
        // 填写Endpoint对应的Region信息，例如cn-hangzhou。
        String region = "cn-hangzhou";

        // 从环境变量中获取访问凭证。运行本代码示例之前，请先配置环境变量。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        // 创建OSSClient实例。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // 显式声明使用 V4 签名算法
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

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

自定义域名配置示例

当您有多个不同的OSS bucket用于不同的目的时，可以通过为每个bucket设置不同的子域名来更好地管理和组织资源。

以下是使用自定义域名配置OSSClient的示例代码。

警告

您需要先将自定义域名绑定至Bucket默认域名，否则将引发报错！关于绑定自定义域名的详细操作，请参见绑定自定义域名至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请填写您的自定义域名。例如https://static.example.com。
        String endpoint = "yourEndpoint";
        // Endpoint请填写您对应的Region信息，例如cn-hangzhou。
        String region = "cn-hangzhou";

        // 从环境变量中获取访问凭证。运行本代码示例之前，请先配置环境变量。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        // 创建OSSClient实例。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // 请注意，设置true开启CNAME选项。
        clientBuilderConfiguration.setSupportCname(true);
        // 显式声明使用 V4 签名算法
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

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

专有域配置示例

以下是使用专有域配置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请填写您的专有域。例如：https://service.corp.example.com
        String endpoint = "yourEndpoint";
        // 填写Endpoint对应的Region信息，例如cn-hangzhou。
        String region = "cn-hangzhou";

        // 从环境变量中获取访问凭证。运行本代码示例之前，请先配置环境变量。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        // 创建OSSClient实例。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // 显式声明使用 V4 签名算法
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

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

IP地址配置示例

以下是使用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();
    }
}

代理服务器配置示例

如果您有配置客户端代理服务器的需求，请参考以下代码示例。

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();

        // 设置用户代理，指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();
    }
}

访问超时配置示例

如果您有配置客户端访问超时的需求，请参考以下代码示例。

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();

        // 设置允许打开的最大HTTP连接数。不设置时默认为1024。
        conf.setMaxConnections(1024);
        // 设置Socket层传输数据的超时时间（单位：毫秒）。不设置时默认为50000毫秒。
        conf.setSocketTimeout(50000);
        // 设置建立连接的超时时间（单位：毫秒）。不设置时默认为50000毫秒。
        conf.setConnectionTimeout(50000);
        // 设置从连接池中获取连接的超时时间（单位：毫秒）。不设置时默认无超时限制。
        conf.setConnectionRequestTimeout(60*60*24*1000);
        // 设置连接空闲超时时间，超时则关闭连接（单位：毫秒）。不设置时默认为60000毫秒。
        conf.setIdleConnectionTime(60000);

        // 创建OSSClient实例。
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(conf)
                .region(region)
                .build();

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

OSSClient的配置方法汇总

说明

ClientConfiguration类是OSSClient的配置类，您可以通过此类来配置OSSClient的代理、连接超时、最大连接数等参数。

方法

描述

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头。默认为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()

设置自定义重试策略，一般不建议设置。

常见问题

在业务代码中可以复用一个OSSClient实例吗？

  1. OSSClient是线程安全的，允许多线程访问同一实例。您可以结合业务需求，复用同一个OSSClient实例，也可以创建多个OSSClient实例，分别使用。

  2. OSSClient实例内部维持一个连接池。当OSSClient实例不再使用时，请调用shutdown方法将其关闭，避免创建过多的OSSClient实例导致资源耗尽。

如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint以提升传输速度

当您的使用场景对上传速度有要求时，建议您通过与OSS同地域的其他阿里云产品（如ECS服务器）访问OSS，并且请改成使用内网 Endpoint进行访问，请参见 ECS实例通过OSS内网地址访问OSS资源。

如何查看RAM用户的AK？是否可以查看旧的AccessKey Secret？

  1. 如需查看RAM用户的AK，请直接登录RAM控制台选择具体用户查看AK信息。

  2. RAM用户的AccessKey Secret仅在创建时显示，之后无法查看，若已经遗忘了的话无法找回。您可以直接访问RAM控制台选择具体用户，并创建新的AccessKey进行轮换。具体操作请参见创建AccessKey。

如果遇到报错问题该如何查询具体的错误类型？

关于错误类型的查询，OSS文档提供了EC错误码供您参阅，例如关于认证方面的常见报错问题，可参见02-AUTH。

上一篇：配置访问凭证下一篇：存储空间
文档推荐