如何建立和配置OSSClient執行個體 - Object Storage Service

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簽名（不推薦）

重要

阿里雲Object Storage Service自2024年12月1日起不再對新使用者（即新UID ）開放使用V1簽名，並將於2025年06月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

在Elastic Compute Service上，您可以通過執行個體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");
        // 設定Proxy 伺服器IP，請將"<yourProxyHost>"替換為Proxy 伺服器的IP地址（如"196.128.xxx.xxx"）。
        conf.setProxyHost("<yourProxyHost>");
        // 設定Proxy 伺服器驗證的使用者名稱，請將"<yourProxyUserName>"替換為Proxy 伺服器的使用者名稱（如"root"）。
        conf.setProxyUsername("<yourProxyUserName>");
        // 設定Proxy 伺服器驗證的密碼，請將"<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	Proxy 伺服器主機地址。
ClientConfiguration.setProxyPort	Proxy 伺服器連接埠。
ClientConfiguration.setProxyUsername	Proxy 伺服器驗證的使用者名稱。
ClientConfiguration.setProxyPassword	Proxy 伺服器驗證的密碼。
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()	設定自訂重試策略，一般不建議設定。