クイックスタート: .NET 用 Azure Queue Storage クライアントライブラリ

[アーティクル]
06/29/2023

.NET 用 Azure Queue Storage クライアントライブラリを使ってみましょう。 Azure Queue Storage は、後で取得して処理するために多数のメッセージを格納するためのサービスです。以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。

API のリファレンスのドキュメント | ライブラリのソースコード | パッケージ (NuGet) | サンプル

.NET 用 Azure Queue Storage クライアントライブラリを使うと、以下のことができます。

キューを作成する
メッセージをキューに追加する
キュー内のメッセージを表示する
キュー内のメッセージを更新する
キューの長さを取得する
キューからメッセージを受信する
キューからメッセージを削除する
キューを削除する

前提条件

Azure サブスクリプション - 無料アカウントを作成する
Azure Storage アカウント - ストレージアカウントを作成する
使用するオペレーティングシステム用の最新の .NET SDK。ランタイムではなく、必ず SDK を入手してください。

設定

このセクションでは、.NET 用 Azure Queue Storage クライアントライブラリを操作するためのプロジェクトの準備について説明します。

プロジェクトを作成する

QueuesQuickstart という名前の .NET アプリケーションを作成します。

コンソールウィンドウ (cmd、PowerShell、Bash など) で、dotnet new コマンドを使用し、QueuesQuickstart という名前で新しいコンソールアプリを作成します。このコマンドを使うと、Program.cs という 1 つのソースファイルを含む単純な "Hello World" C# プロジェクトを作成できます。
```
dotnet new console -n QueuesQuickstart
```
新しく作成した QueuesQuickstart ディレクトリに切り替えます。
```
cd QueuesQuickstart
```

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

まだアプリケーションディレクトリにいる間に、dotnet add package コマンドを使用して、.NET 用の Azure Queue Storage クライアントライブラリパッケージをインストールします。

dotnet add package Azure.Storage.Queues

Azure サービスへのパスワードレス接続には、Azure ID クライアントライブラリパッケージが必要です。

dotnet add package Azure.Identity

アプリのフレームワークを設定する

任意のエディターでプロジェクトを開きます
Program.cs ファイルを開きます
既存のコードを次のように更新します。

using Azure;
using Azure.Identity;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using System;
using System.Threading.Tasks;

Console.WriteLine("Azure Queue Storage client library - .NET quickstart sample");

// Quickstart code goes here

Azure に対して認証します

ほとんどの Azure サービスに対するアプリケーション要求は、認可される必要があります。コード内の Azure サービスに対してパスワードレス接続を実装するには、Azure ID クライアントライブラリによって提供される DefaultAzureCredential クラスを使用する方法お勧めします。

パスワード、接続文字列、その他の資格情報を使用して、Azure サービスへの要求を直接承認することもできます。ただし、この方法は慎重に使用する必要があります。開発者は、安全でない場所にこれらのシークレットを公開しないように注意する必要があります。パスワードまたはシークレットキーへのアクセス権を取得したユーザーは、誰でも認証を受けることができます。 DefaultAzureCredential はアカウント・キーよりも管理しやすく、セキュリティが優れており、パスワードレス認証が可能になります。両方のオプションの例を次に示します。

パスワードレス (推奨)
接続文字列

DefaultAzureCredential は、.NET 用 Azure ID クライアントライブラリによって提供されるクラスです。 DefaultAzureCredential の詳細については、DefaultAzureCredential の概要を参照してください。 DefaultAzureCredential は複数の認証方法をサポートしており、実行時に使用する方法が決定されます。このアプローチを採用すると、環境固有のコードを実装することなく、異なる環境 (ローカルと運用環境) で異なる認証方法をアプリに使用できます。

たとえば、ローカルでの開発時には Visual Studio サインイン資格情報を使用してアプリを認証し、それが Azure にデプロイされたらマネージド ID を使用できます。この移行のためにコードを変更する必要はありません。

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

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

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

重要

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

Azure portal で、メインの検索バーまたは左側のナビゲーションを使ってストレージアカウントを見つけます。
ストレージアカウントの概要ページで、左側のメニューから [アクセス制御 (IAM)] を選びます。
[アクセス制御 (IAM)] ページで、[ロールの割り当て] タブを選びます。
上部のメニューから [+ 追加] を選択し、次に結果のドロップダウンメニューから [ロールの割り当ての追加] を選択します。

A screenshot showing how to assign a role.

検索ボックスを使って、結果を目的のロールに絞り込みます。この例では、「ストレージキューデータ共同作成者」を検索し、一致する結果を選び、[次へ] を選びます。
[アクセスの割り当て先] で、[ユーザー、グループ、またはサービスプリンシパル] を選び、[+ メンバーの選択] を選びます。
ダイアログで、自分の Microsoft Entra ユーザー名 (通常は user@domain メールアドレス) を検索し、ダイアログの下部にある [選択] を選びます。
[レビューと割り当て] を選んで最終ページに移動し、もう一度 [レビューと割り当て] を行ってプロセスを完了します。

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 Queue Data Contributor" \
    --scope "<your-resource-id>"

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

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

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

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

Azure Portal で資格情報をコピーする

サンプルアプリケーションから Azure Storage に対して要求を実行するときは、承認されている必要があります。要求を承認するには、ストレージアカウントの資格情報を接続文字列としてアプリケーションに追加します。ストレージアカウントの資格情報を表示するには、次の手順に従います。

Azure portal にサインインします。
自分のストレージアカウントを探します。
ストレージアカウントメニューウィンドウの [セキュリティとネットワーク] で、 [アクセスキー] を選択します。ここで、アカウントアクセスキーと各キーの完全な接続文字列が確認できます。
[アクセスキー] ペインで、 [キーの表示] を選択します。
[key1] セクションで、 [接続文字列] の値を見つけます。 [クリップボードにコピー] アイコンを選択して、接続文字列をコピーします。次のセクションで、この接続文字列の値を環境変数に追加します。

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

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

Windows
Linux と macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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

プログラムの再起動

環境変数を追加した後、環境変数の読み取りを必要とする実行中のプログラムをすべて再起動します。たとえば、続行する前に、ご使用の開発環境またはエディターを再起動します。

重要

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

オブジェクトモデル

Azure Queue storage は、多数のメッセージを格納するためのサービスです。キューメッセージの許容される最大サイズは 64 KB です。キューには、ストレージアカウントの総容量の上限を超えない限り、数百万のメッセージを含めることができます。キューは通常、非同期的な処理用に作業のバックログを作成するために使用されます。 Queue Storage には、次の 3 種類のリソースがあります。

ストレージアカウント: Azure Storage にアクセスするときは必ずストレージアカウントを使用します。ストレージアカウントの詳細については、「ストレージアカウントの概要」を参照してください
キュー: キューは、メッセージのセットを格納します。すべてのメッセージはキューに格納されている必要があります。キュー名は小文字で入力する必要があります。キューの名前付け規則については、「 Naming Queues and Metadata (キューとメタデータの名前付け規則)」を参照してください。
メッセージ: 形式を問わず、メッセージのサイズは最大で 64 KB です。メッセージは最大 7 日間キューに残ることができます。バージョン 2017-07-29 以降では、最大有効期間を任意の正の数にすることができます。また、-1 は、メッセージが期限切れにならないことを示します。このパラメーターを省略すると、既定の有効期間は 7 日になります。

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

Diagram of Queue storage architecture

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

QueueServiceClient: QueueServiceClient を使用すると、ストレージアカウント内のすべてのキューを管理できます。
QueueClient: QueueClient クラスを使用すると、個々のキューとそのメッセージを管理および操作できます。
QueueMessage: QueueMessage クラスは、キューに対して ReceiveMessages を呼び出したときに返される個々のオブジェクトを表します。

コード例

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

アクセスの認可とクライアントオブジェクトの作成
キューを作成する
メッセージをキューに追加する
キュー内のメッセージを表示する
キュー内のメッセージを更新する
キューの長さを取得する
キューからメッセージを受信する
キューからメッセージを削除する
キューを削除する

パスワードレス (推奨)
接続文字列

アクセスの認可とクライアントオブジェクトの作成

ローカル開発には、ロールを割り当てたのと同じ Microsoft Entra アカウントで認証を受けるようにしてください。 Azure CLI や Azure PowerShell などの一般的な開発ツールを使用して認証できます。認証に使用できる開発ツールは、言語によって異なります。

Azure CLI で次のコマンドを使って Azure にサインインします。

az login

Visual Studio Code から DefaultAzureCredential を操作するには、Azure CLI をインストールする必要があります。

Visual Studio Code のメインメニューで、[ターミナル] > [新しいターミナル] に移動します。

Azure CLI で次のコマンドを使って Azure にサインインします。

az login

PowerShell で次のコマンドを使って Azure にサインインします。

Connect-AzAccount

認証が完了したら、DefaultAzureCredential を使って、ストレージアカウント内のキューデータにアクセスする QueueClient オブジェクトを作成および認可できます。 DefaultAzureCredential は、前の手順でサインインしたアカウントを自動的に検出して使用します。

DefaultAzureCredential を使って認可するには、「パッケージをインストールする」の説明に従って Azure.Identity パッケージを追加していることを確認します。また、必ず Program.cs ファイルに Azure.Identity 名前空間の using ディレクティブを追加します。

using Azure.Identity;

次に、キューの名前を決定し、認可に DefaultAzureCredential を使って、QueueClient クラスのインスタンスを作成します。このクライアントオブジェクトを使って、ストレージアカウント内のキューリソースを作成して操作します。

重要

キュー名に使用できるのは小文字、数字、ハイフンのみであり、名前の先頭は文字または数字にする必要があります。各ハイフンの前後にはハイフン以外の文字を指定する必要があります。また、名前は 3 から 63 文字で指定する必要があります。詳細については、「キューおよびメタデータの名前付け」を参照してください。

Program.cs ファイルの末尾に次のコードを追加します。 <storage-account-name> のプレースホルダーは必ず実際の値に置き換えてください。

// Create a unique name for the queue
// TODO: Replace the <storage-account-name> placeholder 
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();
string storageAccountName = "<storage-account-name>";

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(
    new Uri($"https://{storageAccountName}.queue.core.windows.net/{queueName}"),
    new DefaultAzureCredential());

接続文字列を取得してクライアントを作成する

以下のコードは、ストレージアカウントの接続文字列を取得します。この接続文字列は、「ストレージ接続文字列の構成」セクションで作成した環境変数に格納されます。

Program.cs ファイルの末尾に次のコードを追加します。

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable called
// AZURE_STORAGE_CONNECTION_STRING on the machine running the application.
// If the environment variable is created after the application is launched
// in a console or with Visual Studio, the shell or application needs to be
// closed and reloaded to take the environment variable into account.
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

認可に接続文字列を使って、キューの名前を決定し、QueueClient クラスのインスタンスを作成します。このクライアントオブジェクトを使って、ストレージアカウント内のキューリソースを作成して操作します。

重要

Program.cs ファイルの末尾に次のコードを追加します。

// Create a unique name for the queue
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(connectionString, queueName);

Note

QueueClient クラスを使用して送信されるメッセージは、UTF-8 エンコードを使用して XML 要求に含めることができる形式である必要があります。必要に応じて、MessageEncoding オプションを Base64 に設定して、準拠していないメッセージを処理できます。

キューを作成する

QueueClient オブジェクトを使い、CreateAsync メソッドを呼び出してストレージアカウントにキューを作成します。

Program.cs メソッドの末尾に次のコードを追加します。

Console.WriteLine($"Creating queue: {queueName}");

// Create the queue
await queueClient.CreateAsync();

メッセージをキューに追加する

以下のコードスニペットでは、SendMessageAsync メソッドを呼び出してキューにメッセージを非同期的に追加します。さらに、SendMessageAsync の呼び出しから返された SendReceipt を保存します。この receipt は、後でプログラムの中でメッセージを更新する際に使用します。

Program.cs ファイルの末尾に次のコードを追加します。

Console.WriteLine("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.SendMessageAsync("First message");
await queueClient.SendMessageAsync("Second message");

// Save the receipt so we can update this message later
SendReceipt receipt = await queueClient.SendMessageAsync("Third message");

キュー内のメッセージを表示する

キュー内のメッセージをクイック表示するには、PeekMessagesAsync メソッドを呼び出します。このメソッドは、キューの先頭からメッセージを 1 つ以上取得しますが、メッセージの可視性は変更しません。

Program.cs ファイルの末尾に次のコードを追加します。

Console.WriteLine("\nPeek at the messages in the queue...");

// Peek at messages in the queue
PeekedMessage[] peekedMessages = await queueClient.PeekMessagesAsync(maxMessages: 10);

foreach (PeekedMessage peekedMessage in peekedMessages)
{
    // Display the message
    Console.WriteLine($"Message: {peekedMessage.MessageText}");
}

キュー内のメッセージを更新する

メッセージの内容を更新するには、UpdateMessageAsync メソッドを呼び出します。メッセージの表示タイムアウトと内容は、このメソッドで変更できます。メッセージの内容には UTF-8 でエンコードされた文字列を指定してください。最大サイズは 64 KB です。先ほどこのコードの中で保存した SendReceipt の値を、新しいメッセージの内容と共に渡します。 SendReceipt の値によって、更新するメッセージが識別されます。

Console.WriteLine("\nUpdating the third message in the queue...");

// Update a message using the saved receipt from sending the message
await queueClient.UpdateMessageAsync(receipt.MessageId, receipt.PopReceipt, "Third message has been updated");

キューの長さを取得する

キュー内のメッセージの概数を取得できます。 GetProperties メソッドからは、メッセージ数を含むキューのプロパティが返されます。 ApproximateMessagesCount プロパティには、キュー内のメッセージの概数が格納されます。この数は、キュー内の実際のメッセージ数より少なくなることはありませんが、多くなる可能性があります。

Program.cs ファイルの末尾に次のコードを追加します。

QueueProperties properties = queueClient.GetProperties();

// Retrieve the cached approximate message count
int cachedMessagesCount = properties.ApproximateMessagesCount;

// Display number of messages
Console.WriteLine($"Number of messages in queue: {cachedMessagesCount}");

キューからメッセージを受信する

ReceiveMessagesAsync メソッドを呼び出して、先ほど追加したメッセージをダウンロードします。

Program.cs ファイルの末尾に次のコードを追加します。

Console.WriteLine("\nReceiving messages from the queue...");

// Get messages from the queue
QueueMessage[] messages = await queueClient.ReceiveMessagesAsync(maxMessages: 10);

必要に応じて、maxMessages の値を指定できます。これは、キューから取得するメッセージの数です。メッセージ数の既定値は 1、最大値は 32 です。 visibilityTimeout の値を指定することもできます。これにより、タイムアウト期間の他の操作からメッセージが非表示になります。既定値は 30 秒です。

キューからメッセージを削除する

メッセージは処理後にキューから削除します。ここでの処理は、単にメッセージをコンソールに表示するだけです。

ユーザーからの入力を待ってメッセージを処理、削除するために、Console.ReadLine を呼び出してアプリを一時停止させます。リソースが正しく作成されたことを Azure portal で確認してから、それらを削除してください。明示的に削除されなかったメッセージは、最終的にキューに再表示され、別の機会に処理されます。

Program.cs ファイルの末尾に次のコードを追加します。

Console.WriteLine("\nPress Enter key to 'process' messages and delete them from the queue...");
Console.ReadLine();

// Process and delete messages from the queue
foreach (QueueMessage message in messages)
{
    // "Process" the message
    Console.WriteLine($"Message: {message.MessageText}");

    // Let the service know we're finished with
    // the message and it can be safely deleted.
    await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt);
}

キューを削除する

次のコードでは、DeleteAsync メソッドを使用してキューを削除することにより、アプリによって作成されたリソースがクリーンアップされます。

Program.cs ファイルの末尾に次のコードを追加します。

Console.WriteLine("\nPress Enter key to delete the queue...");
Console.ReadLine();

// Clean up
Console.WriteLine($"Deleting queue: {queueClient.Name}");
await queueClient.DeleteAsync();

Console.WriteLine("Done");

コードの実行

このアプリは、3 つのメッセージを作成して Azure のキューに追加します。コードでは、キュー内のメッセージを一覧表示した後にそれらを取得して削除してから、最後にキューを削除します。

コンソールウィンドウで、お使いのアプリケーションのディレクトリに移動し、アプリケーションをビルドして実行します。

dotnet build

dotnet run

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

Azure Queue Storage client library - .NET quickstart sample

Creating queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2
Done

メッセージを受信する前にアプリが一時停止したら、Azure portal でストレージアカウントを確認してください。キューにメッセージが存在することを確認します。

Enter キーを押してメッセージを受信し、削除します。確認を求められたら、もう一度 Enter キーを押してキューを削除し、デモを終了します。

次のステップ

このクイックスタートでは、非同期 .NET コードを使用して、キューを作成し、そこにメッセージを追加する方法について説明しました。その後、メッセージの表示、取得、削除について説明しました。最後に、メッセージキューを削除する方法を説明しました。

チュートリアル、サンプル、クイックスタートなどのドキュメントについては、次のページを参照してください。

.NET および .NET Core 開発者向けの Azure

非推奨の .NET バージョン 11.x SDK を使用する関連コードサンプルについて、詳しくは「.NET バージョン 11.x を使用したコードサンプル」をご覧ください。
詳細については、「.NET 用 Azure Storage ライブラリ」を参照してください。
その他の Azure Queue Storage サンプルアプリについては、「Azure Queue Storage client library for .NET samples (.NET 用 Azure Queue Storage クライアントライブラリのサンプル)」を参照してください。
.NET Core の詳細については、「Get started with .NET in 10 minutes (10 分で .NET を使い始める)」を参照してください。

クイックスタート: .NET 用 Azure Queue Storage クライアント ライブラリ

前提条件

設定

プロジェクトを作成する

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

アプリのフレームワークを設定する

Azure に対して認証します

オブジェクト モデル

コード例

アクセスの認可とクライアント オブジェクトの作成

キューを作成する

メッセージをキューに追加する

キュー内のメッセージを表示する

キュー内のメッセージを更新する

キューの長さを取得する

キューからメッセージを受信する

キューからメッセージを削除する

キューを削除する

コードの実行

次のステップ

その他のリソース

クイックスタート: .NET 用 Azure Queue Storage クライアントライブラリ

オブジェクトモデル

アクセスの認可とクライアントオブジェクトの作成