如何從 Python 使用 Azure 佇列儲存體How to use Azure Queue Storage from Python

概觀Overview

本文示範使用 Azure 佇列儲存體服務的常見案例。This article demonstrates common scenarios using the Azure Queue Storage service. 涵蓋的案例包括插入、查看、取得和刪除佇列訊息。The scenarios covered include inserting, peeking, getting, and deleting queue messages. 此外也涵蓋建立和刪除佇列的程式碼。Code for creating and deleting queues is also covered.

本文中的範例是以 Python 撰寫,並使用 適用于 python 的 Azure 佇列儲存體用戶端程式庫The examples in this article are written in Python and use the Azure Queue Storage client library for Python. 如需佇列的詳細資訊,請參閱後續步驟一節。For more information on queues, see 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. 佇列儲存體通常用來建立要以非同步方式處理的待處理專案(backlog)。Queue storage is often used to create a backlog of work to process asynchronously.

佇列服務概念Queue service concepts

Azure 佇列服務包含下列元件:The Azure Queue service contains the following components:

Azure 佇列服務元件

  • 儲存體帳戶: Azure 儲存體的所有存取都是透過儲存體帳戶完成。Storage Account: All access to Azure Storage is done through a storage account. 如需儲存體帳戶的詳細資訊,請參閱儲存體帳戶概觀For more information about storage accounts, see Storage account overview.

  • 佇列: 佇列包含一組訊息。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. 如需版本 2017-07-29 或更新版本,最大存留時間可以是任何正數,或是表示訊息未過期的 -1。For version 2017-07-29 or later, the maximum time-to-live can be any positive number, or -1 indicating that the message doesn't expire. 如果省略此參數,則預設存留時間為 7 天。If this parameter is omitted, the default time-to-live is seven days.

  • URL 格式: 您可以使用下列 URL 格式來定址佇列: HTTP:// <storage account> . queue.core.windows.net/<queue>URL format: Queues are addressable using the following URL format: http://<storage account>.queue.core.windows.net/<queue>

    下列 URL 可定址圖中的佇列:The following URL addresses a queue in the diagram:

    http://myaccount.queue.core.windows.net/incoming-orders

建立 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,或 Azure Storage Resource Provider for .NET 來建立 Azure 儲存體帳戶。You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .NET.

如果您目前不想要在 Azure 中建立儲存體帳戶,您也可以使用 Azurite 儲存體模擬器在本機環境中執行並測試您的程式碼。If you prefer not to create a storage account in Azure at this time, you can also use the Azurite storage emulator to run and test your code in a local environment. 如需詳細資訊,請參閱 使用 Azurite 模擬器進行本機 Azure 儲存體開發For more information, see Use the Azurite emulator for local Azure Storage development.

下載並安裝 Azure Storage SDK for PythonDownload and install Azure Storage SDK for Python

適用于 python 的 AZURE 儲存體 SDK需要 python 2.7、3.3 版或更新版本。The Azure Storage SDK for Python requires Python v2.7, v3.3, or later.

透過 PyPI 安裝Install via PyPI

若要透過 Python Package Index (PyPI) 安裝,請輸入:To install via the Python Package Index (PyPI), type:

pip install azure-storage-queue

注意

如果您要從 Azure 儲存體 SDK for Python v 0.36 或更早版本升級,請 pip uninstall azure-storage 在安裝最新封裝之前,先使用舊版 sdk 卸載。If you are upgrading from the Azure Storage SDK for Python v0.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 SDK for Python.

從 Azure 入口網站複製您的認證Copy your credentials from the Azure portal

當應用程式範例向 Azure 儲存體發出要求時,該要求必須獲得授權。When the sample application makes a request to Azure Storage, it must be authorized. 若要對要求授權,請以連接字串的形式將儲存體帳戶認證新增至應用程式。To authorize a request, add your storage account credentials to the application as a connection string. 請依照下列步驟檢視您的儲存體帳戶認證:View your storage account credentials by following these steps:

  1. 登入 Azure 入口網站Sign in to the Azure portal.

  2. 找出您的儲存體帳戶。Locate your storage account.

  3. 在儲存體帳戶概觀的 [設定] 區段中,選取 [存取金鑰]。In the Settings section of the storage account overview, select Access keys. 在此處,您可以檢視帳戶存取金鑰,和每個金鑰的完整連接字串。Here, you can view your account access keys and the complete connection string for each key.

  4. 尋找 [金鑰 1] 下方的 [連接字串] 值,然後選取 [複製] 按鈕以複製連接字串。Find the Connection string value under key1, and select the Copy button to copy the connection string. 在下一個步驟中,您會將連接字串值新增至環境變數。You will add the connection string value to an environment variable in the next step.

    顯示如何從 Azure 入口網站複製連接字串的螢幕擷取畫面

設定儲存體連接字串Configure your storage connection string

在複製您的連接字串後,請在執行應用程式的本機電腦上,將該字串寫入至新的環境變數中。After you have copied your connection string, write it to a new environment variable on the local machine running the application. 若要設定環境變數,請開啟主控台視窗,並遵循您的作業系統所適用的指示。To set the environment variable, open a console window, and follow the instructions for your operating system. <yourconnectionstring> 用實際的連接字串取代。Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

在 Windows 中新增環境變數之後,您必須啟動新的命令視窗執行個體。After you add the environment variable in Windows, you must start a new instance of the command window.

LinuxLinux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOSmacOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

重新啟動程式Restart programs

新增環境變數之後,請重新啟動任何需要讀取環境變數的執行中程式。After you add the environment variable, restart any running programs that will need to read the environment variable. 例如,在繼續之前,先重新啟動您的開發環境或編輯器。For example, restart your development environment or editor before continuing.

設定您的應用程式以存取佇列儲存體Configure your application to access Queue Storage

QueueClient物件可讓您使用佇列。The QueueClient object lets you work with a queue. 將下列程式碼新增至您想要以程式設計方式存取 Azure 佇列之任何 Python 檔案的頂端附近:Add the following code near the top of any Python file in which you wish to programmatically access an Azure queue:

from azure.storage.queue import (
        QueueClient,
        BinaryBase64EncodePolicy,
        BinaryBase64DecodePolicy
)

import os, uuid

os封裝會提供取得環境變數的支援。The os package provides support to retrieve an environment variable. uuid封裝可支援產生佇列名稱的唯一識別碼。The uuid package provides support for generating a unique identifier for a queue name.

建立佇列Create a queue

從稍早設定的環境變數中取出連接字串 AZURE_STORAGE_CONNECTION_STRINGThe connection string is retrieved from the AZURE_STORAGE_CONNECTION_STRING environment variable set earlier.

下列程式碼會 QueueClient 使用儲存體連接字串來建立物件。The following code creates a QueueClient object using the storage connection string.

# Retrieve the connection string from an environment
# variable named AZURE_STORAGE_CONNECTION_STRING
connect_str = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

# Create a unique name for the queue
q_name = "queue-" + str(uuid.uuid4())

# Instantiate a QueueClient object which will
# be used to create and manipulate the queue
print("Creating queue: " + q_name)
queue_client = QueueClient.from_connection_string(connect_str, q_name)

# Create the queue
queue_client.create_queue()

Azure 佇列訊息會儲存為文字。Azure queue messages are stored as text. 如果您想要儲存二進位資料,請在將訊息放入佇列之前,先設定 Base64 編碼和解碼函數。If you want to store binary data, setup Base64 encoding and decoding functions before putting a message in the queue.

建立用戶端物件時,請設定 Base64 編碼和解碼函數。Configure Base64 encoding and decoding functions when creating the client object.

# Setup Base64 encoding and decoding functions
base64_queue_client = QueueClient.from_connection_string(
                            conn_str=connect_str, queue_name=q_name,
                            message_encode_policy = BinaryBase64EncodePolicy(),
                            message_decode_policy = BinaryBase64DecodePolicy()
                        )

將訊息插入佇列Insert a message into a queue

若要將訊息插入佇列中,請使用 send_message 方法。To insert a message into a queue, use the send_message method.

message = u"Hello World"
print("Adding message: " + message)
queue_client.send_message(message)

查看訊息Peek at messages

您可以藉由呼叫方法來查看訊息,而不需要從佇列中移除訊息 peek_messagesYou can peek at messages without removing them from the queue by calling the peek_messages method. 根據預設,這個方法會查看單一訊息。By default, this method peeks at a single message.

# Peek at the first message
messages = queue_client.peek_messages()

for peeked_message in messages:
    print("Peeked message: " + peeked_message.content)

變更佇列訊息的內容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 task, you can use this feature to update the status of the task.

下列程式碼會使用 update_message 方法來更新訊息。The following code 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_client.receive_messages()
list_result = next(messages)

message = queue_client.update_message(
        list_result.id, list_result.pop_receipt,
        visibility_timeout=0, content=u'Hello World Again')

print("Updated message to: " + message.content)

取得佇列長度Get the queue length

您可以取得佇列中的估計訊息數目。You can get an estimate of the number of messages in a queue.

Get_queue_properties方法會傳回佇列屬性,包括 approximate_message_countThe get_queue_properties method returns queue properties including the approximate_message_count.

properties = queue_client.get_queue_properties()
count = properties.approximate_message_count
print("Message count: " + str(count))

結果只是近似值,因為在服務回應您的要求之後,就可以新增或移除訊息。The result is only approximate because messages can be added or removed after the service responds to your request.

清除佇列中的訊息Dequeue messages

透過兩個步驟將訊息從佇列中移除。Remove a message from a queue in two steps. 如果您的程式碼無法處理訊息,此兩步驟程式可確保您可以取得相同的訊息,然後再試一次。If your code fails to process a message, this two-step process ensures that you can get the same message and try again. delete_message在成功處理訊息之後呼叫。Call delete_message after the message has been successfully processed.

當您呼叫 receive_messages時,您預設會取得佇列中的下一則訊息。When you call receive_messages, you get the next message in the queue by default. receive_messages 傳回的訊息,對於從此佇列讀取訊息的任何其他程式碼而言,將會是不可見的。A message returned from receive_messages becomes invisible to any other code reading messages from this queue. 依預設,此訊息會維持 30 秒的不可見狀態。By default, this message stays invisible for 30 seconds. 若要完成從佇列中移除訊息的作業,您也必須呼叫 delete_messageTo finish removing the message from the queue, you must also call delete_message.

messages = queue_client.receive_messages()

for message in messages:
    print("Dequeueing message: " + message.content)
    queue_client.delete_message(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.

下列程式碼範例會使用 receive_messages 方法,以批次方式取得訊息。The following code example uses the receive_messages method to get messages in batches. 然後,它會使用嵌套迴圈處理每個批次中的每個訊息 forThen it processes each message within each batch by using a nested for loop. 它也會將可見度逾時設定為每個訊息五分鐘。It also sets the invisibility timeout to five minutes for each message.

messages = queue_client.receive_messages(messages_per_page=5, visibility_timeout=5*60)

for msg_batch in messages.by_page():
   for msg in msg_batch:
      print("Batch dequeue message: " + msg.content)
      queue_client.delete_message(msg)

刪除佇列Delete a queue

若要刪除佇列及其內含的所有訊息,請呼叫 delete_queue 方法。To delete a queue and all the messages contained in it, call the delete_queue method.

print("Deleting queue: " + queue_client.queue_name)
queue_client.delete_queue()

提示

Microsoft Azure 儲存體總管Try the Microsoft Azure Storage Explorer

Microsoft Azure 儲存體總管 是一個免費的獨立應用程式,可讓您在 Windows、MacOS 和 Linux 上以視覺化方式處理 Azure 儲存體資料。Microsoft 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.

下一步Next steps

既然您已瞭解佇列儲存體的基本概念,請參考下列連結以深入瞭解。Now that you've learned the basics of Queue Storage, follow these links to learn more.