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簽名(不推薦)
阿里云對象存儲OSS自2025年03月01日起不再對新用戶(即新UID )開放使用V1簽名,并將于2025年09月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 | 代理服務器端口。 |
proxyPassword | 代理服務器驗證的密碼。 |
proxyUserName | 代理服務器驗證的用戶名。 |
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賬號信息。*/
/* 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;
/* 設置連接池數,默認為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);
client.SetRegion(Region);
/* 釋放網絡等資源。*/
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";
/* yourRegion填寫Bucket所在地域對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。*/
std::string Region = "yourRegion";
/* 初始化網絡等資源。*/
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
/* 設置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);
client.SetRegion(Region);
/* 釋放網絡等資源。*/
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";
/* yourRegion填寫Bucket所在地域對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。*/
std::string Region = "yourRegion";
/* 填寫Bucket名稱,例如examplebucket。*/
std::string BucketName = "examplebucket";
/* 填寫Object完整路徑,完整路徑中不能包含Bucket名稱,例如exampledir/exampleobject.txt。*/
std::string ObjectName = "exampledir/exampleobject.txt";
/* 初始化網絡等資源。*/
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
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);
client.SetRegion(Region);
/* 設置下載限速(單位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";
/* yourRegion填寫Bucket所在地域對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。*/
std::string Region = "yourRegion";
/* 初始化網絡等資源。*/
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
/* 設置失敗請求重試次數,默認為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);
client.SetRegion(Region);
/* 釋放網絡等資源。*/
ShutdownSdk();
return 0;
}
設置代理服務器
以下代碼用戶設置代理服務器:
#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;
/* 設置代理服務地址。*/
conf.proxyHost = "yourProxyHost";
/* 設置代理服務端口。*/
conf.proxyPort = 1234;
/* 設置代理服務器驗證的用戶名,可選。*/
conf.proxyUserName = "yourProxyUserName";
/* 設置代理服務器驗證的密碼,可選。*/
conf.proxyPassword = "yourProxyPassword";
/* 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量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;
}