如何使用來自 Python 的 Azure 佇列記憶體

概觀

本文示範使用 Azure 佇列記憶體服務的常見案例。 涵蓋的案例包括插入、查看、取得和刪除佇列訊息。 也涵蓋建立和刪除佇列的程序代碼。

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

什麼是佇列記憶體？

Azure 佇列記憶體是一項服務，可用來儲存大量訊息，可透過 HTTP 或 HTTPS 的已驗證呼叫從世界各地存取。 單一佇列訊息的大小最多可達 64 KB，而佇列可以包含數百萬則訊息，最多可達記憶體帳戶的總容量限制。 佇列存儲通常用於建立待處理工作的清單，以便進行異步處理。

隊列服務概念

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

• 記憶體帳戶： 所有對 Azure 記憶體的存取都是透過記憶體帳戶完成。 如需儲存體帳戶的詳細資訊，請參閱儲存體帳戶概觀。

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

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

• 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或適用於 .NET 的 Azure 記憶體資源提供者來建立 Azure 記憶體帳戶。

如果您目前不想在 Azure 中建立記憶體帳戶，您也可以使用 Azurite 記憶體模擬器在本機環境中執行和測試程式代碼。 如需詳細資訊，請參閱 使用 Azurite 模擬器進行本機 Azure 記憶體開發。

下載並安裝適用於 Python 的 Azure 記憶體 SDK

適用於 Python 的 Azure 記憶體 SDK 需要 Python v2.7、v3.3 或更新版本。

透過 PyPI 安裝

若要透過 Python 套件索引安裝 （PyPI），請輸入：

pip install azure-storage-queue

如需替代安裝方法，請參閱 適用於 Python 的 Azure SDK。

從 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 版的程式代碼範例。