如何從 PowerShell 使用 Azure 佇列儲存體

發行項
05/21/2024

Azure 佇列儲存體是一項儲存大量訊息的服務，全球任何地方都可透過 HTTP 或 HTTPS 叫來存取這些訊息。如需詳細資訊，請參閱 Azure 佇列儲存體簡介。本操作說明文章涵蓋一般的佇列儲存體作業。您將學習如何：

建立佇列
擷取佇列
新增訊息
擷取
刪除訊息
刪除佇列

本操作指南需要 Azure PowerShell （Az）模組 v12.0.0。執行 Get-Module -ListAvailable Az 以尋找目前安裝的版本。如果您需要升級，請參閱安裝 Azure PowerShell 模組。

沒有任何適用於佇列資料層的 PowerShell Cmdlet。若要執行資料層作業 (例如新增訊息、讀取訊息，以及刪除訊息)，您必須使用 PowerShell 中公開的 .NET 儲存體用戶端程式庫。您可以建立訊息物件，然後使用 AddMessage 這類命令對該訊息執行作業。本文示範如何執行這項作業。

注意

建議您使用 Azure Az PowerShell 模組來與 Azure 互動。若要開始使用，請參閱安裝 Azure PowerShell。若要了解如何移轉至 Az PowerShell 模組，請參閱將 Azure PowerShell 從 AzureRM 移轉至 Az。

使用 Connect-AzAccount 命令登入 Azure 訂用帳戶並遵循畫面上的指示。如有需要，您可以藉由新增 TenantId 和 Subscription 參數來指定訂用帳戶，並包含個別的值。

Connect-AzAccount

擷取位置清單

如果您不知道要使用哪個位置，可以使用 Cmdlet 列出可用的位置 Get-AzLocation ，如提供的範例所示。顯示清單之後，請選擇位置，並將它儲存在變數中 location 以供日後使用。此練習中的範例會 eastus 使用位置。

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

建立資源群組

Azure 資源群組是在其中部署與管理 Azure 資源的邏輯容器。選擇資源群組的名稱，並將其儲存在變數中 resourceGroup 以供日後使用。這個範例會使用名稱 howtoqueuesrg。

呼叫 New-AzResourceGroup Cmdlet 並將名稱和位置 ResourceGroupName 提供給參數，以建立資源群組，如下所示。

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

建立儲存體帳戶

Azure 記憶體帳戶是唯一命名的資源，其中包含所有數據對象作為 Blob、檔案、佇列和數據表。

選擇記憶體帳戶的名稱，並將它儲存在變數中 storageAccountName 以供日後使用。這個範例會使用名稱 howtoqueuestorage。

接下來，使用 New-Az 儲存體 Account Cmdlet，建立具有本地備援記憶體（LRS）的標準一般用途記憶體帳戶。最後，設定定義記憶體帳戶的記憶體帳戶內容，並將它儲存至 ctx 變數。使用變數參考內容可讓您對記憶體帳戶執行作業，而不重複提供認證。

$storageAccountName = "howtoqueuestorage"

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

$ctx = $storageAccount.Context

建立佇列

首先，選擇記憶體帳戶的名稱，並將其儲存在變數中 queueName 。這個範例會使用名稱 howtoqueuestorage。接下來，使用 New-Az 儲存體 Queue Cmdlet 建立佇列，並將和 ctx 變數傳遞queueName至 Name 和 Context 參數，如下所示。

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

如需 Azure 佇列儲存體命名慣例的相關資訊，請參閱命名佇列和中繼資料。

擷取佇列

您可以使用 Get-Az 儲存體 Queue Cmdlet 來擷取特定佇列，或記憶體帳戶內所有佇列的清單。下列範例示範如何使用 Cmdlet 擷取所有佇列 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 儲存體總管，則可以連線到您的 Azure 帳戶，以及檢視儲存體帳戶中的佇列，並向下鑽研至某個佇列以檢視佇列上的訊息。

從佇列擷取訊息

雖然不一定保證，但訊息會以最佳嘗試先出的順序從佇列中擷取。

根據您的使用案例，您可以從佇列擷取一或多個訊息。您也可以修改訊息的可見性，允許或防止其他進程存取相同的訊息。

有兩種方式可從佇列擷取訊息：

接收：使用 Receive 清除佇列擷取訊息，並遞增其 DequeueCount 屬性。除非刪除訊息，否則會重新插入佇列中以再次處理。
查看：使用 Peek 擷取訊息可讓您從佇列「預覽」訊息。 Peek 不會清除訊息或遞增其 DequeueCount 屬性。

接收訊息

當您使用之類的ReceiveMessage方法從佇列讀取訊息時，訊息會暫時清除佇列，並暫時對其他進程看不見。此 可見度逾時 會定義訊息保持不可見的時間長度。默認可見性逾時為30秒。

如果在可見度逾時通過之前未處理訊息，則會遞增其 DequeueCount 屬性，並在佇列結尾重新插入。重新插入相同的訊息可確保另一個進程可以擷取相同的訊息，然後再試一次。

下列範例會將 invisibleTimeout 變數設定為 10 秒，然後從佇列讀取兩則訊息。

# 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 屬性，才能永久刪除訊息。由於這項需求，使用雙步驟程式刪除訊息最簡單的方式。

首先，呼叫 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 進行基本佇列儲存體管理，包括如何：

建立佇列
擷取佇列
新增訊息
讀取訊息
刪除訊息
刪除佇列

Microsoft Azure PowerShell 儲存體 Cmdlet

儲存體 PowerShell Cmdlet

Microsoft Azure 儲存體總管

Microsoft Azure 儲存體總管是一個免費的獨立應用程式，可讓您在 Windows、MacOS 和 Linux 上以視覺化方式處理 Azure 儲存體資料。

共用方式為