如何配置OSSClient - Object Storage Service

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完成配置環境變數。

使用RAM使用者AccessKey配置環境變數。

Linux

在命令列介面執行以下命令來將環境變數設定追加到~/.bashrc 檔案中。

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

執行以下命令使變更生效。
```
source ~/.bashrc
```

執行以下命令檢查環境變數是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

macOS

在終端中執行以下命令，查看預設Shell類型。

echo $SHELL

根據預設Shell類型進行操作。

Zsh

執行以下命令來將環境變數設定追加到 ~/.zshrc 檔案中。

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

執行以下命令使變更生效。
```
source ~/.zshrc
```

執行以下命令檢查環境變數是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Bash

執行以下命令來將環境變數設定追加到 ~/.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

執行以下命令使變更生效。
```
source ~/.bash_profile
```

執行以下命令檢查環境變數是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

在CMD中運行以下命令。

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

運行以下命令，檢查環境變數是否生效。
```
echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
```

PowerShell

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

運行以下命令，檢查環境變數是否生效。

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

參考上述方式修改系統內容變數後，請重啟或重新整理您的編譯運行環境，包括IDE、命令列介面、其他傳統型應用程式及後台服務，以確保最新的系統內容變數成功載入。

預設配置樣本

以下程式碼範例示範了如何使用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簽名（不推薦）

重要

阿里雲Object Storage Service自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 = "https://static.example.com";
        // 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 = "https://service.corp.example.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();
    }
}

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

Proxy 伺服器配置樣本

如果您有配置用戶端Proxy 伺服器的需求，請參考以下程式碼範例。

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");
        // 設定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();
    }
}

訪問逾時配置樣本

如果您有配置用戶端訪問逾時的需求，請參考以下程式碼範例。

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毫秒。說明
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	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()	設定自訂重試策略，一般不建議設定。

常見問題

在業務代碼中可以複用一個OSSClient執行個體嗎？

OSSClient是安全執行緒的，允許多線程訪問同一執行個體。您可以結合業務需求，複用同一個OSSClient執行個體，也可以建立多個OSSClient執行個體，分別使用。
OSSClient執行個體內部維持一個串連池。當OSSClient執行個體不再使用時，請調用shutdown方法將其關閉，避免建立過多的OSSClient執行個體導致資源耗盡。

如果您希望通過與OSS同地區的其他阿里雲產品訪問OSS，如何提升傳輸速度？

當您的使用情境對上傳速度有要求時，建議您通過與OSS同地區的其他阿里雲產品（如ECS伺服器）訪問OSS，並且請改成使用內網 Endpoint進行訪問，請參見 ECS執行個體通過OSS內網地址訪問OSS資源。

如何查看RAM使用者的AK資訊？

如需查看RAM使用者的AK，請直接登入RAM控制台選擇具體使用者查看AK資訊。
RAM使用者的AccessKey Secret僅在建立時顯示，之後無法查看，若已經遺忘了的話無法找回。您可以直接存取RAM控制台選擇具體使用者，並建立新的AccessKey進行輪換。具體操作請參見建立AccessKey。

如果遇到報錯問題該如何查詢具體的錯誤類型？

關於錯誤類型的查詢，OSS文檔提供了EC錯誤碼供您參閱，例如關於認證方面的常見報錯問題，可參見02-AUTH。