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

建立有OSS系統管理權限的RAM使用者AccessKey。
使用ROS指令碼快速建立有OSS系統管理權限的RAM使用者AccessKey
在Resource Orchestration Service控制台的建立資源棧頁面的安全確認下，勾選確認，然後單擊建立。
建立完成後，在輸出中，複製建立的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。

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

重要

阿里雲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執行個體。
        // 當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();
    }
}

更多功能實踐配置樣本

單例模式配置樣本

說明

OSSClient是安全執行緒的，允許多線程訪問同一執行個體。您可以結合業務需求，採用單例模式建立並複用 OSSClient 執行個體。
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();
    }
}

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執行個體。
        // 當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	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()	設定自訂重試策略，一般不建議設定。

常見問題

如果您希望通過與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。