初期化 - Object Storage Service - Alibaba Cloud ドキュメントセンター

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

OSSClient インスタンスの作成

重要

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

（推奨）V4 署名アルゴリズムを使用する

セキュリティが強化されているため、V4 署名アルゴリズムを使用することをお勧めします。 V4 署名アルゴリズムを使用する場合は、Region パラメーターを含めます。 Region パラメーターは、Alibaba Cloud リージョン ID である必要があります。例：cn-Hangzhou。同時に SignatureVersionType::V4 も宣言する必要があります。 C++ 1.10.0 以降の OSS SDK は、V4 署名アルゴリズムをサポートしています。

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

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

int main(void)
{
    /* OSSへのアクセスに使用するアカウントに関する情報を初期化します。*/
            
    /* バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
    /* バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 署名アルゴリズムを使用する

重要

2025 年 3 月 1 日以降、OSS の V1 署名アルゴリズムは、新しい UID を持つ新規のお客様はご利用いただけなくなります。 2025 年 9 月 1 日以降、OSS は V1 署名アルゴリズムの更新と保守を行わなくなり、V1 署名アルゴリズムは新しいバケットでは使用できなくなります。ビジネスへの影響を防ぐため、できるだけ早く V1 署名を V4 署名にアップグレードしてください。

OSS エンドポイントを使用する

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

int main(void)
{
    /* OSSへのアクセスに使用するアカウントに関する情報を初期化します。*/
            
    /* バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを 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;
}

カスタムドメイン名を使用する

#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 から取得した一時的なアクセス認証情報を使用する

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

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

int main(void)
{
    /* バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
        
    /* ネットワークリソースなどのリソースを初期化します。*/
    InitializeSdk();

    ClientConfiguration conf;
    /* 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、環境変数を使用して一時的な AccessKey ペアとセキュリティトークンが構成されていることを確認してください。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf); 

    /* ネットワークリソースなどのリソースを解放します。*/
    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 ベースの認証は無効になっています。説明 OSS SDK for C++ 1.8.2 以降では、デフォルトで SSL ベースの認証が有効になっています。
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)
{
    /* OSS にアクセスするために使用されるアカウントに関する情報を初期化します。*/
            
    /* バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
    /* バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。*/
    std::string Region = "yourRegion";
    
    /* ネットワークリソースなどのリソースを初期化します。*/
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    /* 最大接続数を指定します。デフォルト値：16 */
    conf.maxConnections = 20;

    /* リクエストタイムアウト期間を指定します。タイムアウト期間中にデータが受信されない場合、接続は閉じられます。単位：ミリ秒。デフォルト値：10000 */
    conf.requestTimeoutMs = 8000;

    /* 接続を確立するためのタイムアウト期間を指定します。単位：ミリ秒。デフォルト値：5000 */
    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 ベース認証の設定

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

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

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

int main(void)
{
    /* OSS にアクセスするために使用されるアカウントに関する情報を初期化します。*/
            
    /* バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
    /* バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。*/
    std::string Region = "yourRegion";
    
    /* ネットワークリソースなどのリソースを初期化します。*/
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    /* SSL ベース認証を設定します。デフォルト値：true。値 true は、SSL ベース認証が有効になっていることを指定します。*/
    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 にアクセスするために使用するアカウントの情報を初期化します。*/
            
    /* バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
    /* バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。*/
    std::string Region = "yourRegion";
    /* バケットの名前を指定します。例: examplebucket。*/
    std::string BucketName = "examplebucket";
    /* オブジェクトの完全なパスを指定します。オブジェクトの完全なパスにはバケット名を含めないでください。例: 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);

    /* オブジェクトをアップロードします。ローカルファイルの完全なパスを指定します。*/
    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 コード
    if ((responseCode == 403 && error.Message().find("RequestTimeTooSkewed") != std::string::npos) ||
        (responseCode > 499 && responseCode < 599)) {
        return true;
    }
    else {
        switch (responseCode)
        {
        //curl エラーコード
        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
        case (ERROR_CURL_BASE + 65): //CURLE_SEND_FAIL_REWIND
            return true;
        default:
            break;
        };
    }

    return false;
}

long UserRetryStrategy::calcDelayTimeMs(const Error & error, long attemptedRetries) const
{
    return (1 << attemptedRetries) * m_scaleFactor;
}

int main(void)
{
    /* OSS にアクセスするために使用されるアカウントの情報を初期化します。 */
            
    /* バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。 */
    std::string Endpoint = "yourEndpoint";
    /* バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 にアクセスするために使用されるアカウントに関する情報を初期化します。*/
            
    /* バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
    /* バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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;
}