初期化 (C++ SDK) - Object Storage Service - Alibaba Cloud ドキュメントセンター

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

OssClient インスタンスの作成

重要

OssClient クラスはスレッドセーフであり、複数のスレッドで同じインスタンスにアクセスできます。必要に応じて、同じ OssClient インスタンスを再利用したり、複数のインスタンスを作成したりできます。
InitializeSdk() と ShutdownSdk() はグローバル関数です。プログラムのライフサイクル中にこれらの関数を呼び出すのは一度だけにしてください。

(推奨) V4 署名

より安全な V4 署名アルゴリズムを使用することを推奨します。V4 署名を使用してインスタンスを初期化する場合、リクエストのエンドポイントと Alibaba Cloud リージョン ID の両方を指定する必要があります。たとえば、リージョン ID は cn-hangzhou のようになります。また、SignatureVersionType::V4 を宣言する必要もあります。C++ SDK バージョン 1.10.0 以降は V4 署名をサポートしています。

次のコードは、OSS ドメイン名と V4 署名を使用して OssClient インスタンスを作成する方法の例です。カスタムドメイン名または Security Token Service (STS) のアクセス認証情報を使用するには、例を適宜変更してください。

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

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

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

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

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

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

int main(void)
{
    /* yourEndpoint を、バケットが配置されているリージョンのエンドポイントに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを 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 を設定するためのクラスです。このクラスを使用して、プロキシ、接続タイムアウト、最大接続数などのパラメーターを設定できます。

OssClient には、次のパラメーターを設定できます：

パラメーター	説明
isCname	エンドポイントとして CNAME を使用するかどうかを指定します。デフォルトでは、この機能はサポートされていません。
userAgent	ユーザーエージェント。HTTP の User-Agent ヘッダーです。デフォルト値は aliyun-sdk-cpp/1.X.X です。
maxConnections	接続プールのサイズ。デフォルト値は 16 です。
requestTimeoutMs	リクエストのタイムアウト期間 (ミリ秒単位)。タイムアウト期間内にデータが受信されない場合、接続は閉じられます。デフォルト値は 10,000 ms です。
connectTimeoutMs	接続確立のタイムアウト期間。デフォルト値は 5,000 ms です。
retryStrategy	失敗したリクエストに対するカスタムリトライポリシー。
proxyScheme	プロキシのプロトコル。デフォルト値は HTTP です。
proxyPort	プロキシサーバーのポート。
proxyPassword	プロキシサーバー認証用のパスワード。
proxyUserName	プロキシサーバー認証用のユーザー名。
verifySSL	SSL 証明書検証を有効にするかどうかを指定します。デフォルトでは、この機能は無効になっています。説明 C++ SDK 1.8.2 以降のバージョンでは、デフォルトで SSL 証明書検証が有効になっています。
caPath	CA 証明書のルートパス。このパラメーターは、verifySSL が true に設定されている場合にのみ有効です。デフォルトでは、このパラメーターは空です。
caFile	CA 証明書のパス。このパラメーターは、verifySSL が true に設定されている場合にのみ有効です。デフォルトでは、このパラメーターは空です。
enableCrc64	64 ビット巡回冗長検査 (CRC64) 検証を有効にするかどうかを指定します。デフォルトでは、この機能は有効になっています。
enableDateSkewAdjustment	HTTP リクエスト時間のずれの自動補正を有効にするかどうかを指定します。デフォルトでは、この機能は有効になっています。
sendRateLimiter	アップロード速度制限 (KB/s)。
recvRateLimiter	ダウンロード速度制限 (KB/s)。

タイムアウト期間の設定

次のコードは、タイムアウト期間を設定する方法の例です：

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

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

    /* 接続プールのサイズを設定します。デフォルト値は 16 です。*/
    conf.maxConnections = 20;

    /* リクエストのタイムアウト期間を設定します。この期間内にデータが受信されない場合、接続は閉じられます。デフォルト値は 10,000 ms です。*/
    conf.requestTimeoutMs = 8000;

    /* 接続確立のタイムアウト期間を設定します。デフォルト値は 5,000 ms です。*/
    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 を、バケットが配置されているリージョンのエンドポイントに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
    /* yourRegion を、バケットが配置されているリージョンに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを 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 を、バケットが配置されているリージョンのエンドポイントに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
    /* yourRegion を、バケットが配置されているリージョンに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを 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);

    /* ファイルをアップロードします。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 コード
    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 アカウント情報を初期化します。*/
            
   /* yourEndpoint を、バケットが配置されているリージョンのエンドポイントに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
    /* yourRegion を、バケットが配置されているリージョンに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを 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 を、バケットが配置されているリージョンのエンドポイントに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。*/
    std::string Endpoint = "yourEndpoint";
    /* yourRegion を、バケットが配置されているリージョンに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを 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;
}