OSS SDK for C ++ を使用するためのOSSClientインスタンスの初期化 - Object Storage Service

OSSClientは、バケットやオブジェクトなどのObject Storage Service (OSS) リソースを管理するために使用されます。 OSS SDK for C ++ を使用してリクエストを開始するには、OSSClientインスタンスを初期化し、ClientConfigurationのデフォルト設定項目を変更する必要があります。

OSSClientインスタンスの作成

重要

OSSClientはスレッドセーフで、複数のスレッドを使用して同じインスタンスにアクセスできます。 OSSClientインスタンスを再利用するか、ビジネス要件に基づいて複数のOSSClientインスタンスを作成できます。
InitializeSdk() とShutdownSdk() は、プログラムのライフサイクル中に一度だけ呼び出す必要があるグローバル操作です。

(推奨) V4署名アルゴリズムの使用

より良いセキュリティを提供するV4署名アルゴリズムを使用することを推奨します。 V4署名アルゴリズムを使用する場合は、Regionパラメーターを含めます。リージョンパラメーターはAlibaba CloudリージョンIDである必要があります。例: cn-杭州 SignatureVersionType::V4も同時に宣言する必要があります。 OSS SDK for C ++ 1.10.0以降は、V4署名アルゴリズムをサポートしています。

次のサンプルコードは、OSSエンドポイントとV4署名アルゴリズムを使用してOSSClientインスタンスを作成する方法の例を示しています。 Security Token Service (STS) から取得したカスタムドメイン名またはアクセス資格情報を使用してOSSClientインスタンスを作成するには、次のサンプルコードを変更します。

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

int main(void)
{
    /* Initialize information about the account that is used to access 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 region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Initialize resources, such as network resources. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}

(非推奨) V1署名アルゴリズムの使用

重要

2024年12月1日以降、新しいUIDを持つ新規顧客は、OSSのV1署名アルゴリズムを利用できなくなります。 2025年6月1日以降、OSSはV1署名アルゴリズムを更新および維持しなくなり、V1署名アルゴリズムは新しいバケットで使用できなくなります。ビジネスへの影響を防ぐため、できるだけ早い機会にV1シグネチャをV4シグネチャにアップグレードします。

OSSエンドポイントの使用

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

int main(void)
{
    /* Initialize the information about the account that is used to access 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";
    
    /* Initialize resources, such as network resources. */
    InitializeSdk();

    ClientConfiguration conf;
    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);   

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}

カスタムドメイン名の使用

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

int main(void)
{
    /* Initialize the information about the account that is used to access OSS. */
            
    /* Set yourEndpoint to the custom domain name that you want to use. */
    std::string Endpoint = "yourEndpoint";
    
    /* Initialize resources, such as network resources. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.isCname = true;
    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);   

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}

STSから取得した一時的なアクセス資格情報の使用

Security Token Service (STS) によって提供される一時的なアクセス資格情報には、セキュリティトークンと一時的なAccessKeyペアが含まれます。 AccessKeyペアは、AccessKey IDとAccessKeyシークレットで構成されます。 STSから一時的なアクセス資格情報を取得する方法の詳細については、「STSが提供する一時的な資格情報を使用してOSSにアクセスする」をご参照ください。

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

int main(void)
{
    /* 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";
        
    /* Initialize resources, such as network resources. */
    InitializeSdk();

    ClientConfiguration conf;
    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the temporary AccessKey pair and security token are configured by using the environment variables. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf); 

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}

OSSClientインスタンスの設定

ClientConfiguration は OSSClient の設定クラスです。 ClientConfigurationを使用して、userAgent、connectTimeoutMs、maxConnectionsなどのパラメーターを設定できます。

OSSClientを使用してパラメーターを設定できます。下表に、各パラメーターを説明します。

パラメーター	説明
isCname	CNAMEをエンドポイントとして使用するかどうかを指定します。デフォルトでは、CNAMEは使用されません。
userAgent	ユーザーエージェント (user-agentヘッダー) 。デフォルト値: aliyun-sdk-cpp/1.X. X
maxConnections	接続の最大数。デフォルト値: 16。
requestTimeoutMs	リクエストのタイムアウト期間。タイムアウト期間を通じてデータが受信されない場合、接続は閉じられます。デフォルト値: 10000。単位：ミリ秒。
connectTimeoutMs	接続セットアップのタイムアウト時間。デフォルト値: 5000。単位：ミリ秒。
retryStrategy	リクエストが失敗した場合に許可される再試行の最大数。
proxyScheme	プロキシプロトコル。デフォルト値: HTTP。
proxyPort	プロキシサーバーへの接続に使用されるポート。
proxyPassword	プロキシサーバーへのログインに使用されるパスワード。
proxyUserName	プロキシサーバーへのログオンに使用されるユーザー名。
verifySSL	SSLベースの認証を有効にするかどうかを指定します。デフォルトでは、SSLベースの認証は無効になっています。説明デフォルトでは、SSLベースの認証はOSS SDK for C ++ 1.8.2以降で有効になっています。
caPath	CA証明書のルートパス。このパラメーターは、verifySSLがtrueに設定されている場合に有効です。デフォルトでは、このパラメータは空のままです。
caFile	CA証明書のパス。このパラメーターは、verifySSLがtrueに設定されている場合に有効です。デフォルトでは、このパラメータは空のままです。
enableCrc64	CRC-64を有効にするかどうかを指定します。デフォルトでは、CRC-64は有効です。
enableDateSkewAdjustment	HTTPリクエスト時間の自動修正を有効にするかどうかを指定します。デフォルトでは、HTTPリクエスト時間の自動修正が有効になっています。
sendRateLimiter	最大アップロード速度。単位: KB/s。
recvRateLimiter	最大ダウンロード速度。単位: KB/s。

タイムアウト期間の設定

次のコードは、タイムアウト期間を設定する方法の例を示しています。

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

int main(void)
{
    /* Initialize the information about the account that is used to access 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 region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Initialize resources, such as network resources. */
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    /* 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;

    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}

SSLベースの認証の設定

デフォルトでは、SSLベースの認証はOSS SDK for C ++ V1.8.2以降で有効になっています。 SSLベースの認証が失敗した場合は、SSL証明書のパスが正しいかどうかを確認するか、SSLベースの認証を無効にします。

次のサンプルコードは、SSLベースの認証を設定する方法の例を示しています。

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

int main(void)
{
    /* Initialize the information about the account that is used to access 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 region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Initialize resources, such as network resources. */
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    /* 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";;

    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);  

    /* Release resources, such as network resources. */
    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)
{
    /* Initialize the information about the account that is used to access 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 region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Specify the name of the bucket. Example: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Specify the full path of the object. Do not include the bucket name in the full path of the object. Example: exampledir/exampleobject.txt. */
    std::string ObjectName = "exampledir/exampleobject.txt";

    /* Initialize resources, such as network resources. */
    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;

    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

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

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

    /* Upload the object. Specify the full path of the local file. */
    auto outcome = client.PutObject(BucketName, ObjectName, "yourLocalFilename");  

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

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}

再試行ポリシーの設定

次のサンプルコードは、再試行ポリシーを設定する方法の例を示しています。

#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
{
    return (1 << attemptedRetries) * m_scaleFactor;
}

int main(void)
{
    /* Initialize the information about the account that is used to access 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 region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Initialize resources, such as network resources. */
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

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

    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf); 
    client.SetRegion(Region); 

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}

プロキシサーバーの設定

次のサンプルコードは、プロキシサーバーを構成する方法の例を示しています。

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

int main(void)
{
    /* Initialize the information about the account that is used to access 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 region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Initialize resources, such as network resources. */
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    /* Specify the address of the proxy server. */
    conf.proxyHost = "yourProxyHost";

    /* Set the port for the proxy server. */
    conf.proxyPort = 1234;

    /* Optional. Specify the username for proxy server authentication. */
    conf.proxyUserName = "yourProxyUserName";

    /* Optional. Specify the password for proxy server authentication. */
    conf.proxyPassword = "yourProxyPassword";

    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}