PowerShell から Azure Queue Storage を使用する方法

Azure Queue Storage は、HTTP または HTTPS を介して世界中のどこからでもアクセスできる大量のメッセージを格納するためのサービスです。 詳細については、Azure Queue Storage の概要に関するページをご覧ください。 このハウツー記事では、Queue Storage の一般的な操作について取り上げます。 以下の方法について説明します。

この攻略ガイドには、Azure PowerShell (Az) モジュール v12.0.0 が必要です。 現在インストールされているバージョンを確認するには、Get-Module -ListAvailable Az を実行します。 アップグレードする必要がある場合は、Azure PowerShell モジュールのインストールに関するページを参照してください。

キューのデータ プレーン用の PowerShell コマンドレットはありません。 メッセージの追加、読み取り、削除などのデータ プレーン操作を実行するには、PowerShell で公開されるとおりに、.NET ストレージ クライアント ライブラリを使用する必要があります。 メッセージ オブジェクトを作成し、AddMessage などのコマンドを使用して、そのメッセージに対して操作を実行できます。 この記事では、その方法について説明します。

Azure へのサインイン

Connect-AzAccount コマンドを使用して Azure サブスクリプションにサインインし、画面上の指示に従います。 必要に応じて、TenantId パラメーターと Subscription パラメーターを追加し、それぞれの値を含めることでサブスクリプションを指定できます。

Connect-AzAccount

場所の一覧を取得する

使用する場所がわからない場合は、次の例に示すように、Get-AzLocation コマンドレットを使って使用できる場所を一覧表示できます。 一覧が表示されたら、場所を選び、後で使うためにそれを location 変数に格納します。 この演習の例では、eastus の場所を使います。

Get-AzLocation | Select-Object Location
$location = "eastus"

リソース グループを作成する

Azure リソース グループとは、Azure リソースのデプロイと管理に使用する論理コンテナーです。 リソース グループの名前を選び、後で使うためにそれを resourceGroup 変数に格納します。 この例では、 howtoqueuesrgという名前を使用しています。

New-AzResourceGroup コマンドレットを呼び出し、次のように名前と場所を ResourceGroupName パラメーターに指定して、リソース グループを作成します。

$resourceGroup = "howtoqueuesrg"
New-AzResourceGroup -ResourceGroupName $resourceGroup -Location $location

ストレージ アカウントの作成

Azure ストレージ アカウントは、BLOB、ファイル、キュー、テーブルなどのすべてのデータ オブジェクトを含む、一意の名前が付けられたリソースです。

ストレージ アカウントの名前を選び、後で使うためにそれを storageAccountName 変数に格納します。 この例では、 howtoqueuestorageという名前を使用しています。

次に、New-AzStorageAccount コマンドレットを使って、ローカル冗長ストレージ (LRS) を備えた標準の汎用ストレージ アカウントを作成します。 最後に、ストレージ アカウントを定義するストレージ アカウント コンテキストを設定し、それを ctx 変数に保存します。 変数を使ってコンテキストを参照すると、資格情報を繰り返し指定しなくても、ストレージ アカウントに対する操作を実行できます。

$storageAccountName = "howtoqueuestorage"

$storageAccount = New-AzStorageAccount -ResourceGroupName $resourceGroup `
  -Name $storageAccountName `
  -Location $location `
  -SkuName Standard_LRS

$ctx = $storageAccount.Context

キューを作成する

まず、ストレージ アカウントの名前を選び、それを queueName 変数に格納します。 この例では、 howtoqueuestorageという名前を使用しています。 次に、以下に示すように、New-AzStorageQueue コマンドレットを使ってキューを作成し、queueName 変数と ctx 変数を Name パラメーターと Context パラメーターに渡します。

$queueName = "howtoqueue"
$queue = New-AzStorageQueue -Name $queueName -Context $ctx

Azure Queue Storage での名前付け規則の詳細については、「キューおよびメタデータの名前付け」を参照してください。

キューを取得する

Get-AzStorageQueue コマンドレットを使うと、特定のキュー、またはストレージ アカウント内のすべてのキューの一覧を取得できます。 次の例は、Get-AzStorageQueue コマンドレットを使ってすべてのキューを取得する方法と、Name パラメーターを使ってキューを指定する方法を示しています。

# Retrieve all queues and show their names
Get-AzStorageQueue -Context $ctx | Select-Object Name

# Retrieve a specific queue
$queue = Get-AzStorageQueue -Name $queueName -Context $ctx

# Show the properties of the queue
$queue

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

キュー内のメッセージに影響を与える操作では、PowerShell で公開されるとおりに、.NET ストレージ クライアント ライブラリを使います。 メッセージをキューに追加するには、メッセージを文字列として QueueClient クラスの SendMessage メソッドに渡します。

メッセージ文字列は UTF-8 形式である必要があります。

次の例は、メッセージをキューに追加する方法を示しています。

# Create a new message using a constructor of the CloudQueueMessage class
$queueMessage = "This is message 1"

# Add a new message to the queue
$queue.QueueClient.AddMessageAsync($queueMessage)

# Add two more messages to the queue
$queueMessages = @("This is message 2","This is message 3")
$queueMessages | foreach {$queue.QueueClient.AddMessageAsync($_)}

Azure Storage Explorer を使用する場合、Azure アカウントに接続し、ストレージ アカウントのキューを表示し、キューにドリルダウンし、そのキューに関するメッセージを表示できます。

キューからメッセージを取得する

常に保証されているわけではありませんが、メッセージは "最善の努力で"、"先入れ先出し" の順序でキューから取得されます。

ユース ケースに応じて、キューから 1 つ以上のメッセージを取得できます。 メッセージの可視性を変更して、他のプロセスによる同じメッセージへのアクセスを許可または禁止することもできます。

キューからメッセージを取得するには 2 つの方法があります。

• Receive: Receive を使ってメッセージを取得すると、メッセージがデキューされ、その DequeueCount プロパティが増分されます。 メッセージは削除されない限り、キューに再挿入されて再度処理されます。
• Peek: Peek を使ってメッセージを取得すると、キューからメッセージを "プレビュー" できます。 Peek ではメッセージがデキューされたり、その DequeueCount プロパティが増分されたりしません。

メッセージを受信する

ReceiveMessage などのメソッドを使ってキューからメッセージを "読み取る" と、メッセージは一時的にキューからデキューされ、一時的に他のプロセスから見えなくなります。 この可視性タイムアウトは、メッセージが表示されない時間を定義します。 既定の可視性タイムアウトは 30 秒です。

可視性タイムアウトが経過する前にメッセージが処理されない場合、その DequeueCount プロパティが増分され、キューの末尾に再挿入されます。 同じメッセージを再挿入すると、別のプロセスが同じメッセージを取得して再試行できるようになります。

次の例では、invisibleTimeout 変数を 10 秒に設定し、キューから 2 つのメッセージを読み取ります。

# Set the amount of time you want to entry to be invisible after read from the queue
# If it is not deleted by the end of this time, it will show up in the queue again
$visibilityTimeout = [System.TimeSpan]::FromSeconds(10)

# Read the message from the queue, then show the contents of the message. 
# Read the next message, too.
$queueMessage = $queue.QueueClient.ReceiveMessage($visibilityTimeout)
$queueMessage.Value
$queueMessage = $queue.QueueClient.ReceiveMessage($visibilityTimeout)
$queueMessage.Value

ReceiveMessages メソッドを使い、返すメッセージの最大数を指定する整数値を渡すことで、キューから複数のメッセージを同時に取得できます。

# Set the amount of time you want to entry to be invisible after read from the queue
# If it is not deleted by the end of this time, it will show up in the queue again
$visibilityTimeout = [System.TimeSpan]::FromSeconds(10)

# Read the messages from the queue, then show the contents of the messages.
$queueMessage = $queue.QueueClient.ReceiveMessages(5,$visibilityTimeout)
$queueMessage.Value

メッセージをクイック表示する

共有キューを使ったり、可視性を変更せずにメッセージをプレビューしたりするユース ケースでは、PeekMessage メソッドと PeekMessages メソッドを使用できます。 前の ReceiveMessages の例と同様に、メッセージの最大数を指定する整数値を渡すことで、複数のメッセージを同時にピークできます。

次の例では、PeekMessage メソッドと PeekMessages メソッドの両方を使ってキューからメッセージを取得します。

# Read the message from the queue, then show the contents of the message. 
$queueMessage = $queue.QueueClient.PeekMessage()
$queueMessage.Value

# Read the next four messages, then show the contents of the messages.
$queueMessage = $queue.QueueClient.PeekMessages(4)
$queueMessage.Value

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

誤って削除されないように、メッセージを完全に削除する前に、MessageId プロパティと PopReceipt プロパティの両方を指定する必要があります。 この要件のため、2 段階のプロセスを使ってメッセージを削除するのが最も簡単です。

まず、ReceiveMessage メソッドまたは ReceiveMessages メソッドを呼び出して、キュー内の次のメッセージをフェッチします。 キューからのメッセージの削除を完了するには、メッセージから取得した値を DeleteMessage メソッドに渡します。

このプロセスを次の例に示します。

# Set the amount of time you want to entry to be invisible after read from the queue
# If it is not deleted by the end of this time, it will show up in the queue again
$visibilityTimeout = [System.TimeSpan]::FromSeconds(10)

# Receive one message from the queue, then delete the message. 
$queueMessage = $queue.QueueClient.ReceiveMessage($visibilityTimeout)
$queue.QueueClient.DeleteMessage($queueMessage.Value.MessageId, $queueMessage.Value.PopReceipt)

# Receive four message from the queue, then delete the messages. 
$queueMessage = $queue.QueueClient.ReceiveMessages(4,$visibilityTimeout)
$queueMessage.Value | foreach { $queue.QueueClient.DeleteMessage($_.MessageId, $_.PopReceipt)}

キューを削除する

キューとそれに含まれるすべてのメッセージを削除するには、QueueClient クラスの Delete メソッドを呼び出します。 次の例は、この演習で使った特定のキューを削除する方法を示しています。

# Delete the queue
Remove-AzStorageQueue -Name $queueName -Context $ctx

リソースをクリーンアップする

この演習で作成した資産とリソースを削除するには、リソース グループを削除します。 この場合、ストレージ アカウントとリソース グループ自体も削除されます。

Remove-AzResourceGroup -Name $resourceGroup

次のステップ

このハウツー記事では、次のような、PowerShell による基本的な Queue Storage 管理について説明しました。

Microsoft Azure PowerShell Storage コマンドレット

• Storage PowerShell コマンドレット

Microsoft Azure Storage Explorer

• Microsoft Azure ストレージ エクスプローラーは、Windows、macOS、Linux で Azure Storage のデータを視覚的に操作できる Microsoft 製の無料のスタンドアロン アプリです。