OSS Java SDK V2（预览版）

环境准备

Java 8 及以上版本。

通过java -version命令查看 Java 版本。如果当前环境没有 Java 或版本低于 Java 8，请下载并安装Java。

安装SDK

建议使用 Maven 方式安装 OSS Java SDK V2。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>alibabacloud-oss-v2</artifactId>
    <version><!-- 填写最新版本号--></version>
</dependency>

mvn clean install -DskipTests

配置访问凭证

将 RAM 用户的 AccessKey 写入环境变量作为凭证。

在RAM 控制台，创建使用永久 AccessKey 访问的 RAM 用户，保存 AccessKey，然后为该用户授予AliyunOSSFullAccess权限。

初始化客户端

使用地域初始化 OSSClient。

• OSSClient 实现了 AutoCloseable，新建实例，采用 try resource 方式使用时，会自动释放资源，无需手动调用 close。

• OSSClient 创建和销毁是耗时的，可采用单例模式，复用 OSSClient，但应用终止前必须手动调用 close，否则资源会泄漏。

  单例模式

  public class OssClientSingleton {
      private OssClientSingleton() {}
  
      private static class Holder {
          private static final OSSClient INSTANCE = OSSClient.newBuilder()
              .credentialsProvider(new EnvironmentVariableCredentialsProvider())
              .region("cn-hangzhou")
              .build();
      }
  
      public static OSSClient getInstance() {
          return Holder.INSTANCE;
      }
  
      // 关闭 OSSClient（需显式调用）
      public static void shutdown() {
          try {
              getInstance().close();
          } catch (Exception e) {
              // 处理关闭异常
          }
      }
  }
  

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.exceptions.ServiceException;
import com.aliyun.sdk.service.oss2.models.*;
import com.aliyun.sdk.service.oss2.paginator.ListBucketsIterable;

public class Example {
    public static void main(String[] args) {
        String region = "cn-hangzhou";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        OSSClientBuilder clientBuilder = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region);

        try (OSSClient client = clientBuilder.build()) {

            ListBucketsIterable paginator = client.listBucketsPaginator(
                    ListBucketsRequest.newBuilder()
                            .build());

            for (ListBucketsResult result : paginator) {
                for (BucketSummary info : result.buckets()) {
                    System.out.printf("bucket: name:%s, region:%s, storageClass:%s\n", info.name(), info.region(), info.storageClass());
                }
            }

        } catch (Exception e) {
//            ServiceException se = ServiceException.asCause(e);
//            if (se != null) {
//                System.out.printf("ServiceException: requestId:%s, errorCode:%s\n", se.requestId(), se.errorCode());
//            }
            System.out.printf("error:\n%s", e);
        }
    }
}

import com.aliyun.sdk.service.oss2.OSSAsyncClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.exceptions.ServiceException;
import com.aliyun.sdk.service.oss2.models.*;

import java.util.concurrent.CompletableFuture;

public class ExampleAsync {
    public static void main(String[] args) {
        String region = "cn-hangzhou";
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSAsyncClient client = OSSAsyncClient.newBuilder()
                .region(region)
                .credentialsProvider(provider)
                .build()) {

            CompletableFuture<ListBucketsResult> future = client.listBucketsAsync(
                    ListBucketsRequest.newBuilder().build()
            );

            future.thenAccept(result -> {
                        for (BucketSummary info : result.buckets()) {
                            System.out.printf("bucket: name:%s, region:%s, storageClass:%s\n",
                                    info.name(), info.region(), info.storageClass());
                        }
                    })
                    .exceptionally(e -> {
//                ServiceException se = ServiceException.asCause(e);
//                if (se != null) {
//                    System.out.printf("Async ServiceException: requestId:%s, errorCode:%s\n",
//                            se.requestId(), se.errorCode());
//                }
                        System.out.printf("async error:\n%s\n", e);
                        return null;
                    });

            future.join();

        } catch (Exception e) {
            System.out.printf("main error:\n%s\n", e);
        }
    }
}

使用自定义域名

使用OSS默认域名访问时，可能会出现文件禁止访问、文件无法预览等问题；通过绑定自定义域名至Bucket默认域名，不仅支持浏览器直接预览文件，还可结合CDN加速分发。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        String region = "cn-hangzhou";

        // 请填写您的自定义域名。例如www.example-***.com
        String endpoint = "https://www.example-***.com";

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                // 请注意，设置true开启CNAME选项，否则无法使用自定义域名
                .useCName(true)
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

超时控制

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        String region = "cn-hangzhou";

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // 设置建立连接的超时时间, 默认值 5秒
                .connectTimeout(Duration.ofSeconds(30))
                // 设置应用读写数据的超时时间, 默认值 20秒
                .readWriteTimeout(Duration.ofSeconds(30))
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

重试策略

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import com.aliyun.sdk.service.oss2.retry.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        /*
         * SDK 重试策略配置说明：
         *
         * 默认重试策略：
         * 当没有配置重试策略时，SDK 使用 StandardRetryer 作为客户端的默认实现，其默认配置如下：
         * - maxAttempts：设置最大尝试次数。默认为3次
         * - maxBackoff：设置最大退避时间（单位：秒）。默认为20秒
         * - baseDelay：设置基础延迟时间（单位：秒）。默认为0.2秒
         * - backoffDelayer：设置退避算法。默认使用FullJitter退避算法
         *   计算公式为：[0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
         * - errorRetryables：可重试的错误类型，包括HTTP状态码、服务错误码、客户端错误等
         *
         * 当发生可重试错误时，将使用其提供的配置来延迟并随后重试该请求。
         * 请求的总体延迟会随着重试次数而增加，如果默认配置不满足您的场景需求时，
         * 可配置重试参数或者修改重试实现。
         */

        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        String region = "cn-hangzhou";

        // 配置重试策略示例：

        // 1. 自定义最大重试次数（默认为3次，这里设置为5次）
        Retryer customRetryer = StandardRetryer.newBuilder()
                .maxAttempts(5)
                .build();

        // 2. 自定义退避延迟时间
        // 调整基础延迟时间 baseDelay 为0.5秒（默认0.2秒），最大退避时间 maxBackoff 为25秒（默认20秒）
        // Retryer customRetryer = StandardRetryer.newBuilder()
        //         .backoffDelayer(new FullJitterBackoff(Duration.ofMillis(500), Duration.ofSeconds(25)))
        //         .build();

        // 3. 自定义退避算法
        // 使用固定时间退避算法替代默认的FullJitter算法，每次延迟2秒
        // Retryer customRetryer = StandardRetryer.newBuilder()
        //         .backoffDelayer(new FixedDelayBackoff(Duration.ofSeconds(2)))
        //         .build();

        // 4. 禁用重试策略
        // 如需禁用所有重试尝试时，可以使用NopRetryer实现
        // Retryer customRetryer = new NopRetryer();

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .retryer(customRetryer)
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

HTTP/HTTPS 协议

使用disableSsl(true)设置不使用HTTPS协议。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        String region = "cn-hangzhou";

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // 设置不使用https请求
                .disableSsl(true)
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

使用内网域名

使用内网域名访问同地域的OSS资源，可以降低流量成本并提高访问速度。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 方式一： 填写Region并设置useInternalEndpoint为true
        // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        String region = "cn-hangzhou";

        // // 方式二： 直接填写Region和Endpoint
        // // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        // String region = "cn-hangzhou";
        // // 填写Bucket所在地域对应的内网Endpoint。以华东1（杭州）为例，Endpoint填写为'oss-cn-hangzhou-internal.aliyuncs.com'
        // String endpoint = "oss-cn-hangzhou-internal.aliyuncs.com";

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .useInternalEndpoint(true)
                // .endpoint(endpoint) // 如果使用方式二，取消注释此行并注释上一行
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

使用传输加速域名

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 方式一： 填写Region并设置useAccelerateEndpoint为true
        // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        String region = "cn-hangzhou";

        // // 方式二： 直接填写Region和传输加速Endpoint
        // // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        // String region = "cn-hangzhou";
        // // 填写Bucket所在地域对应的传输加速Endpoint，例如'https://oss-accelerate.aliyuncs.com'
        // String endpoint = "https://oss-accelerate.aliyuncs.com";

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .useAccelerateEndpoint(true)
                // .endpoint(endpoint) // 如果使用方式二，取消注释此行并注释上一行
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

使用专有域

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        String region = "cn-hangzhou";

        // 请填写您的专有域。例如：https://service.corp.example.com
        String endpoint = "https://service.corp.example.com";

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

使用金融云域名

以下是使用金融云域名配置OSSClient的示例代码。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 填写Region和Endpoint
        // 填写Bucket所在地域。以华东1 金融云为例，Region填写为cn-hangzhou-finance
        String region = "cn-hangzhou-finance";
        // 填写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";

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

使用政务云域名

以下是使用政务云域名配置OSSClient的示例代码。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 填写Region和Endpoint
        // 填写Bucket所在地域。以华北2 阿里政务云1为例，Region填写为cn-north-2-gov-1
        String region = "cn-north-2-gov-1";
        // 填写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";

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

自定义HTTPClient

当常用配置参数无法满足场景需求时，您可以使用自定义 HTTP 客户端。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import com.aliyun.sdk.service.oss2.transport.HttpClient;
import com.aliyun.sdk.service.oss2.transport.HttpClientOptions;
import com.aliyun.sdk.service.oss2.transport.apache5client.Apache5HttpClientBuilder;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        // 从环境变量中加载凭证信息，用于身份验证
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
        String region = "cn-hangzhou";

        // 设置HTTP客户端的参数
        HttpClientOptions httpClientOptions = HttpClientOptions.custom()
                // 连接超时, 默认值 5秒
                .connectTimeout(Duration.ofSeconds(30))
                // 应用读写数据的超时时间, 默认值 20秒
                .readWriteTimeout(Duration.ofSeconds(30))
                // 最大连接数，默认值 1024
                .maxConnections(2048)
                // 是否跳过证书检查，默认不跳过
                .insecureSkipVerify(false)
                // 是否打开启HTTP重定向，默认不启用
                .redirectsEnabled(false)
                // 设置代理服务器
                // .proxyHost("http://user:passswd@proxy.example-***.com")
                .build();

        // 创建HTTP客户端，并传入HTTP客户端参数
        HttpClient httpClient = Apache5HttpClientBuilder.create()
                .options(httpClientOptions)
                .build();

        // 使用配置好的信息创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .httpClient(httpClient)
                .build()) {

            // 使用创建好的client执行后续操作...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

使用自定义访问凭证

当以上凭证配置方式不满足要求时，您可以自定义获取凭证的方式。Java SDK支持多种实现方式。

通过Supplier接口实现

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.Credentials;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProviderSupplier;

public class OSSExample {
    public static void main(String[] args) {
        // 创建自定义凭证提供者
        CredentialsProvider credentialsProvider = new CredentialsProviderSupplier(() -> {
            // TODO: 实现您的自定义凭证获取逻辑
            
            // 返回长期凭证
            return new Credentials("access_key_id", "access_key_secret");
            
            // 返回STS临时凭证（如果需要）
            // return new Credentials("sts_access_key_id", "sts_access_key_secret", "security_token");
        });
        
        // 创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("cn-hangzhou") // 填写Bucket所在地域
                .build()) {
            
            // 使用创建好的client执行后续操作...
            
        } catch (Exception e) {
            System.err.println("操作失败: " + e.getMessage());
        }
    }
}

匿名访问

如果您只需要访问公共读取权限的OSS资源，可以使用匿名访问方式，无需提供任何凭证。

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.AnonymousCredentialsProvider;

public class OSSExample {
    public static void main(String[] args) {
        // 创建匿名凭证提供者
        CredentialsProvider credentialsProvider = new AnonymousCredentialsProvider();
        
        // 创建OSS客户端
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("cn-hangzhou") // 填写Bucket所在地域
                .build()) {
            
            // 使用创建好的client执行后续操作...
            // 注意：匿名访问只能访问具有公共读取权限的资源
            
        } catch (Exception e) {
            System.err.println("操作失败: " + e.getMessage());
        }
    }
}