OSS C++ SDK V2 を使用すると、C++ アプリケーションから Alibaba Cloud OSS のオブジェクトをアップロード、ダウンロード、管理できます。ハイパフォーマンスなシナリオ、組み込みシステム、デスクトップアプリケーション向けに設計されています。
OSS C++ SDK V2 はプレビュー段階です。インターフェイスが変更となる可能性があります。アップデートについては、GitHub リポジトリのリリースノートを確認してください。
クイックスタート
次の手順に従って、SDK のインストール、認証情報の設定、およびクライアントの初期化を行います。
前提条件
-
C++17 以降のコンパイラ (GCC 7+、Clang 5+、または MSVC 2017+)。
-
CMake 3.15 以降。
cmake --version コマンドを実行して、CMake のバージョンを確認します。CMake がインストールされていない場合、またはバージョンが 3.15 より前の場合は、CMake をダウンロードしてインストールしてください。
SDK のインストール
vcpkg を使用したインストールを推奨します。
vcpkg
vcpkg パッケージマネージャーを使用して SDK をインストールします。
vcpkg install alibabacloud-oss-cpp-sdk-v2[curl]
# Windows では、代わりに WinHTTP を HTTP トランスポートレイヤーとして使用できます。
vcpkg install alibabacloud-oss-cpp-sdk-v2[winhttp]
オーバーレイポートを使用して、ソースコードからインストールすることもできます。
git clone https://github.com/aliyun/alibabacloud-oss-cpp-sdk-v2.git
vcpkg install alibabacloud-oss-cpp-sdk-v2[curl] --overlay-ports=alibabacloud-oss-cpp-sdk-v2/vcpkg --head
HTTP トランスポートレイヤー (curl または winhttp) はデフォルトで有効になっていないため、指定する必要があります。両方を有効にすることもできます。
openssl と mbedtls の両方が有効な場合、openssl が優先されます。
オプション機能:
|
機能 |
説明 |
|
|
libcurl に基づく HTTP トランスポートレイヤー。この機能はデフォルトでは有効になっていないため、インストールコマンドで |
|
|
WinHTTP に基づく HTTP トランスポートレイヤー (Windows のみ)。 |
|
|
ハッシュ計算に OpenSSL を使用します。 |
|
|
ハッシュ計算に mbedTLS を使用します。 |
|
|
クライアント側の暗号化を有効にします。Windows 以外のプラットフォームでは、 |
|
|
コンパイル時に実行時型情報 (RTTI) を有効にします。 |
|
|
SDK に含まれるバージョンではなく、システムにインストールされた |
完全な定義:「vcpkg/vcpkg.json」。
ソースコード
OSS C++ SDK V2 の最新バージョンを GitHub からダウンロードし、CMake でビルドおよびインストールします。
git clone https://github.com/aliyun/alibabacloud-oss-cpp-sdk-v2.git
cd alibabacloud-oss-cpp-sdk-v2
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build . --target install
使用可能な CMake オプション:
|
オプション |
説明 |
|
|
SDK を共有ライブラリとしてビルドします。デフォルトでは、静的ライブラリがビルドされます (OFF)。 |
|
|
libcurl を HTTP トランスポートレイヤーとして使用します。 |
|
|
WinHTTP を HTTP トランスポートレイヤーとして使用します (Windows のみ)。 |
|
|
SDK に含まれるバージョンではなく、システムにインストールされた |
|
|
システムにインストールされた |
|
|
システムにインストールされた |
|
|
システムにインストールされた |
|
|
C++23 標準の |
|
|
クライアント側の暗号化を有効にします。 |
|
|
実行時型情報 (RTTI) を有効にします。 |
プロジェクトの CMakeLists.txt ファイルに依存関係を追加します。
cmake_minimum_required(VERSION 3.15)
project(my-app)
find_package(alibabacloud_oss_v2 REQUIRED)
add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE alibabacloud_oss_v2::oss)
アクセス認証情報の設定
RAM ユーザーの AccessKey ペアを使用して環境変数を設定します。
RAM コンソール で、RAM ユーザーを作成し、永続的な AccessKey を生成します。AccessKey を保存し、ユーザーに AliyunOSSFullAccess 権限を付与します。
Linux
-
コマンドラインインターフェイスで次のコマンドを実行し、環境変数を
~/.bashrcファイルに追加します。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc-
次のコマンドを実行して、変更を適用します。
source ~/.bashrc -
次のコマンドを実行して、環境変数が設定されていることを確認します。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
-
macOS
-
ターミナルで、次のコマンドを実行して、デフォルトのシェルを確認します。
echo $SHELL-
以降の手順は、デフォルトのシェルによって異なります。
Zsh
-
次のコマンドを実行して、環境変数を
~/.zshrcファイルに追加します。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc -
次のコマンドを実行して、変更を適用します。
source ~/.zshrc -
次のコマンドを実行して、環境変数が設定されていることを確認します。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Bash
-
次のコマンドを実行して、環境変数を
~/.bash_profileファイルに追加します。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile -
次のコマンドを実行して、変更を適用します。
source ~/.bash_profile -
次のコマンドを実行して、環境変数が設定されていることを確認します。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
-
-
Windows
コマンド プロンプト
-
コマンド プロンプト (CMD) で、次のコマンドを実行します。
setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID" setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET" -
コマンド プロンプトを再度開き、次のコマンドを実行して、環境変数が設定されていることを確認します。
echo %OSS_ACCESS_KEY_ID% echo %OSS_ACCESS_KEY_SECRET%
PowerShell
-
PowerShell で、次のコマンドを実行します。
[System.Environment]::SetEnvironmentVariable('OSS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY_ID', [System.EnvironmentVariableTarget]::User) [System.Environment]::SetEnvironmentVariable('OSS_ACCESS_KEY_SECRET', 'YOUR_ACCESS_KEY_SECRET', [System.EnvironmentVariableTarget]::User) -
PowerShell を再度開き、次のコマンドを実行して、環境変数が設定されていることを確認します。
[System.Environment]::GetEnvironmentVariable('OSS_ACCESS_KEY_ID', [System.EnvironmentVariableTarget]::User) [System.Environment]::GetEnvironmentVariable('OSS_ACCESS_KEY_SECRET', [System.EnvironmentVariableTarget]::User)
クライアントの初期化
SDK は、OSSClient (同期)、OSSClient (非同期) (スレッドプールベース)、および OSSAsyncClient (非同期) (ネイティブ非同期) の 3 つのリクエストモードをサポートしています。次の例では、ListBuckets を使用して各モードを示します。
OSSClient (同期)
操作が完了するまで待機してから次に進む必要がある場合は、OSSClient 同期モードを使用します。
サンプルコードを実行する前に、<region-id>を実際のリージョンとエンドポイントに置き換えます。例:ap-southeast-1。
#include <iostream>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
namespace oss = alibabacloud::oss2;
int main() {
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
oss::OSSClient client(conf);
auto outcome = client.listBuckets(
oss::models::ListBucketsRequest());
if (!outcome.has_value()) {
auto& err = outcome.error();
std::cerr << "Error Code: " << err.getCode() << std::endl;
std::cerr << "Error Message: " << err.getMessage() << std::endl;
std::cerr << "Request ID: " << err.getRequestId() << std::endl;
return 1;
}
auto& result = outcome.value();
for (auto& bucket : result.getBuckets()) {
std::cout << "bucket: name:" << bucket.name
<< ", region:" << bucket.region
<< ", storageClass:" << bucket.storageClass
<< std::endl;
}
return 0;
}
OSSClient (非同期)
このスレッドプールベースの非同期モードでは、引き続き OSSClient を使用します。 conf.executor (スレッドプール) を設定した後、asyncCall() を呼び出して同期リクエストをスレッドプールに渡し、並列実行します。 この呼び出しは std::future を返し、呼び出し元は get() で結果を待機します。
conf.executorが設定されていない場合、asyncCall()はNoExecutorエラーを返します。
#include <future>
#include <iostream>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
#include "alibabacloud/oss2/utils/DefaultExecutor.h"
namespace oss = alibabacloud::oss2;
int main() {
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// ポイント: OSSClient の asyncCall() サポートを有効にするために、スレッドプールを設定します。
conf.executor = std::make_shared<oss::DefaultExecutor>();
oss::OSSClient client(conf);
// std::future を返す非同期呼び出し。
auto future = client.asyncCall(oss::models::ListBucketsRequest());
// get() を使用して結果を待機します (future パターン)。
auto outcome = future.get();
if (!outcome.has_value()) {
auto& err = outcome.error();
std::cerr << "Error Code: " << err.getCode() << std::endl;
std::cerr << "Error Message: " << err.getMessage() << std::endl;
return 1;
}
auto& result = outcome.value();
for (auto& bucket : result.getBuckets()) {
std::cout << "bucket: name:" << bucket.name
<< ", region:" << bucket.region
<< ", storageClass:" << bucket.storageClass
<< std::endl;
}
return 0;
}
並行アップロードおよびダウンロードの例:「AsyncCallOnSyncClient.cpp」および「AsyncCallbackOnSyncClient.cpp」。
OSSAsyncClient (非同期)
このネイティブ非同期モードは OSSAsyncClient を使用します。各操作には、対応する operationNameAsync() メソッドがあり、コールバックを介して結果を受け取るため、スレッドプールを設定する必要がなくなります。このモードは、大量の同時操作を必要とするシナリオに最適です。
サンプルコードを実行する前に、<region-id>を実際のリージョンとエンドポイントに置き換えます。例:ap-southeast-1。
#include <iostream>
#include <thread>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSAsyncClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
namespace oss = alibabacloud::oss2;
int main() {
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
auto client = std::make_shared<oss::OSSAsyncClient>(conf);
client->listBucketsAsync(
oss::models::ListBucketsRequest(),
oss::ListBucketsAsyncCallback([](oss::ListBucketsOutcome outcome) {
if (!outcome.has_value()) {
auto& err = outcome.error();
std::cerr << "Error Code: " << err.getCode() << std::endl;
std::cerr << "Error Message: " << err.getMessage() << std::endl;
return;
}
auto& result = outcome.value();
for (auto& bucket : result.getBuckets()) {
std::cout << "bucket: name:" << bucket.name
<< ", region:" << bucket.region
<< ", storageClass:" << bucket.storageClass
<< std::endl;
}
}));
// 非同期操作が完了するまで待機します。
std::this_thread::sleep_for(std::chrono::seconds(5));
return 0;
}
出力には、すべてのリージョンにわたるアカウント内のすべてのバケットが一覧表示されます。
クライアント設定
カスタムドメインの使用
カスタムドメイン を使用すると、ブラウザベースのファイルプレビューと CDN アクセラレーションによる配信が可能になります。
サンプルコードを実行する前に、<region-id>を リージョンとエンドポイント のリストにある実際のリージョン ID (例:ap-southeast-1) に置き換えてください。
#include <iostream>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
namespace oss = alibabacloud::oss2;
int main() {
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.endpoint = "https://your-custom-domain.com";
conf.useCName = true;
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
oss::OSSClient client(conf);
// カスタムドメインを使用して操作を実行します。
auto outcome = client.putObject(
oss::models::PutObjectRequest()
.setBucket("your-bucket")
.setKey("your-key")
.setBody(oss::RequestBody::fromString("Hello, OSS!")));
if (!outcome.has_value()) {
auto& err = outcome.error();
std::cerr << "エラー: " << err.getMessage() << std::endl;
return 1;
}
std::cout << "アップロードが成功しました" << std::endl;
return 0;
}
タイムアウト制御
connectTimeout と readWriteTimeout を使用して、接続および読み取り/書き込みタイムアウトをミリ秒単位で設定します。
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 接続タイムアウトを 10 秒に設定します。
conf.connectTimeout = 10000;
// 読み取り/書き込みタイムアウトを 30 秒に設定します。
conf.readWriteTimeout = 30000;
oss::OSSClient client(conf);
リトライポリシー
組み込みの StandardRetryer は、デフォルトで最大 3 回のリトライを行う FullJitterBackoff 戦略を使用します。調整するには retryMaxAttempts を使用します。
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 最大リトライ回数を 5 に設定します。
conf.retryMaxAttempts = 5;
oss::OSSClient client(conf);
カスタムリトライ戦略の例: CustomRetryStrategy.cpp。
HTTP/HTTPS プロトコル
デフォルトでは HTTPS プロトコルが使用されます。 HTTP プロトコルを使用するには、 disableSsl を true に設定します。
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// HTTP プロトコルを使用します。
conf.disableSsl = true;
oss::OSSClient client(conf);
内部エンドポイントの使用
Elastic Compute Service (ECS) にデプロイする場合、内部エンドポイントを使用してパブリックネットワークのトラフィックコストを回避できます。
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 内部エンドポイントを使用します。
conf.useInternalEndpoint = true;
oss::OSSClient client(conf);
転送アクセラレーションエンドポイントの使用
長距離のデータ転送には、転送アクセラレーションエンドポイントを使用します。
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 転送アクセラレーションエンドポイントを使用します。
conf.useAccelerateEndpoint = true;
oss::OSSClient client(conf);
カスタムドメイン (CNAME) の使用
カスタムドメイン (CNAME) を使用して OSS にアクセスします。
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
conf.endpoint = "https://your-custom-domain.com";
conf.useCName = true;
oss::OSSClient client(conf);
HTTP トランスポートのカスタマイズ
SDK はデフォルトで cURL を使用します。 httpTransport で置き換えることができます。 Windows では WinHTTP もサポートされています。
カスタムトランスポートの例: CurlCustomConfig.cpp と WinHttpCustomConfig.cpp。
アクセス認証情報の設定
SDK は次の認証情報メソッドをサポートしています:
RAM ユーザーのアクセスキー
セキュアでインターネットに公開されていない環境にあるアプリケーションでは、RAM ユーザーのアクセスキーを使用します。
環境変数 (推奨)
OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET の環境変数から認証情報を取得します。
-
RAM ユーザーのアクセスキーを使用して、環境変数を設定します。
Linux
-
コマンドラインから次のコマンドを実行し、環境変数の設定を
~/.bashrcファイルに追記します。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc -
次のコマンドを実行して、変更を反映します。
source ~/.bashrc -
次のコマンドを実行し、環境変数が設定されていることを確認します。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
macOS
-
ターミナルで次のコマンドを実行し、デフォルトのシェルの種類を確認します。
echo $SHELL -
デフォルトのシェルの種類に応じて手順に従ってください。
Zsh
-
次のコマンドを実行して、環境変数の設定を
~/.zshrcファイルに追記します。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc -
次のコマンドを実行して、変更を反映します。
source ~/.zshrc -
次のコマンドを実行し、環境変数が設定されていることを確認します。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Bash
-
次のコマンドを実行して、環境変数の設定を
~/.bash_profileファイルに追記します。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile -
次のコマンドを実行して、変更を反映します。
source ~/.bash_profile -
次のコマンドを実行し、環境変数が設定されていることを確認します。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
-
Windows
CMD
-
CMD で次のコマンドを実行します。
setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID" setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET" -
CMD を再度開き、次のコマンドを実行して環境変数が設定されていることを確認します。
echo %OSS_ACCESS_KEY_ID% echo %OSS_ACCESS_KEY_SECRET%
PowerShell
-
PowerShell で次のコマンドを実行します。
[System.Environment]::SetEnvironmentVariable('OSS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY_ID', [System.EnvironmentVariableTarget]::User) [System.Environment]::SetEnvironmentVariable('OSS_ACCESS_KEY_SECRET', 'YOUR_ACCESS_KEY_SECRET', [System.EnvironmentVariableTarget]::User) -
PowerShell を再度開き、次のコマンドを実行して環境変数が設定されていることを確認します。
[System.Environment]::GetEnvironmentVariable('OSS_ACCESS_KEY_ID', [System.EnvironmentVariableTarget]::User) [System.Environment]::GetEnvironmentVariable('OSS_ACCESS_KEY_SECRET', [System.EnvironmentVariableTarget]::User)
-
-
システムの環境変数を変更した後は、変更を反映するために IDE とターミナルを再起動してください。
-
環境変数を使用して認証情報を渡します。
サンプルコードを実行する前に、
<region-id>をcn-hangzhouなどの実際のリージョン ID に置き換えてください。#include "alibabacloud/oss2/ClientConfiguration.h" #include "alibabacloud/oss2/OSSClient.h" #include "alibabacloud/oss2/credentials/CredentialsProvider.h" namespace oss = alibabacloud::oss2; int main() { auto conf = oss::ClientConfiguration::loadDefault(); conf.region = "<region-id>"; conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>(); oss::OSSClient client(conf); // クライアントを使用して操作を実行します。 return 0; }
コードで明示的に指定
StaticCredentialsProvider を使用して、アクセスキー ID とシークレットアクセスキーを明示的に指定できます。
この方法ではアクセスキーがコードに直接記述されるため、テスト用途にのみ推奨します。本番環境では、環境変数など、より安全な方法を使用してください。
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
namespace oss = alibabacloud::oss2;
int main() {
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::StaticCredentialsProvider>(
"YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET");
oss::OSSClient client(conf);
// クライアントを使用して操作を実行します。
return 0;
}
STS 一時認証情報
STS 一時認証情報は、アクセスキー ID、シークレットアクセスキー、およびセキュリティトークンで構成されます。トークンは手動で管理し、更新する必要があります。
-
SDK を使用して STS 一時認証情報を取得する方法については、「STS 一時認証情報を使用して OSS にアクセスする」をご参照ください。
-
STS トークンを生成する際は、有効期限を指定する必要があります。トークンは有効期限が切れると自動的に無効になります。
-
STS から取得したアクセスキー ID は、たとえば
STS.L4aBSCSJVMuKg5U1****のように、接頭辞STSで始まることに注意してください。
環境変数 (推奨)
OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、および OSS_SESSION_TOKEN の環境変数を使用して、一時認証情報を取得します。
-
一時認証情報を使用して、環境変数を設定します。
macOS、Linux、または Unix
export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID> export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET> export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>Windows
set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID> set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET> set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN> -
環境変数を使用して認証情報を渡します。SDK の
EnvironmentVariableCredentialsProviderは、これら 3 つの環境変数を自動的に読み取ります。サンプルコードを実行する前に、
<region-id>をcn-hangzhouなどの実際のリージョン ID に置き換えてください。#include "alibabacloud/oss2/ClientConfiguration.h" #include "alibabacloud/oss2/OSSClient.h" #include "alibabacloud/oss2/credentials/CredentialsProvider.h" namespace oss = alibabacloud::oss2; int main() { auto conf = oss::ClientConfiguration::loadDefault(); conf.region = "<region-id>"; // OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、および OSS_SESSION_TOKEN を自動的に読み取ります。 conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>(); oss::OSSClient client(conf); // クライアントを使用して操作を実行します。 return 0; }
コードで明示的に指定
StaticCredentialsProvider を使用して、一時的なアクセスキー ID、シークレットアクセスキー、およびセキュリティトークンを明示的に指定できます。
テスト用途のみです。本番コードに認証情報を埋め込まないでください。代わりに、環境変数または SDK の自動更新メソッドを使用してください。
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
namespace oss = alibabacloud::oss2;
int main() {
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::StaticCredentialsProvider>(
"STS_ACCESS_KEY_ID", "STS_ACCESS_KEY_SECRET", "STS_SECURITY_TOKEN");
oss::OSSClient client(conf);
// クライアントを使用して操作を実行します。
return 0;
}
RAMRoleARN、ECSRAMRole、または OIDCRoleARN
RAMRoleARN、ECSRAMRole、OIDCRoleARN などの認証情報メソッドでは、CredentialsProviderFunc と併せて alibabacloud-credentials-cpp ライブラリを使用することを推奨します。
-
依存関係をインストールします。
vcpkg install alibabacloud-credentials-cpp -
CMakeLists.txt ファイルに依存関係を追加します。
find_package(alibabacloud_credentials REQUIRED) -
CredentialsProviderFuncを使用してライブラリを統合します。RAMRoleARN
#include "alibabacloud/oss2/ClientConfiguration.h" #include "alibabacloud/oss2/OSSClient.h" #include "alibabacloud/oss2/credentials/CredentialsProvider.h" #include <darabonba/core/Client.hpp> #include <alibabacloud/credential.hpp> namespace oss = alibabacloud::oss2; int main() { auto credConfig = std::make_shared<Alibabacloud_Credential::Config>(); // 認証情報のタイプは ram_role_arn である必要があります。 credConfig->type = std::make_shared<std::string>("ram_role_arn"); // RAM ユーザーのアクセスキー ID。ハードコードを避けるため、この値は ALIBABA_CLOUD_ACCESS_KEY_ID 環境変数を使用して設定することを推奨します。 credConfig->accessKeyId = std::make_shared<std::string>("YOUR_ACCESS_KEY_ID"); // RAM ユーザーのシークレットアクセスキー。ハードコードを避けるため、この値は ALIBABA_CLOUD_ACCESS_KEY_SECRET 環境変数を使用して設定することを推奨します。 credConfig->accessKeySecret = std::make_shared<std::string>("YOUR_ACCESS_KEY_SECRET"); // 引き受ける RAM ロールの ARN。例:acs:ram::123456789012****:role/adminrole // この値は ALIBABA_CLOUD_ROLE_ARN 環境変数を使用して設定することもできます。 credConfig->roleArn = std::make_shared<std::string>("YOUR_ROLE_ARN"); // 監査目的で使用されるロールセッション名。この値は ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数を使用して設定することもできます。 credConfig->roleSessionName = std::make_shared<std::string>("your-session-name"); // (オプション) ポリシーで権限をさらに制限します。このパラメーターは必須ではありません。 // 例:{"Statement":[{"Action":["oss:GetObject"],"Effect":"Allow","Resource":["*"]}],"Version":"1"} // credConfig->policy = std::make_shared<std::string>("<Policy>"); // (オプション) ロールセッションの有効期間 (秒)。デフォルト:3600 (1 時間)。このパラメーターは必須ではありません。 // credConfig->roleSessionExpiration = std::make_shared<long>(3600); auto credClient = std::make_shared<Alibabacloud_Credential::Client>(credConfig); auto conf = oss::ClientConfiguration::loadDefault(); conf.region = "<region-id>"; conf.credentialsProvider = std::make_shared<oss::CredentialsProviderFunc>( [credClient]() -> oss::Credentials { auto cred = credClient->getCredential(); auto ak = cred.getAccessKeyId(); auto sk = cred.getAccessKeySecret(); if (ak.empty() || sk.empty()) { return oss::Credentials::withRetryableError( "failed to get credentials from alibabacloud-credentials-cpp"); } auto token = cred.getSecurityToken(); return oss::Credentials(std::move(ak), std::move(sk), std::move(token)); }); oss::OSSClient client(conf); // クライアントを使用して操作を実行します。 return 0; }ECSRAMRole
#include "alibabacloud/oss2/ClientConfiguration.h" #include "alibabacloud/oss2/OSSClient.h" #include "alibabacloud/oss2/credentials/CredentialsProvider.h" #include <darabonba/core/Client.hpp> #include <alibabacloud/credential.hpp> namespace oss = alibabacloud::oss2; int main() { auto credConfig = std::make_shared<Alibabacloud_Credential::Config>(); // 認証情報のタイプは ecs_ram_role である必要があります。 credConfig->type = std::make_shared<std::string>("ecs_ram_role"); // ECS インスタンスに付与されている RAM ロールの名前。このパラメーターはオプションです。 // 設定しない場合、SDK はメタデータサービスから自動的に取得します。 // メタデータサービスへのリクエストを減らすため、このパラメーターは明示的に設定することを強く推奨します。 credConfig->roleName = std::make_shared<std::string>("YOUR_ECS_ROLE_NAME"); auto credClient = std::make_shared<Alibabacloud_Credential::Client>(credConfig); auto conf = oss::ClientConfiguration::loadDefault(); conf.region = "<region-id>"; conf.credentialsProvider = std::make_shared<oss::CredentialsProviderFunc>( [credClient]() -> oss::Credentials { auto cred = credClient->getCredential(); auto ak = cred.getAccessKeyId(); auto sk = cred.getAccessKeySecret(); if (ak.empty() || sk.empty()) { return oss::Credentials::withRetryableError( "failed to get credentials from alibabacloud-credentials-cpp"); } auto token = cred.getSecurityToken(); return oss::Credentials(std::move(ak), std::move(sk), std::move(token)); }); oss::OSSClient client(conf); // クライアントを使用して操作を実行します。 return 0; }OIDCRoleARN
#include "alibabacloud/oss2/ClientConfiguration.h" #include "alibabacloud/oss2/OSSClient.h" #include "alibabacloud/oss2/credentials/CredentialsProvider.h" #include <darabonba/core/Client.hpp> #include <alibabacloud/credential.hpp> namespace oss = alibabacloud::oss2; int main() { auto credConfig = std::make_shared<Alibabacloud_Credential::Config>(); // 認証情報のタイプは oidc_role_arn である必要があります。 credConfig->type = std::make_shared<std::string>("oidc_role_arn"); // 引き受ける RAM ロールの ARN。この値は ALIBABA_CLOUD_ROLE_ARN 環境変数を使用して設定することもできます。 credConfig->roleArn = std::make_shared<std::string>("YOUR_ROLE_ARN"); // OIDC ID プロバイダーの ARN。この値は ALIBABA_CLOUD_OIDC_PROVIDER_ARN 環境変数を使用して設定することもできます。 credConfig->oidcProviderArn = std::make_shared<std::string>("YOUR_OIDC_PROVIDER_ARN"); // OIDC トークンファイルへのパス。このファイルは RRSA によって pod に自動的にマウントされます。この値は ALIBABA_CLOUD_OIDC_TOKEN_FILE 環境変数を使用して設定することもできます。 credConfig->oidcTokenFilePath = std::make_shared<std::string>("/var/run/secrets/tokens/oidc-token"); // 監査目的で使用されるロールセッション名。この値は ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数を使用して設定することもできます。 credConfig->roleSessionName = std::make_shared<std::string>("your-session-name"); // (オプション) ポリシーで権限をさらに制限します。このパラメーターは必須ではありません。 // credConfig->policy = std::make_shared<std::string>("<Policy>"); auto credClient = std::make_shared<Alibabacloud_Credential::Client>(credConfig); auto conf = oss::ClientConfiguration::loadDefault(); conf.region = "<region-id>"; conf.credentialsProvider = std::make_shared<oss::CredentialsProviderFunc>( [credClient]() -> oss::Credentials { auto cred = credClient->getCredential(); auto ak = cred.getAccessKeyId(); auto sk = cred.getAccessKeySecret(); if (ak.empty() || sk.empty()) { return oss::Credentials::withRetryableError( "failed to get credentials from alibabacloud-credentials-cpp"); } auto token = cred.getSecurityToken(); return oss::Credentials(std::move(ak), std::move(sk), std::move(token)); }); oss::OSSClient client(conf); // クライアントを使用して操作を実行します。 return 0; }その他の認証情報の例については、「認証情報の例」をご参照ください。
匿名アクセス
認証情報なしで、公開読み取りのバケットとオブジェクトにアクセスします。
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
namespace oss = alibabacloud::oss2;
int main() {
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::AnonymousCredentialsProvider>();
oss::OSSClient client(conf);
// クライアントを使用して操作を実行します。
return 0;
}
カスタム認証情報プロバイダー
CredentialsProviderFunc を使用して、カスタムの認証情報取得ロジックを実装します。
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
#include <cstdlib>
namespace oss = alibabacloud::oss2;
// 例:カスタム環境変数または設定ファイルから認証情報を読み込みます。
static oss::Credentials loadCredentialsFromCustomSource() {
// 実際のアプリケーションでは、さまざまなソースから認証情報を取得できます。
// - 設定ファイル (例:~/.ossrc)
// - キー管理サービス (例:HashiCorp Vault または KMS)
// - メタデータサービス
// - データベース
const char* ak = std::getenv("MY_APP_ACCESS_KEY_ID");
const char* sk = std::getenv("MY_APP_ACCESS_KEY_SECRET");
const char* token = std::getenv("MY_APP_SESSION_TOKEN");
if (!ak || !sk) {
// エラーメッセージは OperationError::getMessage() に伝播します。
return oss::Credentials::withError(
"MY_APP_ACCESS_KEY_ID and MY_APP_ACCESS_KEY_SECRET must be set");
// ネットワークタイムアウトなどの一時的な障害では、withRetryableError を使用します。
// SDK は認証情報の取得を自動的にリトライします。
// return oss::Credentials::withRetryableError("...");
}
return oss::Credentials(ak, sk, token ? token : "");
}
int main() {
// カスタム認証情報プロバイダー関数は、認証情報が必要になるたびに呼び出されます。
// これにより、ローテーション、更新、またはキャッシュのロジックを実装できます。
auto provider = std::make_shared<oss::CredentialsProviderFunc>(
loadCredentialsFromCustomSource);
auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = provider;
oss::OSSClient client(conf);
// クライアントを使用して操作を実行します。
return 0;
}
API オペレーションの呼び出し
API オペレーションは、一貫した命名規則と呼び出しパターンに従います。
API の命名規則
メソッド名は キャメルケース を使用します。各オペレーションは <OperationName>Request パラメーターを受け取り、<OperationName>Outcome (Outcome<Result, Error>) を返します。
OSSClient (同期):
OutcomeType operationName(const models::OperationNameRequest& request, const OperationOptions* options = nullptr)
OSSAsyncClient (ネイティブ非同期):
void operationNameAsync(const models::OperationNameRequest& request, const OperationNameAsyncCallback& callback, const OperationOptions* options = nullptr)
呼び出しモード
|
呼び出しモード |
OSSClient |
OSSAsyncClient |
|
同期 |
|
- |
|
future ベースの非同期 |
|
|
|
コールバックベースの非同期 |
|
|
リクエストのキャンセル
CancellationToken を使用して長時間実行オペレーションをキャンセルするには、 OperationOptions で cancellationToken を渡します。 OSS C++ SDK V2 は 2 つのキャンセルモードを用意しています。
即時キャンセル
別のスレッドから CancellationTokenSource::cancel() を呼び出して、実行中のリクエストを中断します。
// 別のスレッドからリクエストをキャンセル
auto cts = oss::CancellationTokenSource::create();
oss::OperationOptions opts;
opts.cancellationToken = cts->getToken();
// 別のスレッドでリクエストを開始
auto future = std::async([&]() {
return client.getObject(request, &opts);
});
// 現在のスレッドからキャンセル
cts->cancel();
デッドラインによるキャンセル
cancelAfter() を呼び出してタイムアウトを設定します。 SDK は、タイムアウトすると自動的にリクエストをキャンセルします。
// 自動キャンセルのため、30秒のタイムアウトを設定します。
auto cts = oss::CancellationTokenSource::create();
cts->cancelAfter(std::chrono::seconds(30));
oss::OperationOptions opts;
opts.cancellationToken = cts->getToken();
auto outcome = client.getObject(request, &opts);
エラー処理
OSS C++ SDK V2 は Outcome<Result, Error> を使用します。 これは std::expected と互換性があります。 has_value() を呼び出して成功を確認します。 成功した場合は、 value() を使用するか、outcome オブジェクトを逆参照 (*outcome) して結果を取得します。 それ以外の場合は、 error() を使用してエラーオブジェクトを取得します。
auto outcome = client.putObject(request);
if (!outcome.has_value()) {
auto& err = outcome.error();
std::cerr << "Error code: " << err.getCode() << std::endl;
std::cerr << "Error message: " << err.getMessage() << std::endl;
std::cerr << "EC: " << err.getEC() << std::endl;
std::cerr << "Request ID: " << err.getRequestId() << std::endl;
std::cerr << "Request target: " << err.getRequestTarget() << std::endl;
}
-DUSE_STD_EXPECTED=ON フラグを使用してビルドする場合 (C++23)、 Outcome は std::expected の型エイリアスとなり、 .and_then()、 .transform()、 .or_else() などのモナド操作をサポートします。
サンプルコード
次の表に、利用可能なサンプルコードを示します。
|
カテゴリ |
説明 |
同期バージョン |
非同期バージョン |
|
バケット |
バケットの作成 |
||
|
バケットの一覧表示 |
|||
|
バケットの削除 |
|||
|
バケット情報の取得 |
|||
|
バケットのロケーションの取得 |
|||
|
オブジェクトのアップロード |
シンプルアップロード |
||
|
追加アップロード |
|||
|
マルチパートアップロード |
|||
|
マルチパートコピー |
|||
|
オブジェクトのダウンロード |
シンプルダウンロード |
||
|
オブジェクトのコピー |
|||
|
オブジェクトの管理 |
オブジェクトの一覧表示 |
||
|
オブジェクトの一覧表示 V2 |
|||
|
オブジェクトの削除 |
|||
|
複数のオブジェクトの削除 |
|||
|
オブジェクトメタデータの取得 |
|||
|
簡易オブジェクトメタデータの取得 |
|||
|
アーカイブ済みオブジェクト |
オブジェクトの復元 |
||
|
復元されたオブジェクトの削除 |
|||
|
シンボリックリンク |
シンボリックリンクの作成 |
||
|
シンボリックリンクの取得 |
|||
|
オブジェクトのタグ付け |
オブジェクトタグの設定 |
||
|
オブジェクトタグの取得 |
|||
|
オブジェクトタグの削除 |
|||
|
アクセス制御 |
バケット ACL の設定 |
||
|
バケット ACL の取得 |
|||
|
オブジェクト ACL の設定 |
|||
|
バージョニング |
バケットバージョニングの設定 |
||
|
バケットバージョニングステータスの取得 |
|||
|
オブジェクトバージョンの一覧表示 |
|||
|
ホットリンク保護 |
ホットリンク保護の設定 |
||
|
ホットリンク保護設定の取得 |
|||
|
システム機能 |
エンドポイント情報の取得 |
||
|
署名付き URL |
ダウンロード用の署名付き URL の生成 |
- |
|
|
アップロード用の署名付き URL の生成 |
- |
||
|
HEAD リクエスト用の署名付き URL の生成 |
- |
||
|
マルチパートアップロード用の署名付き URL の生成 |
- |
||
|
汎用 API |
|
- |
|
|
データ処理 |
オブジェクトの処理と結果の保存 |
||
|
非同期オブジェクト処理タスクの送信 |
|||
|
ページネーター |
すべてのバケットの一覧表示 |
- |
|
|
すべてのオブジェクトの一覧表示 (推奨) |
- |
||
|
すべてのオブジェクトバージョンの一覧表示 |
- |
||
|
すべてのアップロード済みパートの一覧表示 |
- |
||
|
すべてのマルチパートアップロードの一覧表示 |
- |
||
|
すべてのオブジェクトの一覧表示 (レガシー、非推奨) |
- |
||
|
シナリオ例 |
|
- |
|
|
|
- |
||
|
その他のシナリオ例 |
- |