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帳號資訊。*/
/* 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;
}
設定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";
/* yourRegion填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。*/
std::string Region = "yourRegion";
/* 初始化網路等資源。*/
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
/* 設定代理服務地址。*/
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);
client.SetRegion(Region);
/* 釋放網路等資源。*/
ShutdownSdk();
return 0;
}