如何通过 Python 使用队列存储How to use Queue storage from Python

Tip

尝试 Azure 存储资源管理器Try the Azure Storage Explorer

Azure 存储资源管理器是 Microsoft 免费提供的独立应用,适用于在 Windows、macOS 和 Linux 上以可视方式处理 Azure 存储数据。Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.

概述Overview

本指南演示如何使用 Azure 队列存储服务执行常见方案。This guide shows you how to perform common scenarios using the Azure Queue storage service. 这些示例用 Python 编写并使用 Microsoft Azure Storage SDK for PythonThe samples are written in Python and use the Microsoft Azure Storage SDK for Python. 介绍的方案包括插入扫视获取删除队列消息以及创建和删除队列The scenarios covered include inserting, peeking, getting, and deleting queue messages, as well as creating and deleting queues. 有关队列的详细信息,请参阅[后续步骤]部分。For more information on queues, refer to the [Next Steps] section.

什么是队列存储?What is Queue Storage?

Azure 队列存储是一项可存储大量消息的服务,用户可以通过经验证的呼叫,使用 HTTP 或 HTTPS 从世界任何地方访问这些消息。Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or HTTPS. 一条队列消息的大小最多可为 64 KB,一个队列中可以包含数百万条消息,直至达到存储帐户的总容量限值。A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account.

队列存储的常见用途包括:Common uses of Queue storage include:

  • 创建积压工作以进行异步处理Creating a backlog of work to process asynchronously
  • 将消息从 Azure Web 角色传递到 Azure 辅助角色Passing messages from an Azure web role to an Azure worker role

队列服务概念Queue Service Concepts

队列服务包含以下组件:The Queue service contains the following components:

队列 1

  • URL 格式: 可使用以下 URL 格式对队列进行寻址:URL format: Queues are addressable using the following URL format:
    http://<storage account>.queue.core.chinacloudapi.cn/<queue>http://<storage account>.queue.core.chinacloudapi.cn/<queue>

    可使用以下 URL 访问示意图中的某个队列:The following URL addresses a queue in the diagram:

    http://myaccount.queue.core.chinacloudapi.cn/images-to-download

  • 存储帐户: 对 Azure 存储进行的所有访问都要通过存储帐户完成。Storage Account: All access to Azure Storage is done through a storage account. 有关存储帐户容量的详细信息,请参阅 Azure 存储可伸缩性和性能目标See Azure Storage Scalability and Performance Targets for details about storage account capacity.

  • 队列: 一个队列包含一组消息。Queue: A queue contains a set of messages. 所有消息必须位于相应的队列中。All messages must be in a queue. 请注意,队列名称必须全部小写。Note that the queue name must be all lowercase. 有关命名队列的详细信息,请参阅 命名队列和元数据For information on naming queues, see Naming Queues and Metadata.

  • 消息: 一条消息(不管采用何种格式)的最大大小为 64 KB。Message: A message, in any format, of up to 64 KB. 消息可以保留在队列中的最长时间为 7 天。The maximum time that a message can remain in the queue is 7 days.

创建 Azure 存储帐户Create an Azure storage account

创建第一个 Azure 存储帐户的最简单方法是使用 Azure 门户The easiest way to create your first Azure storage account is by using the Azure portal. 若要了解更多信息,请参阅 创建存储帐户To learn more, see Create a storage account.

还可使用 Azure PowerShellAzure CLI适用于 .NET 的 Azure 存储资源提供程序创建 Azure 存储帐户。You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .NET.

如果暂时不想在 Azure 中创建存储帐户,也可以使用 Azure 存储模拟器在本地环境中运行和测试代码。If you prefer not to create a storage account in Azure at this time, you can also use the Azure storage emulator to run and test your code in a local environment. 有关详细信息,请参阅 使用 Azure 存储模拟器进行开发和测试For more information, see Use the Azure Storage Emulator for Development and Testing.

下载和安装适用于 Python 的 Azure 存储 SDKDownload and Install Azure Storage SDK for Python

适用于 Python 的 Azure 存储 SDK 需要使用 Python 2.7、3.3、3.4、3.5 或 3.6。The Azure Storage SDK for Python requires Python 2.7, 3.3, 3.4, 3.5, or 3.6.

通过 PyPi 安装Install via PyPi

要通过 Python 包索引 (PyPI) 安装,请键入:To install via the Python Package Index (PyPI), type:

pip install azure-storage-queue

Note

如果要从适用于 Python 的 Azure 存储 SDK 版本 0.36 或更早版本升级,请在安装最新软件包之前使用 pip uninstall azure-storage 卸载旧版 SDK。If you are upgrading from the Azure Storage SDK for Python version 0.36 or earlier, uninstall the older SDK using pip uninstall azure-storage before installing the latest package.

有关备用安装方法,请参阅适用于 Python 的 Azure 存储 SDKFor alternative installation methods, see Azure Storage SDK for Python.

查看示例应用程序View the sample application

若要查看和运行示例应用程序,该应用程序演示如何将 Python 与 Azure 队列配合使用,请参阅 Azure Storage:Getting Started with Azure Queues in Python(Azure 存储:开始在 Python 中使用 Azure 队列)。To view and run a sample application that shows how to use Python with Azure Queues, see Azure Storage: Getting Started with Azure Queues in Python.

若要运行示例应用程序,请确保已安装 azure-storage-queueazure-storage-common 软件包。To run the sample application, make sure you have installed both the azure-storage-queue and azure-storage-common packages.

如何:创建队列How To: Create a Queue

可以通过 QueueService 对象来处理队列。The QueueService object lets you work with queues. 以下代码创建 QueueService 对象。The following code creates a QueueService object. 在希望在其中以编程方式访问 Azure 存储的任何 Python 文件中,将以下代码添加到文件的顶部附近:Add the following near the top of any Python file in which you wish to programmatically access Azure Storage:

from azure.storage.queue import QueueService

以下代码使用存储帐户名称和帐户密钥创建 QueueService 对象。The following code creates a QueueService object using the storage account name and account key. 使用帐户名称和密钥替换“myaccount”和“mykey”。Replace 'myaccount' and 'mykey' with your account name and key.

queue_service = QueueService(account_name='myaccount', account_key='mykey', endpoint_suffix='core.chinacloudapi.cn')

queue_service.create_queue('taskqueue')

如何:在队列中插入消息How To: Insert a Message into a Queue

若要在队列中插入消息,可使用 put_message 方法创建一条新消息并将其添加到队列中。To insert a message into a queue, use the put_message method to create a new message and add it to the queue.

queue_service.put_message('taskqueue', u'Hello World')

如何:扫视下一条消息How To: Peek at the Next Message

可以通过调用 peek_messages 方法,查看队列前面的消息,而不必从队列中将其删除。You can peek at the message in the front of a queue without removing it from the queue by calling the peek_messages method. 默认情况下,peek_messages 扫视单条消息。By default, peek_messages peeks at a single message.

messages = queue_service.peek_messages('taskqueue')
for message in messages:
    print(message.content)

如何:取消消息的排队How To: Dequeue Messages

代码分两步从队列中删除消息。Your code removes a message from a queue in two steps. 在调用 get_messages 时,默认情况下会获得队列中的下一条消息。When you call get_messages, you get the next message in a queue by default. 对于从此队列读取消息的任何其他代码,从 get_messages 返回的消息将变得不可见。A message returned from get_messages becomes invisible to any other code reading messages from this queue. 默认情况下,此消息持续 30 秒不可见。By default, this message stays invisible for 30 seconds. 若要从队列中删除消息,还必须调用 delete_message。To finish removing the message from the queue, you must also call delete_message. 此删除消息的两步过程可确保当代码因硬件或软件故障而无法处理消息时,其他代码实例可以获取同一消息并重试。This two-step process of removing a message assures that when your code fails to process a message due to hardware or software failure, another instance of your code can get the same message and try again. 处理消息后代码会立即调用 delete_message。Your code calls delete_message right after the message has been processed.

messages = queue_service.get_messages('taskqueue')
for message in messages:
    print(message.content)
    queue_service.delete_message('taskqueue', message.id, message.pop_receipt)

可以通过两种方式自定义队列中的消息检索。There are two ways you can customize message retrieval from a queue. 首先,可获取一批消息(最多 32 条)。First, you can get a batch of messages (up to 32). 其次,可以设置更长或更短的不可见超时时间,从而允许代码使用更多或更少时间来完全处理每个消息。Second, you can set a longer or shorter invisibility timeout, allowing your code more or less time to fully process each message. 以下代码示例使用 get_messages 方法在一次调用中获取 16 条消息。The following code example uses the get_messages method to get 16 messages in one call. 然后,它会使用 for 循环处理每条消息。Then it processes each message using a for loop. 它还将每条消息的不可见超时时间设置为 5 分钟。It also sets the invisibility timeout to five minutes for each message.

messages = queue_service.get_messages('taskqueue', num_messages=16, visibility_timeout=5*60)
for message in messages:
    print(message.content)
    queue_service.delete_message('taskqueue', message.id, message.pop_receipt)        

如何:更改已排队消息的内容How To: Change the Contents of a Queued Message

可以更改队列中现有消息的内容。You can change the contents of a message in-place in the queue. 如果消息表示工作任务,则可以使用此功能来更新该工作任务的状态。If the message represents a work task, you could use this feature to update the status of the work task. 以下代码使用 update_message 方法来更新消息。The code below uses the update_message method to update a message. 可见性超时设为 0,这意味着消息会立刻出现且内容将更新。The visibility timeout is set to 0, meaning the message appears immediately and the content is updated.

messages = queue_service.get_messages('taskqueue')
for message in messages:
    queue_service.update_message('taskqueue', message.id, message.pop_receipt, 0, u'Hello World Again')

如何:获取队列长度How To: Get the Queue Length

可以获取队列中消息的估计数。You can get an estimate of the number of messages in a queue. get_queue_metadata 方法要求队列服务返回有关队列的元数据和 approximate_message_count。The get_queue_metadata method asks the queue service to return metadata about the queue, and the approximate_message_count. 结果仅是近似值,因为在队列服务响应请求之后,可能添加或删除了消息。The result is only approximate because messages can be added or removed after the queue service responds to your request.

metadata = queue_service.get_queue_metadata('taskqueue')
count = metadata.approximate_message_count

如何:删除队列How To: Delete a Queue

若要删除队列及其中包含的所有消息,请调用 delete_queue 方法。To delete a queue and all the messages contained in it, call the delete_queue method.

queue_service.delete_queue('taskqueue')

后续步骤Next Steps

在了解了队列存储的基础知识后,可单击下面的链接了解详细信息。Now that you've learned the basics of Queue storage, follow these links to learn more.