C++初始化 - Object Storage Service

OssClient用於管理儲存空間（Bucket）和檔案（Object）等OSS資源。使用C++ SDK發起OSS請求時，您需要初始化一個OssClient執行個體，並根據需要修改ClientConfiguration的預設配置項。

建立OssClient

重要

OssClient是安全執行緒的，允許多線程訪問同一執行個體。您可以結合業務需求，複用同一個OssClient執行個體，也可以建立多個OssClient執行個體，分別使用。
InitializeSdk()和ShutdownSdk()是全域性介面，在程式生命週期內只需要調用一次。

V4簽名（推薦）

推薦使用更安全的V4簽名演算法。使用V4簽名初始化時，除指定Endpoint以外，您還需要指定阿里雲通用Region ID作為發起請求地區的標識，樣本值為cn-hangzhou。同時聲明SignatureVersionType::V4。OSS C++ SDK 1.10.0及以上版本支援V4簽名。

以使用OSS網域名稱建立OSSClient時使用V4簽名為例，其他通過自訂網域名、STS等建立OSSClient的情境可參考以下樣本執行相應修改。

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /* yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    /* yourRegion填寫Bucket所在地區對應的Region。以華東1（杭州）為例，Region填寫為cn-hangzhou。*/
    std::string Region = "yourRegion";
    
    /* 初始化網路等資源。*/
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}

V1簽名（不推薦）

重要

阿里雲Object Storage Service自2024年12月1日起不再對新使用者（即新UID ）開放使用V1簽名，並將於2025年06月01日起停止更新與維護且不再對新增Bucket開放使用V1簽名。請儘快切換到V4簽名，避免影響服務。更多資訊，請參見公告說明。

使用OSS網域名稱建立OSSClient

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /* yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    
    /* 初始化網路等資源。*/
    InitializeSdk();

    ClientConfiguration conf;
    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);   

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}

使用自訂網域名建立OSSClient

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /* yourEndpoint填寫自訂網域名。*/
    std::string Endpoint = "yourEndpoint";
    
    /* 初始化網路等資源。*/
    InitializeSdk();

    ClientConfiguration conf;
    conf.isCname = true;
    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);   

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}

使用STS建立OSSClient

STS臨時訪問憑證包括臨時存取金鑰（AccessKey ID和AccessKey Secret）和安全性權杖（SecurityToken）。關於如何擷取STS臨時訪問憑證的具體操作，請參見使用STS臨時訪問憑證訪問OSS。

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
        
    /* 初始化網路等資源。*/
    InitializeSdk();

    ClientConfiguration conf;
    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已通過環境變數設定臨時存取金鑰和安全性權杖。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf); 

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}

配置OssClient

ClientConfiguration是OssClient的配置類，您可通過此配置類來配置代理、連線逾時、最大串連數等參數。

通過OssClient可設定的參數如下：

參數	描述
isCname	是否支援直接使用Cname作為Endpoint。預設不支援。
userAgent	使用者代理程式，指HTTP的User-Agent頭。預設代理為aliyun-sdk-cpp/1.X.X。
maxConnections	串連池數。預設為16個。
requestTimeoutMs	請求逾時時間。請求逾時沒有收到資料將會關閉串連，預設為10000ms。
connectTimeoutMs	建立串連的逾時時間。預設為5000ms。
retryStrategy	自訂失敗重試策略。
proxyScheme	代理協議，預設為HTTP。
proxyPort	Proxy 伺服器連接埠。
proxyPassword	Proxy 伺服器驗證的密碼。
proxyUserName	Proxy 伺服器驗證的使用者名稱。
verifySSL	是否開啟SSL認證校正，預設關閉。說明 C++ SDK 1.8.2及以上版本預設開啟SSL認證校正。
caPath	用於設定CA認證根路徑，當verifySSL為true時有效，預設為空白。
caFile	用於設定CA憑證路徑，當verifySSL為true時有效，預設為空白。
enableCrc64	是否開啟CRC64校正，預設開啟。
enableDateSkewAdjustment	是否開啟HTTP請求時間自動修正，預設開啟。
sendRateLimiter	上傳限速（單位KB/s）。
recvRateLimiter	下載限速（單位KB/s）。

設定逾時時間

以下代碼用於設定逾時時間：

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /* 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    
    /* 初始化網路等資源。*/
    InitializeSdk();
    ClientConfiguration conf;

    /* 設定串連池數，預設為16個。*/
    conf.maxConnections = 20;

    /* 佈建要求逾時時間，逾時沒有收到資料就關閉串連，預設為10000ms。*/
    conf.requestTimeoutMs = 8000;

    /* 設定建立串連的逾時時間，預設為5000ms。*/
    conf.connectTimeoutMs = 8000;

    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);  

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}

設定SSL認證校正

C++ SDK 1.8.2及以上的版本預設自動開啟SSL認證校正。如果出現SSL認證校正失敗，您需要根據實際情況設定正確的憑證路徑，或者關閉SSL認證校正。

以下代碼用於設定SSL認證校正：

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /* yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    
    /* 初始化網路等資源。*/
    InitializeSdk();
    ClientConfiguration conf;

    /* 設定SSL認證校正開關，預設為true，即開啟認證校正。*/
    conf.verifySSL = true;

    /* 設定CA認證根路徑，當verifySSL為true時有效，預設為空白。*/
    conf.caPath = "/etc/ssl/certs/";

    /* 設定CA憑證路徑，當verifySSL為true時有效，預設為空白。*/
    conf.caFile = "/etc/ssl/certs/ca-certificates.crt";;

    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);  

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}

設定限速處理

以下代碼用於設定上傳或下載限速：

#include <alibabacloud/oss/OssClient.h>
#include <alibabacloud/oss/client/RateLimiter.h>

using namespace AlibabaCloud::OSS;

class UserRateLimiter : public RateLimiter
{
public:
    UserRateLimiter() : rate_(0) {};
    ~UserRateLimiter() {};
    virtual void setRate(int rate) { rate_ = rate; };
    virtual int Rate() const { return rate_; };
private:
    int rate_;
};

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /* yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    /* 填寫Bucket名稱，例如examplebucket。*/
    std::string BucketName = "examplebucket";
    /* 填寫Object完整路徑，完整路徑中不能包含Bucket名稱，例如exampledir/exampleobject.txt。*/
    std::string ObjectName = "exampledir/exampleobject.txt";

    /* 初始化網路等資源。*/
    InitializeSdk();

    ClientConfiguration conf;

    auto sendrateLimiter = std::make_shared<UserRateLimiter>();
    auto recvrateLimiter = std::make_shared<UserRateLimiter>();
    conf.sendRateLimiter = sendrateLimiter;
    conf.recvRateLimiter = recvrateLimiter;

    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);

    /* 設定下載限速（單位KB/s）。*/
    recvrateLimiter->setRate(256);

    /* 設定上傳限速（單位KB/s）。*/
    sendrateLimiter->setRate(256);

    /* 上傳檔案。yourLocalFilename填寫本地檔案完整路徑。*/
    auto outcome = client.PutObject(BucketName, ObjectName, "yourLocalFilename");  

    /* 上傳過程中更新上傳限速（單位KB/s）。*/
    sendrateLimiter->setRate(300);

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}

設定重試策略

以下代碼用於設定重試策略：

#include <alibabacloud/oss/OssClient.h>
#include <alibabacloud/oss/client/RetryStrategy.h>

using namespace AlibabaCloud::OSS;

class UserRetryStrategy : public RetryStrategy
{
public:

    /* maxRetries表示最大重試次數，scaleFactor為重試等待時間的尺度因子。*/
    UserRetryStrategy(long maxRetries = 3, long scaleFactor = 300) :
        m_scaleFactor(scaleFactor), m_maxRetries(maxRetries)  
    {}

    /* 您可以自訂shouldRetry函數，該函數用於判斷是否進行重試。*/
    bool shouldRetry(const Error & error, long attemptedRetries) const;

    /* 您可以自訂calcDelayTimeMs函數，該函數用於計算重試的延遲等待時間。*/
    long calcDelayTimeMs(const Error & error, long attemptedRetries) const;

private:
    long m_scaleFactor;
    long m_maxRetries;
};

bool UserRetryStrategy::shouldRetry(const Error & error, long attemptedRetries) const
{    
    if (attemptedRetries >= m_maxRetries)
        return false;

    long responseCode = error.Status();

    //http code
    if ((responseCode == 403 && error.Message().find("RequestTimeTooSkewed") != std::string::npos) ||
        (responseCode > 499 && responseCode < 599)) {
        return true;
    }
    else {
        switch (responseCode)
        {
        //curl error code
        case (ERROR_CURL_BASE + 7):  //CURLE_COULDNT_CONNECT
        case (ERROR_CURL_BASE + 18): //CURLE_PARTIAL_FILE
        case (ERROR_CURL_BASE + 23): //CURLE_WRITE_ERROR
        case (ERROR_CURL_BASE + 28): //CURLE_OPERATION_TIMEDOUT
        case (ERROR_CURL_BASE + 52): //CURLE_GOT_NOTHING
        case (ERROR_CURL_BASE + 55): //CURLE_SEND_ERROR
        case (ERROR_CURL_BASE + 56): //CURLE_RECV_ERROR
            return true;
        default:
            break;
        };
    }

    return false;
}

long UserRetryStrategy::calcDelayTimeMs(const Error & error, long attemptedRetries) const
{
    return (1 << attemptedRetries) * m_scaleFactor;
}

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /*yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    
    /* 初始化網路等資源。*/
    InitializeSdk();
    ClientConfiguration conf;

    /* 設定失敗請求重試次數，預設為3次。*/
    auto defaultRetryStrategy = std::make_shared<UserRetryStrategy>(5);
    conf.retryStrategy = defaultRetryStrategy;

    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);  

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}

設定Proxy 伺服器

以下代碼使用者佈建Proxy 伺服器：

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /* yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    
    /* 初始化網路等資源。*/
    InitializeSdk();
    ClientConfiguration conf;

    /* 設定代理服務地址。*/
    conf.proxyHost = "yourProxyHost";

    /* 設定代理服務連接埠。*/
    conf.proxyPort = 1234;

    /* 設定Proxy 伺服器驗證的使用者名稱,可選。*/
    conf.proxyUserName = "yourProxyUserName";

    /* 設定Proxy 伺服器驗證的密碼,可選。*/
    conf.proxyPassword = "yourProxyPassword";

    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);  

    /* 釋放網路等資源。*/
    ShutdownSdk();
    return 0;
}