クイック スタート: 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

プロジェクトのセットアップと C++ 用 Azure SDK の操作の詳細については、 C++ 用 Azure SDK の 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 ID クライアント ライブラリによって提供される 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 RBAC のスコープについて」を参照してください。

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

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

Important

ほとんどの場合、ロールの割り当てが 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 の概要ページにあります。

   

   注

   運用環境で 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

Get-AzStorageAccount コマンドと Get-AzStorageAccountKey コマンドを使用して、PowerShell で接続文字列をアセンブルできます。

$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);

Important

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

コンテナーを作成する

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

Important

コンテナー名は小文字にする必要があります。 コンテナーと BLOB の名前付けの詳細については、「コンテナー、 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. コンテナーの「Create a container」セクション内で 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 のプロパティを取得します。 次に、アップロードした BLOB のプロパティを使用して、新しい std::vector<uint8_t> オブジェクトを宣言してサイズを変更します。 std::vector<uint8_t> 基本クラスで DownloadTo 関数を呼び出して、以前に作成した BLOB を新しい オブジェクトにダウンロードします。 最後に、ダウンロードした 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 を使用してコンテナー全体を削除することによってアプリが作成したリソースをクリーンアップ します。削除します。

次のコードを 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 クライアント ライブラリのサンプル