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

文章
03/13/2024

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

API 參考文件 | 程式庫原始程式碼 | 套件 (Python Package Index) | 範例

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

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

必要條件

Azure 訂用帳戶 - 建立免費帳戶
Azure 儲存體帳戶 - 建立儲存體帳戶
Python 3.8+

設定

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

建立專案

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

在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中，為專案建立一個新目錄。
```
mkdir queues-quickstart
```
切換至新建立的 queues-quickstart 目錄。
```
cd queues-quickstart
```

安裝套件

從專案目錄，使用 pip install 命令安裝適用於 Python 套件的 Azure 佇列儲存體用戶端程式庫。需要 Azure 身分識別 套件才能對 Azure 服務進行無密碼連線。

pip install azure-storage-queue azure-identity

設定應用程式架構

在程式碼編輯器中開啟新的文字檔
加入 import 陳述式

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

程式碼如下：

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)

將新檔案以 queues-quickstart.py 儲存在 queues-quickstart 目錄中。

向 Azure 驗證

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

您也可以直接使用密碼、連接字串或其他認證來授權對 Azure 服務的要求。不過，應該謹慎使用此方法。開發人員必須盡可能避免在不安全的地方公開秘密。能夠取得密碼或祕密金鑰存取的任何人都可以進行驗證。 DefaultAzureCredential 提供優於帳戶金鑰的管理和安全性優點，允許無密碼驗證。下列範例示範這兩個選項。

無密碼 (建議)
連接字串

DefaultAzureCredential 是適用於 Python 的 Azure 身分識別用戶端程式庫所提供的類別。如需深入了解 DefaultAzureCredential，請參閱 DefaultAzureCredential 概觀。 DefaultAzureCredential 支援多個驗證方法，並在執行階段判斷應該使用哪個方法。此方法可讓您的應用程式在不同的環境中 (本機或實際執行環境) 使用不同的驗證方法，而不需要實作環境特有的程式碼。

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

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

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

下列範例將 儲存體佇列資料參與者 角色指派給使用者帳戶，以針對儲存體帳戶中的佇列資料提供讀取和寫入存取權。

重要

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

在 Azure 入口網站中，使用主要搜尋列或左側導覽找出您的儲存體帳戶。
在儲存體帳戶概觀頁面上，從左側功能表中選取 [存取控制 (IAM)]。
在 [存取控制 (IAM)] 頁面上，選取 [角色指派] 索引標籤。
從頂端功能表選取 [+ 新增]，然後從產生的下拉功能表中選取 [新增角色指派]。

A screenshot showing how to assign a role.

使用搜尋方塊，從結果篩選出所需的角色。在此範例中，搜尋「儲存體佇列資料參與者」，接著選取相符的結果，然後選擇 [下一步]。
在 [存取權指派對象為] 下，選取 [使用者、群組或服務主體]，然後選擇 [+ 選取成員]。
在對話方塊中，搜尋 Microsoft Entra 使用者名稱 (通常是您的 user@domain 電子郵件地址)，然後在對話方塊底部選擇 [選取]。
選取 [檢閱 + 指派] 以移至最終頁面，然後再次選取 [檢閱 + 指派] 以完成此程序。

若要使用 Azure CLI 在資源層級指派角色，您必須先使用 az storage account show 命令擷取資源識別碼。您可以使用 --query 參數來篩選輸出屬性。

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

複製上述命令的輸出 Id。接著，您可以使用 Azure CLI 的 az role 命令來指派角色。

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

若要使用 Azure PowerShell 在資源層級指派角色，您必須先使用 Get-AzResource 命令擷取資源識別碼。

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

複製上述命令輸出的 Id 值。接著，您可以在 PowerShell 中使用 New-AzRoleAssignment 命令來指派角色。

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

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

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

登入 Azure 入口網站。
找出您的儲存體帳戶。
在 [儲存體帳戶] 功能表窗格的 [安全性 + 網路] 下方，選取 [存取金鑰]。在此處，您可以檢視帳戶存取金鑰，和每個金鑰的完整連接字串。
在 [存取金鑰] 窗格中，選取 [顯示金鑰]。
在 [金鑰 1] 區段中，找出連接字串值。選取 [複製到剪貼簿] 圖示以複製連接字串。在下一小節中，您會將該連接字串值新增至環境變數。

設定儲存體連接字串

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

Windows
Linux 和 macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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

重新啟動程式

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

重要

應該謹慎使用帳戶存取金鑰。如果帳戶存取金鑰遺失或意外放在不安全的地方，您的服務可能變得易受攻擊。具有存取金鑰的任何人都可以授權對儲存體帳戶的要求，並有效地存取所有資料。 DefaultAzureCredential 會提供增強的安全性功能和權益，建議用來管理對 Azure 服務的授權。

物件模型

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

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

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

Diagram of Queue storage architecture

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

QueueServiceClient: QueueServiceClient 可讓您管理儲存體帳戶中的所有佇列。
QueueClient: QueueClient 類別可讓您管理和操作個別佇列及其訊息。
QueueMessage: QueueMessage 類別代表在佇列上呼叫 receive_messages 時所傳回的個別物件。

程式碼範例

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

授權存取並建立用戶端物件
建立佇列
將訊息新增至佇列
窺視佇列中的訊息
更新佇列中的訊息
取得佇列長度
從佇列接收訊息
刪除佇列中的訊息
刪除佇列

無密碼 (建議)
連接字串

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

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

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

az login

您必須安裝 Azure CLI，才能透過 Visual Studio 程式碼使用 DefaultAzureCredential。

在 Visual Studio Code 的主功能表上，瀏覽至 [終端機] > [新增終端機]。

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

az login

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

Connect-AzAccount

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

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

from azure.identity import DefaultAzureCredential

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

重要

佇列名稱只能包含小寫字母、數字和連字號，且必須以字母或數字開頭。每個連字號前後都必須緊接非連字號的字元。名稱長度也必須為 3 到 63 個字元。如需為佇列命名的詳細資訊，請參閱為佇列和中繼資料命名。

在 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)

取得連接字串和建立用戶端

以下程式碼會擷取儲存體帳戶的連接字串。連接字串會儲存在設定儲存體連接字串一節中建立的環境變數。

在 try 區塊內加入此程式碼：

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

    # Retrieve the connection string for use with the application. The storage
    # connection string is stored in an environment variable on the machine
    # running the application called AZURE_STORAGE_CONNECTION_STRING. If the
    # environment variable is created after the application is launched in a
    # console or with Visual Studio, the shell or application needs to be
    # closed and reloaded to take the environment variable into account.
    connect_str = os.getenv('AZURE_STORAGE_CONNECTION_STRING')

決定佇列的名稱，並使用連接字串進行授權，建立 QueueClient 類別的執行個體。我們會使用此用戶端物件來建立並與儲存體帳戶中的佇列資源互動。

重要

佇列名稱只能包含小寫字母、數字和連字號，且必須以字母或數字開頭。每個連字號前後都必須緊接非連字號的字元。名稱長度也必須為 3 到 63 個字元。如需詳細資訊，請參閱為佇列和中繼資料命名。

將此程式碼加入到 try 區塊的結尾處：

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

    print("Creating queue: " + queue_name)

    # Instantiate a QueueClient which will be
    # used to create and manipulate the queue
    queue_client = QueueClient.from_connection_string(connect_str, queue_name)

佇列訊息會儲存為文字。如果您想要儲存二進位資料，請在將訊息放入佇列之前，先設定 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 方法，將訊息新增至佇列。它也會儲存第三次 send_message 呼叫所傳回的 QueueMessage。 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

如需使用已取代的 Python 第 2 版 SDK 的相關程式碼範例，請參閱使用 Python 第 2 版的程式碼範例。
若要深入了解，請參閱適用於 Python 的 Azure 儲存體程式庫。
如需更多 Azure 佇列儲存體範例應用程式，請參閱適用於 Python 的 Azure 佇列儲存體用戶端程式庫 - 範例。

分享方式：

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

必要條件

設定

建立專案

安裝套件

設定應用程式架構

向 Azure 驗證

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

設定儲存體連接字串

重新啟動程式

物件模型

程式碼範例

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

取得連接字串和建立用戶端

建立佇列

將訊息新增至佇列

窺視佇列中的訊息

更新佇列中的訊息

取得佇列長度

從佇列接收訊息

刪除佇列中的訊息

刪除佇列

執行程式碼

下一步

意見反映

更多資源