Object Storage Service:Initialization

Create an OSSClient instance

You can use one of the following methods to create an OSSClient instance:

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

/* Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. */
std::string Endpoint = "yourEndpoint";
/* The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. */
std::string AccessKeyId = "yourAccessKeyId";
std::string AccessKeySecret = "yourAccessKeySecret";

/* InitializeSdk() is called to initialize resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
InitializeSdk();

ClientConfiguration conf;
OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

/* ShutdownSdk() is called to release resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
ShutdownSdk();

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

/* Set yourEndpoint to the custom domain name that you want to use. */
String endpoint = "yourEndpoint";
std::string Endpoint = "yourEndpoint";
/* The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. */
std::string AccessKeyId = "yourAccessKeyId";
std::string AccessKeySecret = "yourAccessKeySecret";

/* InitializeSdk() is called to initialize resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
InitializeSdk();

ClientConfiguration conf;
conf.isCname = true;
OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

/* ShutdownSdk() is called to release resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
ShutdownSdk();

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

/* Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. */
std::string Endpoint = "yourEndpoint";
/* Specify the temporary AccessKey pair obtained from STS. */
std::string AccessKeyId = "yourAccessKeyId";
std::string AccessKeySecret = "yourAccessKeySecret";
/* Specify the security token obtained from STS. */
std::string SecurityToken = "yourSecurityToken";

/* InitializeSdk() is called to initialize resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
InitializeSdk();

ClientConfiguration conf;
OssClient client(Endpoint, AccessKeyId, AccessKeySecret, SecurityToken, conf);

/* ShutdownSdk() is called to release resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
ShutdownSdk();

Configure the OSSClient instance

ClientConfiguration is a configuration class of OSSClient. You can use ClientConfiguration to configure parameters, such as userAgent, connectTimeoutMs, and maxConnections.

You can configure parameters by using OSSClient. The following table describes the parameters.

Configure a timeout period

#include <alibabacloud/oss/OssClient.h>

using namespace AlibabaCloud::OSS;

int main(void)
{

    /* InitializeSdk() is called to initialize resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
    InitializeSdk();
    ClientConfiguration conf;

    /* Specify the maximum number of connections. Default value: 16. */
    conf.maxConnections = 20;

    /* Specify the request timeout period. The connection is closed if no data is received during the timeout period. Unit: milliseconds. Default value: 10000. */
    conf.requestTimeoutMs = 8000;

    /* Specify the timeout period to establish a connection. Unit: milliseconds. Default value: 5000. */
    conf.connectTimeoutMs = 8000;

    OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

    /* ShutdownSdk() is called to release resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
    ShutdownSdk();
    return 0;
}

Configure SSL-based authentication

By default, SSL-based authentication is enabled in OSS SDK for C++ V1.8.2 or later. If SSL-based authentication fails, you must set the correct path of the SSL certificate, or disable SSL-based authentication.

The following code provides an example on how to configure SSL-based authentication:

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

int main(void)
{

    /* InitializeSdk() is called to initialize resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
    InitializeSdk();
    ClientConfiguration conf;

    /* Configure SSL-based authentication. Default value: true. The value true specifies that SSL-based authentication is enabled. */
    conf.verifySSL = true;

    /* Specify the root path of the CA certificate. This parameter is valid if verifySSL is set to true. By default, this parameter is left empty. */
    conf.caPath = "/etc/ssl/certs/";

    /* Specify the path of the CA certificate. This parameter is valid if verifySSL is set to true. By default, this parameter is left empty. */
    conf.caFile = "/etc/ssl/certs/ca-certificates.crt";;

    OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

    /* ShutdownSdk() is called to release resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
    ShutdownSdk();
    return 0;
}

Configure bandwidth throttling

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

using namespace AlibabaCloud::OSS;

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

int main(void)
{
    /* Initialize the information about the account that is used to access OSS. */
    std::string AccessKeyId = "yourAccessKeyId";
    std::string AccessKeySecret = "yourAccessKeySecret";
    std::string Endpoint = "yourEndpoint";
    std::string BucketName = "yourBucketName";
    std::string ObjectName = "yourObjectName";

    /* InitializeSdk() is called to initialize resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
    InitializeSdk();

    ClientConfiguration conf;

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

    OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

    /* Configure bandwidth throttling for the download. Unit: Kbit/s. */
    recvrateLimiter->setRate(256);

    /* Configure bandwidth throttling for the upload. Unit: Kbit/s. */
    sendrateLimiter->setRate(256);

    /* Upload the object. */
    auto outcome = client.PutObject(BucketName, ObjectName,"yourLocalFilename");  

    /* Update the speed limit during the upload. Unit: KB/s. */
    sendrateLimiter->setRate(300);

    /* ShutdownSdk() is called to release resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
    ShutdownSdk();
    return 0;
}

Configure a retry policy

The following code provides an example on how to configure a retry policy:

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

using namespace AlibabaCloud::OSS;

class UserRetryStrategy : public RetryStrategy
{
public:

    /* maxRetries indicates the maximum number of allowed retry attempts. scaleFactor indicates the factor that is used to calculate the waiting time before a retry is attempted. */
    UserRetryStrategy(long maxRetries = 3, long scaleFactor = 300) :
        m_scaleFactor(scaleFactor), m_maxRetries(maxRetries)  
    {}

    /* You can specify the shouldRetry function to determine whether to retry a request. */
    bool shouldRetry(const Error & error, long attemptedRetries) const;

    /* You can specify the calcDelayTimeMs function to calculate the waiting time before a retry is attempted. */
    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
{
    UNUSED_PARAM(error);
    return (1 << attemptedRetries) * m_scaleFactor;
}

int main(void)
{
    /* InitializeSdk() is called to initialize resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
    InitializeSdk();

    ClientConfiguration conf;

    /* Configure the maximum number of allowed retry attempts if a request fails. Default value: 3. */
    auto defaultRetryStrategy = std::make_shared<UserRetryStrategy>(5);
    conf.retryStrategy = defaultRetryStrategy;

    OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

    /* ShutdownSdk() is called to release resources, such as network resources. You need to call this operation only once during the lifecycle of a program. */
    ShutdownSdk();
    return 0;
}