全部产品
Search
文档中心

对象存储 OSS:如何配置OSSClient

更新时间:May 29, 2025

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完成配置环境变量。

  1. 创建有OSS管理权限的RAM用户AccessKey

    使用ROS脚本快速创建有OSS管理权限的RAM用户AccessKey

    在资源编排ROS控制台的创建资源栈页面的安全确认下,勾选确认,然后单击创建

    1.png

    创建完成后,在输出中,复制创建的AccessKey。

    image

  2. 使用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
      1. 执行以下命令使变更生效。

        source ~/.bashrc
      2. 执行以下命令检查环境变量是否生效。

        echo $OSS_ACCESS_KEY_ID
        echo $OSS_ACCESS_KEY_SECRET

    macOS

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

      echo $SHELL
      1. 根据默认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"
      1. 运行以下命令,检查环境变量是否生效。

        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)
      1. 运行以下命令,检查环境变量是否生效。

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

  3. 参考上述方式修改系统环境变量后,请重启或刷新您的编译运行环境,包括IDE、命令行界面、其他桌面应用程序及后台服务,以确保最新的系统环境变量成功加载。

默认配置示例

以下代码示例演示了如何使用V4签名和V1签名配置OSSClient

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

以下示例代码使用Bucket公网域名以及RAM用户的AK信息对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信息,以华东1(杭州)为例,Region填写为cn-hangzhou。
        String region = "cn-hangzhou";

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

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        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方法以释放资源。
        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实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
        
        // 使用OSSClient发起请求,例如执行文件上传、下载或管理等操作...
        
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        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信息,以华东1(杭州)为例,Region填写为cn-hangzhou。
        String region = "cn-hangzhou";

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

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        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方法以释放资源。
        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 = "https://static.example.com";
        // 填写Endpoint对应的Region信息,以华东1(杭州)为例,Region填写为cn-hangzhou。
        String region = "cn-hangzhou";

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

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        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.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 = "https://service.corp.example.com";
        // 填写Endpoint对应的Region信息,以华东1(杭州)为例,Region填写为cn-hangzhou。
        String region = "cn-hangzhou";

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

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        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方法以释放资源。
        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信息,以华东1(杭州)为例,Region填写为cn-hangzhou。
        String region = "cn-hangzhou";

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

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        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方法以释放资源。
        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 {
        // 填写Bucket所在地域对应的内网Endpoint。以华东1 金融云为例,Endpoint填写为"https://oss-cn-hzjbp-a-internal.aliyuncs.com"
        // 如需指定为http协议,请在指定域名时填写为"http://oss-cn-hzjbp-a-internal.aliyuncs.com"
        String endpoint = "https://oss-cn-hzjbp-a-internal.aliyuncs.com";
        // 填写Bucket所在地域。以华东1 金融云为例,Region填写为cn-hangzhou-finance
        String region = "cn-hangzhou-finance";

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

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        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方法以释放资源。
        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 {
        // 填写Bucket所在地域对应的内网Endpoint。以华北2 阿里政务云1为例,Endpoint填写为"https://oss-cn-north-2-gov-1-internal.aliyuncs.com"
        // 如需指定为http协议,请在指定域名时填写为"http://oss-cn-north-2-gov-1-internal.aliyuncs.com"
        String endpoint = "https://oss-cn-north-2-gov-1-internal.aliyuncs.com";
        // 填写Bucket所在地域。以华北2 阿里政务云1为例,Region填写为cn-north-2-gov-1
        String region = "cn-north-2-gov-1";

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

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        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方法以释放资源。
        ossClient.shutdown();
    }
}

更多功能实践配置示例

单例模式配置示例

说明
  1. OSSClient是线程安全的,允许多线程访问同一实例。您可以结合业务需求,采用单例模式创建并复用 OSSClient 实例。

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

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProvider;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.internal.OSSHeaders;
import com.aliyun.oss.model.*;
import java.io.ByteArrayInputStream;

public class OssClientSingleton {
    private OssClientSingleton() {}

    // 静态内部类实现单例(线程安全)
    private static class SingletonHolder {
        private static final OSS INSTANCE = create();

        private static OSS create() {
            try {
                // Endpoint以华东1(杭州)为例,其它Region请按实际情况填写。
                String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
                // 填写Bucket所在地域。以华东1(杭州)为例,Region填写为cn-hangzhou。
                String region = "cn-hangzhou";

                ClientBuilderConfiguration config = new ClientBuilderConfiguration();
                // 显式声明使用 V4 签名算法
                config.setSignatureVersion(SignVersion.V4);

                //从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
                CredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

                // 构建OSS客户端
                return OSSClientBuilder.create()
                        .endpoint(endpoint)
                        .credentialsProvider(credentialsProvider)
                        .clientConfiguration(config)
                        .region(region)
                        .build();
            } catch (Exception e) {
                throw new RuntimeException("OSS客户端初始化失败", e);
            }
        }
    }

    // 获取单例实例
    public static OSS getInstance() {
        return SingletonHolder.INSTANCE;
    }

    // 主函数测试PutObject操作
    public static void main(String[] args) {
        // 获取单例OSS客户端
        OSS ossClient = OssClientSingleton.getInstance();

        // 填写Bucket名称,例如examplebucket。
        String bucketName = "examplebucket";
        // 填写不包含Bucket名称在内的Object完整路径,例如testfolder/exampleobject.txt。
        String objectKey = "testfolder/exampleobject.txt";

        try {
            // 填写字符串。
            String content = "Hello OSS";

            // 创建PutObjectRequest对象。
            PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, objectKey, new ByteArrayInputStream(content.getBytes()));

            // 如果需要上传时设置存储类型和访问权限,请参考以下示例代码。
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
            metadata.setObjectAcl(CannedAccessControlList.Private);
            putObjectRequest.setMetadata(metadata);

            // 上传字符串。
            PutObjectResult result = ossClient.putObject(putObjectRequest);
            // 打印上传结果。
            System.out.println("文件上传成功!");
            System.out.println("ETag: " + result.getETag());
            System.out.println("请求ID: " + result.getRequestId());
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            // 在单例模式下,不建议在每次操作后关闭client(保持连接复用),避免影响后续使用。
            // 在明确OSSClient实例不再使用时(例如应用程序退出前),调用一次shutdown方法以释放资源。
            // ossClient.shutdown();
        }
    }
}

超时机制配置示例

请参考以下代码示例在初始化OSSClient时,添加可选参数配置请求的超时时间。

说明
  • ClientConfiguration.setMaxConnections:设置允许打开的最大HTTP连接数。默认为1024。

  • ClientConfiguration.setSocketTimeout:设置Socket层传输数据的超时时间(单位:毫秒)。默认为50000毫秒。

  • ClientConfiguration.setConnectionTimeout:设置建立连接的超时时间(单位:毫秒)。默认为50000毫秒。

  • ClientConfiguration.setConnectionRequestTimeout:设置从连接池中获取连接的超时时间(单位:毫秒)。默认不超时。

  • ClientConfiguration.setIdleConnectionTime:设置连接空闲超时时间,超时则关闭连接(单位:毫秒)。默认为60000毫秒。

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实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(conf)
                .region(region)
                .build();

        // 使用OSSClient发起请求,例如执行文件上传、下载或管理等操作...
        
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        ossClient.shutdown();
    }
}

重试策略配置示例

Java SDK 内部提供了重试机制以应对网络波动或短期服务异常等场景导致的请求失败,请参考以下代码示例在初始化OSSClient时,添加可选参数配置重试次数。

说明

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

  • 当请求为POST类型时,默认不重试。

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

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

    • 当异常为OSSException时,且返回的错误码不是InvalidResponse。

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

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();
        
        // 设置请求失败后最大的重试次数,默认值为3次。
        conf.setMaxErrorRetry(5); 

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(conf)
                .region(region)
                .build();

        // 使用OSSClient发起请求,例如执行文件上传、下载或管理等操作...
        
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        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实例。
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(conf)
                .region(region)
                .build();

        // 使用OSSClient发起请求,例如执行文件上传、下载或管理等操作...
        
        // 当OSSClient实例不再使用时,调用shutdown方法以释放资源。
        ossClient.shutdown();
    }
}

OSSClient的配置方法汇总

说明

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

方法

描述

ClientConfiguration.setMaxConnections

设置允许打开的最大HTTP连接数。默认为1024。

ClientConfiguration.setSocketTimeout

设置Socket层传输数据的超时时间(单位:毫秒)。默认为50000毫秒。

ClientConfiguration.setConnectionTimeout

设置建立连接的超时时间(单位:毫秒)。默认为50000毫秒。

ClientConfiguration.setConnectionRequestTimeout

设置从连接池中获取连接的超时时间(单位:毫秒)。默认不超时。

ClientConfiguration.setIdleConnectionTime

设置连接空闲超时时间,超时则关闭连接(单位:毫秒)。默认为60000毫秒。

说明

ClientConfiguration.setSupportCname

是否支持CNAME作为Endpoint,默认支持CNAME。

ClientConfiguration.setCrcCheckEnabled

是否支持开启crc校验,默认开启crc校验。

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

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

常见问题

如果您希望通过与OSS同地域的其他阿里云产品访问OSS,如何提升传输速度?

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

如何查看RAM用户的AK信息?

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

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

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

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