クイックスタート: C++ 用 Azure Blob Storage クライアント ライブラリ

C++ 用 Azure Blob Storage クライアント ライブラリを使用してみましょう。 Azure Blob Storage は、Microsoft のクラウド用オブジェクト ストレージ ソリューションです。 以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。

| API リファレンス ドキュメント | ライブラリのソース コード | サンプル |

前提条件

• Azure サブスクリプション - 無料アカウントを作成する
• Azure Storage アカウント - ストレージ アカウントの作成
• C++ コンパイラ
• CMake
• vcpkg - C および C++ パッケージ マネージャー

設定

このセクションでは、C++ 用 Azure Blob Storage クライアント ライブラリを操作するためのプロジェクトの準備について説明します。 Azure SDK for C++ を入手する最も簡単な方法は、vcpkg パッケージ マネージャーを使用することです。

パッケージのインストール

vcpkg install コマンドを使用し、C++ 用の Azure Blob Storage ライブラリと必要な依存関係をインストールします。

vcpkg.exe install azure-storage-blobs-cpp

Azure サービスにパスワードなしで接続するには、Azure ID ライブラリが必要です。

vcpkg.exe install azure-identity-cpp

プロジェクトのセットアップと Azure SDK for C++ の操作の詳細については、Azure SDK for C++ readme を参照してください。

プロジェクトを作成する

Visual Studio で、BlobQuickstart という、Windows 向けの新しい C++ コンソール アプリケーションを作成します。

オブジェクト モデル

Azure Blob Storage は、大量の非構造化データを格納するために最適化されています。 非構造化データとは、特定のデータ モデルや定義に従っていないデータであり、テキスト データやバイナリ データなどがあります。 Blob Storage には、3 種類のリソースがあります。

• ストレージ アカウント
• ストレージ アカウント内のコンテナー
• コンテナー内の BLOB

次の図に、これらのリソースの関係を示します。

これらのリソースとやり取りするには、これら C++ クラスを使用します。

• BlobServiceClient:BlobServiceClient クラスを使用して、Azure Storage リソースと BLOB コンテナーを操作できます。
• BlobContainerClient:BlobContainerClient クラスを使用して、Azure Storage コンテナーとその BLOB を操作できます。
• BlobClient:BlobClient クラスを使用して、Azure Storage BLOB を操作できます。 これは、特殊化されたすべての BLOB クラスの基底クラスです。
• BlockBlobClient: BlockBlobClient クラスを使用して、Azure Storage のブロック BLOB を操作できます。

コード例

以下のサンプル コード スニペットは、C++ 用 Azure Blob Storage クライアント ライブラリを使用して以下のタスクを実行する方法を示します。

• インクルード ファイルを追加する
• Azure に対する認証と BLOB データへのアクセスの承認
• コンテナーの作成
• コンテナーに BLOB をアップロードする
• コンテナー内の BLOB を一覧表示する
• BLOB をダウンロードする
• コンテナーの削除

インクルード ファイルを追加する

プロジェクト ディレクトリで次の操作を行います。

1. Visual Studio で BlobQuickstart.sln ソリューション ファイルを開きます
2. Visual Studio 内で、BlobQuickstart.cpp ソース ファイルを開きます
3. main 内の自動生成されたコードをすべて削除します。
4. #include と using namespace ステートメントを追加します

#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

Azure に対する認証と BLOB データへのアクセスの認可

Azure Blob Storage に対するアプリケーション要求は、認可されている必要があります。 Azure Identity クライアント ライブラリによって提供される DefaultAzureCredential クラスを使用することは、Blob Storage などのコード内の Azure サービスへのパスワードレス接続を実装するための推奨される方法です。

アカウント アクセス キーを使用して、Azure Blob Storage への要求を認可することもできます。 ただし、この方法は慎重に使用する必要があります。 開発者は、セキュリティで保護されていない場所にアクセス・キーを公開しないように注意する必要があります。 アクセス キーを持つすべてのユーザーは、ストレージ アカウントに対する要求を承認でき、実質的にすべてのデータにアクセスできます。 DefaultAzureCredential はアカウント・キーよりも管理しやすく、セキュリティが優れており、パスワードレス認証が可能になります。 両方のオプションの例を次に示します。

パスワードレス (推奨)

Azure ID ライブラリでは、Azure SDK で Microsoft Entra トークン認証のサポートが提供されます。 Microsoft Entra トークン認証をサポートする Azure SDK クライアントを構築するために使用できる一連の TokenCredential 実装を提供します。 DefaultAzureCredential は複数の認証方法をサポートしており、実行時に使用する方法が決定されます。

Microsoft Entra ユーザー アカウントにロールを割り当てる

ローカルで開発する場合は、BLOB データにアクセスするユーザー アカウントに正しいアクセス許可があることを確認します。 BLOB データの読み取りと書き込みを行うには、ストレージ BLOB データ共同作成者が必要です。 このロールを自分に割り当てるには、ユーザー アクセス管理者ロール、または Microsoft.Authorization/roleAssignments/write アクションを含む別のロールに割り当てられている必要があります。 Azure portal、Azure CLI、または Azure PowerShell を使用して、ユーザーに Azure RBAC ロールを割り当てることができます。 ロールの割り当てに使用できるスコープの詳細は、スコープの概要ページでご覧いただけます。

このシナリオでは、最小限の特権の原則に従って、ストレージ アカウントに限定したアクセス許可をユーザー アカウントに割り当てます。 この方法を使って、ユーザーに必要最小限のアクセス許可のみを与え、より安全な運用環境を作成します。

次の例では、ストレージ BLOB データ共同作成者ロールを自分のユーザー アカウントに割り当てます。これにより、そのストレージ アカウント内の BLOB データに対する読み取りと書き込みの両方のアクセス権が付与されます。

重要

ほとんどの場合、ロールの割り当てが Azure に反映されるまでの時間は 1 分から 2 分ですが、まれに 8 分程度までかかる場合があります。 初めてコードを実行したときに認証エラーを受け取る場合は、しばらく待ってから再試行してください。

Azure Portal

1. Azure portal で、メインの検索バーまたは左側のナビゲーションを使ってストレージ アカウントを見つけます。

2. ストレージ アカウントの概要ページで、左側のメニューから [アクセス制御 (IAM)] を選びます。

3. [アクセス制御 (IAM)] ページで、[ロールの割り当て] タブを選びます。

4. 上部のメニューから [+ 追加] を選択し、次に結果のドロップダウン メニューから [ロールの割り当ての追加] を選択します。

   

5. 検索ボックスを使って、結果を目的のロールに絞り込みます。 この例では、ストレージ BLOB データ共同作成者を検索し、一致する結果を選び、[次へ] を選びます。

6. [アクセスの割り当て先] で、[ユーザー、グループ、またはサービス プリンシパル] を選び、[+ メンバーの選択] を選びます。

7. ダイアログで、自分の Microsoft Entra ユーザー名 (通常は user@domain メール アドレス) を検索し、ダイアログの下部にある [選択] を選びます。

8. [レビューと割り当て] を選んで最終ページに移動し、もう一度 [レビューと割り当て] を行ってプロセスを完了します。

Azure CLI

Azure CLI を使ってリソース レベルでロールを割り当てるには、まず az storage account show コマンドを使ってリソース ID を取得する必要があります。 --query パラメーターを使って、出力プロパティをフィルター処理することができます。

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

前のコマンドからの出力 Id をコピーします。 これで、Azure CLI の az role コマンドを使ってロールを割り当てることができます。

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Azure PowerShell を使ってリソース レベルでロールを割り当てるには、まず Get-AzResource コマンドを使ってリソース ID を取得する必要があります。

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

前のコマンドの出力から Id の値をコピーします。 これで、PowerShell の New-AzRoleAssignment コマンドを使ってロールを割り当てることができます。

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

DefaultAzureCredential を使用して Azure にサインインしてアプリ コードを接続する

次の手順を使用して、ストレージ アカウント内のデータへのアクセスを認可できます。

1. 必ず、ストレージ アカウントにロールを割り当てたときと同じ Microsoft Entra アカウントを使って認証を受けてください。 Azure CLI から認証できます。 Azure CLI で次のコマンドを使用して Azure にサインインします。

   az login
   

2. DefaultAzureCredential を使用するには、azure-identity-cpp パッケージがインストールされており、次の #include が追加されていることを確認します。

   #include <azure/identity/default_azure_credential.hpp>
   

3. main() の末尾にこのコードを追加します。 ローカルのワークステーションでこのコードが実行されると、DefaultAzureCredential では開発者の Azure CLI 資格情報を利用して Azure に認証します。

   // Initialize an instance of DefaultAzureCredential
    auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();
   
    auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
    BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);
   

4. 必ず、BlobServiceClient オブジェクトの URI のストレージ アカウント名を更新してください。 ストレージ アカウント名は、Azure portal の概要ページで確認できます。

   

   Note

   運用環境で C++ SDK を使用しているとき、アプリケーションで使用されることがわかっている資格情報だけを有効にすることをお勧めします。 DefaultAzureCredential を使用する代わりに、特定の種類の資格情報を使用するか、サポートされている資格情報と共に ChainedTokenCredential を利用して認可してください。

接続文字列

接続文字列にはストレージ アカウント アクセス キーが含まれており、それを使用して要求を認可します。 セキュリティで保護されていない場所でキーを公開しないように常に注意してください。

注意

ストレージ アカウント アクセス キーを使用してデータ アクセスを認可するには、次の Azure RBAC アクションに対するアクセス許可が必要です: Microsoft.Storage/storageAccounts/listkeys/action。 このアクションのアクセス許可をもつ最小特権の組み込みロールは、閲覧者とデータ アクセスですが、このアクションを含むロールはすべて機能します。

Azure Portal

1. Azure portal にサインインします。

2. 自分のストレージ アカウントを探します。

3. ストレージ アカウント メニュー ウィンドウの [セキュリティとネットワーク] で、 [アクセス キー] を選択します。 ここで、アカウント アクセス キーと各キーの完全な接続文字列が確認できます。

4. [アクセス キー] ペインで、 [キーの表示] を選択します。

5. [key1] セクションで、 [接続文字列] の値を見つけます。 [クリップボードにコピー] アイコンを選択して、接続文字列をコピーします。 次のセクションで、この接続文字列の値を環境変数に追加します。

   

Azure CLI

az storage account show-connection-string コマンドを使ってストレージ アカウントの接続文字列を確認することができます。

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

PowerShell で Get-AzStorageAccount と Get-AzStorageAccountKey のコマンドを使って接続文字列をアセンブルすることができます。

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

ストレージ接続文字列の構成

接続文字列をコピーした後、アプリケーションを実行しているローカル マシンの新しい環境変数にそれを書き込みます。 環境変数を設定するには、コンソール ウィンドウを開いて、お使いのオペレーティング システムの手順に従います。 <yourconnectionstring> は、実際の接続文字列に置き換えてください。

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Windows で環境変数を追加した後、コマンド ウィンドウの新しいインスタンスを開始する必要があります。

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

次のコード例では、前に作成した環境変数からストレージ アカウントの接続文字列が取得され、接続文字列を使用してサービス クライアント オブジェクトが構築されます。

main() の末尾に次のコードを追加します。

    // Retrieve the connection string for use with the application. The storage
    // connection string is stored in an environment variable on the machine
    // running the application called AZURE_STORAGE_CONNECTION_STRING.
    // Note that _MSC_VER is set when using MSVC compiler.
    static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";

#if !defined(_MSC_VER)
    const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
	// Use getenv_s for MSVC
	size_t requiredSize;
	getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
	if (requiredSize == 0) {
		throw std::runtime_error("missing connection string from env.");
	}
	std::vector<char> value(requiredSize);
	getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
	std::string connectionStringStr = std::string(value.begin(), value.end());
	const char* connectionString = connectionStringStr.c_str();
#endif

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

重要

アカウント アクセス キーは慎重に使用する必要があります。 アカウント アクセス キーを紛失した場合、または誤ってセキュリティで保護されていない場所に置いた場合には、サービスが脆弱になる可能性があります。 アクセス キーを持つすべてのユーザーは、ストレージ アカウントに対する要求を承認でき、実質的にすべてのデータにアクセスできます。 DefaultAzureCredential はセキュリティ機能と利点が強化されており、Azure サービスに対する認可を管理するために推奨されるアプローチです。

コンテナーを作成する

新しいコンテナーの名前を決定します。 次に、BlobContainerClient のインスタンスを作成し、コンテナーを作成します。

重要

コンテナーの名前は小文字にする必要があります。 コンテナーと BLOB の名前付けの詳細については、「Naming and Referencing Containers, Blobs, and Metadata (コンテナー、BLOB、メタデータの名前付けと参照)」を参照してください。

main() の末尾に次のコードを追加します。

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

コンテナーに BLOB をアップロードする

次のコード スニペット:

1. "Hello Azure!" を含む文字列を宣言します
2. 「コンテナーを作成する」セクションでのコンテナー上で GetBlockBlobClient を呼び出すことで、BlockBlobClient オブジェクトへの参照を取得します。
3. UploadFrom 関数を呼び出して、文字列を BLOB にアップロードします。 この関数では、BLOB がまだ存在しない場合は作成し、既に存在する場合は更新します。

main() の末尾に次のコードを追加します。

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

コンテナー内の BLOB を一覧表示する

ListBlobs 関数を呼び出して、コンテナー内の BLOB を一覧表示します。 コンテナーに追加されている BLOB は 1 つだけなので、この操作から返されるのは、その BLOB だけです。

main() の末尾に次のコードを追加します。

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

BLOB をダウンロードする

アップロードされた BLOB のプロパティを取得します。 次に、新しい std::vector<uint8_t> オブジェクトを宣言し、アップロードした BLOB のプロパティを使用してサイズを変更します。 BlobClient 基底クラスの DownloadTo 関数を呼び出して、先ほど作成した BLOB を新しい std::vector<uint8_t> オブジェクトにダウンロードします。 最後に、ダウンロードされた BLOB データを表示します。

main() の末尾に次のコードを追加します。

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

BLOB を削除する

次のコードは、BlobClient.Delete 関数を呼び出して、Azure Blob Storage コンテナーから BLOB を削除します。

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

コンテナーを削除する

次のコードでは、BlobContainerClient.Delete を使用してコンテナー全体を削除することで、アプリによって作成されたリソースをクリーンアップします。

main() の末尾に次のコードを追加します。

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

コードの実行

このアプリは、コンテナーを作成し、テキスト ファイルを Azure Blob Storage にアップロードします。 さらに、この例では、コンテナー内の BLOB を一覧表示し、ファイルをダウンロードして、ファイルの内容を表示します。 最後に、BLOB とコンテナーを削除します。

アプリの出力は、次の例のようになります。

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

次のステップ

このクイックスタートでは、C++ を使用して BLOB をアップロード、ダウンロード、および一覧表示する方法について説明しました。 また、Azure Blob Storage コンテナーの作成方法と削除方法についても説明しました。

C++ Blob Storage サンプルを確認するには、次の記事に進んでください。

C++ 向け Azure Blob Storage クライアント ライブラリのサンプル