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

概觀

本文示範使用 Azure 佇列儲存體服務的常見情況。 這些涵蓋的情況包括插入、瞄核、取得和刪除佇列訊息。 此外，建立和刪除佇列的程式碼也涵蓋在內。

本文中的範例是以 Python 撰寫，並使用 適用於 Python 的 Azure 佇列儲存體用戶端程式庫。 如需佇列的詳細資訊，請參閱後續步驟一節。

什麼是佇列儲存體？

Azure 佇列儲存體是一項儲存大量訊息的服務，全球任何地方都可利用 HTTP 或 HTTPS 並透過驗證的呼叫來存取這些訊息。 單一佇列訊息的大小上限為 64 KB，而一個佇列可以包含數百萬個訊息，以儲存體帳戶的總容量為限。 佇列儲存體通常用來建立要以非同步方式處理的待處理項目。

佇列服務概念

Azure 佇列服務包含下列元件：

• 儲存體帳戶： 一律透過儲存體帳戶來存取 Azure 儲存體。 如需儲存體帳戶的詳細資訊，請參閱儲存體帳戶概觀。

• 佇列： 佇列包含一組訊息。 所有訊息都必須放在佇列中。 請注意，佇列名稱必須是小寫。 如需為佇列命名的詳細資訊，請參閱 為佇列和中繼資料命名。

• 訊息： 大小上限為 64 KB 的訊息 (任何格式)。 訊息可保留在佇列中的時間上限為 7 天。 如需版本 2017-07-29 或更新版本，最大存留時間可以是任何正數，或是表示訊息未過期的 -1。 如果省略此參數，則預設存留時間為 7 天。

• URL 格式：您可以使用以下 URL 格式來定址佇列：http://<storage account>.queue.core.windows.net/<queue>

  下列 URL 可定址圖中的佇列：

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

建立 Azure 儲存體帳戶

建立您第一個 Azure 儲存體帳戶最簡單的方法，就是使用 Azure 入口網站。 若要深入了解，請參閱 建立儲存體帳戶。

您也可以使用 Azure PowerShell、Azure CLI，或 Azure Storage Resource Provider for .NET 來建立 Azure 儲存體帳戶。

如果您不想此時在 Azure 中建立儲存體帳戶，也可以使用 Azure 儲存體模擬器在本機環境中執行並測試您的程式碼。 如需詳細資訊，請參閱使用 Azure 模擬器進行本機 Azure 儲存體開發。

下載並安裝 Azure Storage SDK for Python

Azure Storage SDK for Python 需要 Python 2.7 版、3.3 版或更新版本。

透過 PyPI 安裝

若要透過 Python Package Index (PyPI) 安裝，請輸入：

pip install azure-storage-queue

如需替代安裝方法，請參閱 Azure SDK for Python。

從 Azure 入口網站複製您的認證

當應用程式範例向 Azure 儲存體發出要求時，該要求必須獲得授權。 若要對要求授權，請以連接字串的形式將儲存體帳戶認證新增至應用程式。 若要檢視您的儲存體帳戶認證，請遵循下列步驟：

1. 登入 Azure 入口網站。

2. 找出您的儲存體帳戶。

3. 在 [儲存體帳戶] 功能表窗格的 [安全性 + 網路] 下方，選取 [存取金鑰]。 在此處，您可以檢視帳戶存取金鑰，和每個金鑰的完整連接字串。

   

4. 在 [存取金鑰] 窗格中，選取 [顯示金鑰]。

5. 在 [金鑰 1] 區段中，找出連接字串值。 選取 [複製到剪貼簿] 圖示以複製連接字串。 在下一小節中，您會將該連接字串值新增至環境變數。

   

設定儲存體連接字串

在複製連接字串後，請在執行應用程式的本機電腦上，將該字串寫入至新的環境變數中。 若要設定環境變數，請開啟主控台視窗，並遵循您的作業系統所適用的指示。 將 <yourconnectionstring> 用實際的連接字串取代。

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

在 Windows 中新增環境變數之後，您必須啟動新的命令視窗執行個體。

重新啟動程式

新增環境變數之後，請重新啟動任何需要讀取環境變數的執行中程式。 例如，請先重新啟動您的開發環境或編輯器，然後再繼續。

設定您的應用程式以存取佇列儲存體

QueueClient 物件可讓您使用佇列。 在您想要以程式設計方式存取 Azure 佇列的任何 Python 檔案頂端附近，加入下列程式碼：

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

import os, uuid

os 套件支援擷取環境變數。 uuid 套件支援產生佇列名稱的唯一識別碼。

建立佇列

連接字串可從稍早設定的 AZURE_STORAGE_CONNECTION_STRING 環境變數中擷取。

下列程式碼使用儲存體連接字串來建立 QueueClient 物件。

# 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 佇列訊息會儲存為文字。 如果您想要儲存二進位資料，請在將訊息放入佇列之前，先設定 Base64 編碼和解碼函數。

建立用戶端物件時，請設定 Base64 編碼和解碼函數。

# 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()
                        )

將訊息插入佇列

若要將訊息插入佇列，請使用 send_message 方法。

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

查看訊息

您可以藉由呼叫 peek_messages 方法來瞄核訊息，而不需要從佇列中移除訊息。 根據預設，這個方法會瞄核單一訊息。

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

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

變更佇列訊息的內容

您可以在佇列中就地變更訊息內容。 如果訊息代表一項作業，則您可以使用此功能來更新該作業的狀態。

下列程式碼使用 update_message 方法來更新訊息。 可見度逾時設定為 0，表示會立即顯示訊息，並且會更新內容。

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_queue_properties 方法會傳回包含 approximate_message_count 在內的佇列屬性。

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

由於服務在回應您的要求之後可以新增或移除訊息，此結果僅為近似值。

清除佇列中的訊息

您可以使用兩個步驟將訊息從佇列中移除。 如果您的程式碼無法處理訊息，則此兩步驟程序可確保您可以取得相同的訊息，然後再試一次。 在成功處理訊息之後呼叫 delete_message。

呼叫 receive_messages 時，依預設，您會取得佇列中的下一個訊息。 從 receive_messages 傳回的訊息，對於從此佇列讀取訊息的任何其他程式碼而言，將會是不可見的。 依預設，此訊息會維持 30 秒的不可見狀態。 若要完成從佇列中移除訊息的作業，您還必須呼叫 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)

自訂從佇列中擷取訊息的方法有兩種。 首先，您可以取得一批訊息 (最多 32 個)。 其次，您可以設定較長或較短的可見度逾時，讓您的程式碼有較長或較短的時間可以完全處理每個訊息。

下列程式碼範例使用 receive_messages 方法分批次取得訊息。 然後，它會使用巢狀 for 迴圈處理每個批次中的每個訊息。 它也會將可見度逾時設定為每個訊息五分鐘。

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_queue 方法。

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

下一步

了解佇列儲存體的基本概念之後，請使用下列連結深入了解。

• Azure 佇列儲存體 Python API 參考
• Python 開發人員中心
• Azure 儲存體 REST API 參考

如需使用已取代 Python 第 2 版 SDK 的相關程式碼範例，請參閱 使用 Python 第 2 版的程式碼範例。