如何通过 PowerShell 使用 Azure 队列存储

Azure 队列存储是一项可存储大量消息的服务，用户可以通过 HTTP 或 HTTPS 从世界任何地方访问这些消息。 有关详细信息，请参阅 Azure 队列存储简介。 此操作指南文章介绍常见的队列存储操作。 你将学习如何执行以下操作：

本操作说明指南需要 Azure PowerShell (Az) 模块 v12.0.0。 运行 Get-Module -ListAvailable Az 以查找当前安装的版本。 如果需要进行升级，请参阅 Install Azure PowerShell module（安装 Azure PowerShell 模块）。

队列的数据平面没有相应的 PowerShell cmdlet。 若要执行数据平面操作（如添加消息、读取消息和删除消息），必须使用 PowerShell 中公开的 .NET 存储客户端库。 创建消息对象，然后可以使用命令（例如 AddMessage）对该消息执行操作。 本文介绍如何执行该操作。

登录 Azure

运行 Connect-AzAccount -EnvironmentName AzureChinaCloud 命令以登录 Azure 订阅，并按照屏幕上的说明操作。 如果需要，可以通过添加 TenantId 和 Subscription 参数并包括相应的值来指定订阅。

Connect-AzAccount -EnvironmentName AzureChinaCloud

检索位置列表

如果不知道要使用的位置，可以使用 Get-AzLocation cmdlet 列出可用位置，如提供的示例所示。 显示列表后，选择一个位置并将其存储在 location 变量中供将来使用。 本练习中的示例使用 chinaeast 位置。

Get-AzLocation | Select-Object Location
$location = "China East"

创建资源组

Azure 资源组是在其中部署和管理 Azure 资源的逻辑容器。 为资源组选择一个名称，并将其存储在 resourceGroup 变量中以供将来使用。 此示例使用名称 howtoqueuesrg。

通过调用 New-AzResourceGroup cmdlet 并向 ResourceGroupName 参数提供名称和位置来创建资源组，如下所示。

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

创建存储帐户

Azure 存储帐户是一个唯一命名的资源，其中包含 blob、文件、队列和表形式的所有数据对象。

为存储帐户选择一个名称，并将其存储在 storageAccountName 变量中以供将来使用。 此示例使用名称 howtoqueuestorage。

接下来，使用 New-AzStorageAccount cmdlet 创建具有本地冗余存储 (LRS) 的标准常规用途存储帐户。 最后，设置定义存储帐户的存储帐户上下文，将其保存到 ctx 变量。 通过使用变量引用上下文，可以针对存储帐户执行操作，而无需重复提供凭据。

$storageAccountName = "howtoqueuestorage"

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

$ctx = $storageAccount.Context

创建队列

首先，选择存储帐户的名称并将其存储在 queueName 变量中。 此示例使用名称 howtoqueuestorage。 接下来，使用 New-AzStorageQueue cmdlet 创建队列，并将 queueName 和 ctx 变量传递给 Name 和 Context 参数，如下所示。

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

有关 Azure 队列存储的命名约定的信息，请参阅命名队列和元数据。

检索队列

可以使用 Get-AzStorageQueue cmdlet 检索特定队列或存储帐户中所有队列的列表。 以下示例演示如何使用 Get-AzStorageQueue cmdlet 检索所有队列，以及如何使用 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：使用 Receive 检索消息可将消息取消排队并递增其 DequeueCount 属性。 除非删除消息，否则它将重新插入队列中以再次进行处理。
• Peek：使用检索 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 进行队列存储管理的基本知识，其中包括如何：

Azure PowerShell 存储 cmdlet

• 存储 PowerShell cmdlet

Microsoft Azure 存储资源管理器

• Microsoft Azure 存储资源管理器是 Microsoft 免费提供的独立应用，适用于在 Windows、macOS 和 Linux 上以可视方式处理 Azure 存储数据。