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自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 | 代理服务器端口。 |
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;
}