共用方式為

快速入門：適用於 Python 的 Azure 佇列儲存體用戶端程式庫

開始使用適用於 Python 的 Azure 佇列儲存體用戶端程式庫。 Azure 佇列儲存體是一種服務，可用來儲存大量訊息，以供稍後擷取和處理。 請遵循下列步驟來安裝套件，並試用基本工作的程式碼範例。

API 參考文件 | 程式庫原始碼 | 套件 （Python 套件索引） | 範例

使用適用於 Python 的 Azure 佇列儲存體用戶端程式庫來：

  • 建立佇列
  • 將訊息新增至佇列
  • 查看佇列中的訊息
  • 更新佇列中的訊息
  • 取得佇列長度
  • 從佇列接收訊息
  • 從佇列中刪除訊息
  • 刪除佇列

先決條件

設定

本節會逐步引導您準備專案，以使用適用於 Python 的 Azure 佇列儲存體用戶端程式庫。

建立專案

建立名為 queues-quickstart 的 Python 應用程式。

  1. 在主控台視窗 （例如 cmd、PowerShell 或 Bash） 中，為專案建立新目錄。

    mkdir queues-quickstart

  2. 切換至新建立的 queues-quickstart 目錄。

    cd queues-quickstart

安裝套件

從專案目錄中，使用命令 pip install 安裝適用於 Python 套件的 Azure 佇列儲存體用戶端程式庫。 Azure 服務的無密碼連線需要 azure-identity 套件。

pip install azure-storage-queue azure-identity

設定應用程式架構

  1. 在程式碼編輯器中開啟新的文字檔

  2. 新增 import 陳述式

  3. 建立程式的結構，包括基本例外狀況處理

    程式碼如下：

    import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.queue import QueueServiceClient, QueueClient, QueueMessage, BinaryBase64DecodePolicy, BinaryBase64EncodePolicy

try:
    print("Azure Queue storage - Python quickstart sample")
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

  4. 將新檔案儲存為 queues-quickstart 目錄中的 queues-quickstart.py。

向 Azure 驗證

大部分 Azure 服務的應用程式要求必須獲得授權。 使用 DefaultAzureCredential Azure 身分識別用戶端程式庫所提供的類別，是在程式碼中實作 Azure 服務的無密碼連線的建議方法。

您也可以直接使用密碼、連接字串或其他認證來授權對 Azure 服務的要求。 但是，應謹慎使用這種方法。 開發人員必須勤奮，永遠不要在不安全的位置暴露這些秘密。 任何獲得密碼或密鑰訪問權限的人都可以進行身份驗證。 DefaultAzureCredential 提供比帳戶金鑰更好的管理和安全優勢，以允許無密碼驗證。 下列範例示範這兩個選項。

DefaultAzureCredential 是適用於 Python 的 Azure 身分識別用戶端程式庫所提供的類別。 若要深入 DefaultAzureCredential瞭解 ，請參閱 DefaultAzureCredential 概觀。 DefaultAzureCredential 支援多種身份驗證方法，並決定在運行時應該使用哪種方法。 此方法可讓您的應用程式在不同的環境 （本機與生產環境） 中使用不同的驗證方法，而無需實作環境特定的程式碼。

例如，您的應用程式可以在本機開發時使用 Visual Studio Code 登入認證進行驗證，然後在部署至 Azure 之後使用 受控識別 。 此轉移不需要變更程式碼。

在本機開發時，請確定存取佇列資料的使用者帳戶具有正確的權限。 您需要具備儲存體佇列資料參與者的權限，才能讀取和寫入佇列資料。 若要指派此角色給您自己，您需要被指派使用者存取管理員角色，或另一個包含 Microsoft.Authorization/roleAssignments/write 動作的角色。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell，將 Azure RBAC 角色指派給使用者。 您可以在範圍概觀頁面上深入了解角色指派的可用範圍。

在此案例中，您會將許可權指派給使用者帳戶 （範圍限定為儲存體帳戶），以遵循 最低許可權原則。 此做法只為使用者提供所需的最低權限，並建立更安全的實際執行環境。

下列範例會將 儲存佇列資料貢獻者 角色指派給您的使用者帳戶，以在您的儲存帳戶中提供佇列資料的讀寫許可權。

這很重要

在大部分情況下，角色指派在 Azure 中傳播只需要一兩分鐘，但在罕見情況下，可能需要長達八分鐘。 如果您第一次執行程式碼時收到驗證錯誤，請稍候片刻再試一次。

  1. 在 Azure 入口網站中，使用主要搜尋列或左側導覽找出您的儲存體帳戶。

  2. 在儲存體帳戶概觀頁面上，從左側功能表中選取 [存取控制 （IAM）]。

  3. 在 [存取控制 (IAM)] 頁面上，選取 [角色指派] 索引標籤。

  4. 從頂端功能表中選取 [+ 新增 ]，然後從產生的下拉式功能表中選取 [ 新增角色指派 ]。

顯示如何指派角色的螢幕擷取畫面。

  1. 使用搜尋方塊，從結果篩選出所需的角色。 在此範例中，搜尋 Storage Queue Data Contributor 並選取相符的結果，然後選擇 Next （下一步）。

  2. 在 [存取權指派對象為] 下，選取 [使用者、群組或服務主體]，然後選擇 [+ 選取成員]。

  3. 在對話方塊中，搜尋 Microsoft Entra 使用者名稱 (通常是您的 user@domain 電子郵件地址)，然後在對話方塊底部選擇 [選取]。

  4. 選取 [檢閱 + 指派] 以移至最終頁面，然後再次選取 [檢閱 + 指派] 以完成此程序。

物件模型

Azure 佇列儲存體是儲存大量訊息的服務。 佇列訊息的大小上限為 64 KB。 佇列可能包含數百萬則訊息，最高可達儲存體帳戶的總容量限制。 佇列通常用來建立待辦專案以非同步處理。 佇列儲存體提供三種類型的資源：

  • 儲存體帳戶：Azure 儲存體的所有存取都是透過儲存體帳戶完成。 如需儲存體帳戶的詳細資訊，請參閱 儲存體帳戶概觀
  • 佇列：佇列包含一組訊息。 所有訊息都必須在佇列中。 請注意，佇列名稱必須全部為小寫。 如需命名佇列的資訊，請參閱 命名佇列和中繼資料。
  • 訊息：任何格式的訊息，最大為 64 KB。 訊息最多可以在佇列中保留 7 天。 對於 2017-07-29 版或更新版本，存留時間上限可以是任何正數，或 -1 表示訊息不會過期。 如果省略此參數，則預設存留時間為 7 天。

下圖顯示這些資源之間的關係。

佇列儲存體架構圖

使用下列 Python 類別與這些資源互動：

程式碼範例

這些範例程式碼片段示範如何使用適用於 Python 的 Azure 佇列儲存體用戶端程式庫執行下列動作：

授權存取並建立用戶端物件

請確定使用您指派角色的相同 Microsoft Entra 帳戶進行驗證。 您可以透過 Azure CLI、Visual Studio Code 或 Azure PowerShell 進行驗證。

使用下列命令透過 Azure CLI 登入 Azure：

az login

驗證之後，您可以使用QueueClient建立和授權DefaultAzureCredential物件，以存取儲存體帳戶中的佇列資料。 DefaultAzureCredential 自動探索並使用您在上一個步驟中登入時使用的帳戶。

若要授權使用 DefaultAzureCredential，請確定您已新增 azure-identity 套件，如 安裝套件中所述。 此外，請務必在 queues-quickstart.py 檔案中新增下列 import 陳述式：

from azure.identity import DefaultAzureCredential

為佇列決定一個名稱，並建立 QueueClient 類別的實例，使用 DefaultAzureCredential 進行授權。 我們會使用此用戶端物件來建立儲存體帳戶中的佇列資源並與之互動。

這很重要

佇列名稱只能包含小寫字母、數字和連字號，而且必須以字母或數字開頭。 每個連字號之前和後面都必須有一個非連字號字元。 名稱的長度也必須介於 3 到 63 個字元之間。 如需命名佇列的相關資訊，請參閱 命名佇列和 meta 資料。

在 try 區塊內新增下列程式碼，並確保替換 <storage-account-name> 佔位符值：

    print("Azure Queue storage - Python quickstart sample")

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

    account_url = "https://<storageaccountname>.queue.core.windows.net"
    default_credential = DefaultAzureCredential()

    # Create the QueueClient object
    # We'll use this object to create and interact with the queue
    queue_client = QueueClient(account_url, queue_name=queue_name ,credential=default_credential)

佇列訊息會儲存為文字。 如果要儲存二進位數據，請在將訊息放入佇列之前設定 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()
                        )

建立佇列

使用 QueueClient 物件，呼叫 create_queue 方法，在您的儲存帳戶中建立佇列。

將以下程式碼新增至區塊的 try 末尾：

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

將訊息新增至佇列

下列程式碼片段會呼叫 send_message 方法，將訊息新增至佇列。 其也會儲存第三次 QueueMessage 呼叫所傳回的 send_message。 在程式中，saved_message 用於稍後更新訊息內容。

將以下程式碼新增至區塊的 try 末尾：

    print("\nAdding messages to the queue...")

    # Send several messages to the queue
    queue_client.send_message(u"First message")
    queue_client.send_message(u"Second message")
    saved_message = queue_client.send_message(u"Third message")

查看佇列中的訊息

藉由呼叫 peek_messages 方法來窺視佇列中的訊息。 這個方法會從佇列前面擷取一或多個訊息，但不會變更訊息的可見度。

將以下程式碼新增至區塊的 try 末尾：

    print("\nPeek at the messages in the queue...")

    # Peek at messages in the queue
    peeked_messages = queue_client.peek_messages(max_messages=5)

    for peeked_message in peeked_messages:
        # Display the message
        print("Message: " + peeked_message.content)

更新佇列中的訊息

使用update_message方法更新訊息的內容。 這個方法可以變更訊息的可見性逾時和內容。 訊息內容必須是大小不超過 64 KB 的 UTF-8 編碼字串。 將稍早在程式碼中儲存的訊息的值與新內容一起傳遞。 這些 saved_message 值會識別要更新的訊息。

    print("\nUpdating the third message in the queue...")

    # Update a message using the message saved when calling send_message earlier
    queue_client.update_message(saved_message, pop_receipt=saved_message.pop_receipt, \
        content="Third message has been updated")

取得佇列長度

您可以取得佇列中訊息數目的估計值。

get_queue_properties 方法會傳回佇列屬性，包括 approximate_message_count.

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

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

從佇列接收訊息

您可以呼叫方法 receive_messages 來下載先前新增的訊息。

將以下程式碼新增至區塊的 try 末尾：

    print("\nReceiving messages from the queue...")

    # Get messages from the queue
    messages = queue_client.receive_messages(max_messages=5)

呼叫 receive_messages 方法時，您可以選擇性地指定 的 max_messages值，這是要從佇列擷取的訊息數目。 預設值為 1 則訊息，上限為 32 則訊息。 您也可以為 visibility_timeout 指定值，以隱藏逾時期間其他作業的訊息。 預設值為 30 秒。

從佇列中刪除訊息

在收到並處理訊息之後，從佇列中刪除訊息。 在此情況下，處理只是在主控台上顯示訊息。

應用程式會在處理和刪除訊息之前呼叫 input 來暫停使用者輸入。 在刪除資源之前，請在 Azure 入口網站 中確認已正確建立資源。 任何未明確刪除的訊息最終都會再次在佇列中可見，以便再次有機會處理它們。

將以下程式碼新增至區塊的 try 末尾：

    print("\nPress Enter key to 'process' messages and delete them from the queue...")
    input()

    for msg_batch in messages.by_page():
            for msg in msg_batch:
                # "Process" the message
                print(msg.content)
                # Let the service know we're finished with
                # the message and it can be safely deleted.
                queue_client.delete_message(msg)

刪除佇列

下列程式碼會使用 delete_queue 方法刪除佇列，以清除應用程式所建立的資源。

將此程式碼新增至區塊結 try 尾並儲存檔案：

    print("\nPress Enter key to delete the queue...")
    input()

    # Clean up
    print("Deleting queue...")
    queue_client.delete_queue()

    print("Done")

執行程式碼

此應用程式會建立三則訊息，並將其新增至 Azure 佇列。 程式碼會列出佇列中的訊息，然後擷取並刪除它們，最後刪除佇列。

在控制台視窗中，導覽至包含 queues-quickstart.py 檔案的目錄，然後使用下列 python 命令執行應用程式。

python queues-quickstart.py

應用程式的輸出類似下列範例：

Azure Queue Storage client library - Python quickstart sample
Creating queue: quickstartqueues-<UUID>

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

First message
Second message
Third message has been updated

Press Enter key to delete the queue...

Deleting queue...
Done

當應用程式在接收訊息之前暫停時，請在 Azure 入口網站 中檢查您的儲存體帳戶。 確認訊息是否在佇列中。

按 鍵 Enter 接收和刪除訊息。 出現提示時，再次按 鍵 Enter 刪除佇列並完成示範。

後續步驟

在本快速入門中，您已瞭解如何使用 Python 程式碼建立佇列，並將訊息新增至佇列。 然後你學會了查看、檢索和刪除訊息。 最後，您瞭解如何刪除訊息佇列。

如需教學課程、範例、快速入門和其他文件，請造訪：

適用於 Python 開發人員的 Azure

  • Last updated on