Object Storage Service：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 -Dgpg.skip=true

配置訪問憑證

將 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預設網域名稱訪問時，可能會出現檔案禁止訪問、檔案無法預覽等問題；通過通過自訂網域名訪問OSS，不僅支援瀏覽器直接預覽檔案，還可結合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所在地區。以華北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)
                // 設定Proxy 伺服器
                // .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());
        }
    }
}