Udostępnij przez

Szybki start: biblioteka klienta usługi Azure Queue Storage dla języka Python

Wprowadzenie do biblioteki klienta usługi Azure Queue Storage dla języka Python. Azure Queue Storage to usługa do przechowywania dużej liczby komunikatów na potrzeby późniejszego pobierania i przetwarzania. Wykonaj następujące kroki, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

Dokumentacja referencyjna API | Kod źródłowy biblioteki | Pakiet (indeks pakietów języka Python) | Przykłady

Użyj biblioteki klienta usługi Azure Queue Storage dla języka Python, aby:

  • Utwórz kolejkę
  • Dodaj komunikaty do kolejki
  • Zajrzyj do komunikatów w kolejce
  • Zaktualizuj komunikat w kolejce
  • Pobierz długość kolejki
  • Odbieranie komunikatów z kolejki
  • Usuwanie komunikatów z kolejki
  • Usuń kolejkę

Wymagania wstępne

Konfigurowanie

Ta sekcja przeprowadzi Cię przez proces przygotowywania projektu do pracy z biblioteką klienta usługi Azure Queue Storage dla języka Python.

Tworzenie projektu

Utwórz aplikację w języku Python o nazwie queues-quickstart.

  1. W oknie konsoli (takim jak cmd, PowerShell lub Bash) utwórz nowy katalog dla projektu.

    mkdir queues-quickstart

  2. Przejdź do nowo utworzonego katalogu queues-quickstart .

    cd queues-quickstart

Instalowanie pakietów

Z katalogu projektu zainstaluj bibliotekę klienta usługi Azure Queue Storage dla pakietu języka Python przy użyciu pip install polecenia . Pakiet azure-identity jest wymagany w przypadku połączeń bez hasła z usługami platformy Azure.

pip install azure-storage-queue azure-identity

Konfigurowanie struktury aplikacji

  1. Otwieranie nowego pliku tekstowego w edytorze kodu

  2. Dodawanie import instrukcji

  3. Tworzenie struktury programu, w tym podstawowej obsługi wyjątków

    Oto kod:

    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. Zapisz nowy plik jako queues-quickstart.py w katalogu queues-quickstart .

Uwierzytelnianie na platformie Azure

Żądania aplikacji do większości usług platformy Azure muszą być autoryzowane. DefaultAzureCredential Użycie klasy udostępnionej przez bibliotekę klienta tożsamości platformy Azure jest zalecanym podejściem do implementowania połączeń bez hasła z usługami platformy Azure w kodzie.

Możesz również autoryzować żądania do usług platformy Azure przy użyciu haseł, parametrów połączenia lub innych poświadczeń bezpośrednio. Należy jednak zachować ostrożność przy użyciu tego podejścia. Deweloperzy muszą być ostrożni, aby nigdy nie ujawniać tych sekretów w niezabezpieczonym miejscu. Każdy, kto uzyskuje dostęp do hasła lub klucza tajnego, może się uwierzytelnić. DefaultAzureCredential oferuje ulepszone korzyści związane z zarządzaniem i zabezpieczeniami za pośrednictwem klucza konta, aby umożliwić uwierzytelnianie bez hasła. Obie opcje przedstawiono w poniższym przykładzie.

DefaultAzureCredential jest klasą dostarczaną przez bibliotekę klienta tożsamości platformy Azure dla języka Python. Aby dowiedzieć się więcej na temat usługi DefaultAzureCredential, zobacz Omówienie DefaultAzureCredential. DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, która metoda powinna być używana w czasie wykonywania. Takie podejście umożliwia aplikacji używanie różnych metod uwierzytelniania w różnych środowiskach (lokalnych i produkcyjnych) bez implementowania kodu specyficznego dla środowiska.

Na przykład aplikacja może uwierzytelniać się przy użyciu poświadczeń logowania programu Visual Studio Code podczas opracowywania lokalnie, a następnie używać tożsamości zarządzanej po jej wdrożeniu na platformie Azure. Do tego przejścia nie są wymagane żadne zmiany kodu.

Podczas tworzenia aplikacji lokalnie upewnij się, że konto użytkownika, które uzyskuje dostęp do danych kolejki, ma odpowiednie uprawnienia. Będziesz potrzebować Storage Queue Data Contributor, aby móc odczytywać i zapisywać dane w kolejce. Aby przypisać sobie tę rolę, musisz mieć przypisaną rolę Administratora dostępu użytkowników lub inną rolę obejmującą akcję Microsoft.Authorization/roleAssignments/write . Role RBAC platformy Azure można przypisać użytkownikowi przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell. Więcej informacji na temat dostępnych zakresów przypisań ról można znaleźć na stronie przeglądu zakresu.

W tym scenariuszu przypiszesz uprawnienia do Twojego konta użytkownika w zakresie konta magazynowego, aby postępować zgodnie z zasadą najniższych uprawnień. Ta praktyka zapewnia użytkownikom tylko minimalne wymagane uprawnienia i tworzy bezpieczniejsze środowiska produkcyjne.

W poniższym przykładzie do Twojego konta użytkownika zostanie przypisana rola Kontrybutor danych kolejki magazynowej, która zapewnia zarówno dostęp do odczytu, jak i zapisu danych kolejki w Twoim koncie magazynowym.

Ważne

W większości przypadków propagacja przypisania roli na platformie Azure potrwa minutę lub dwie, ale w rzadkich przypadkach może upłynąć do ośmiu minut. Jeśli podczas pierwszego uruchomienia kodu wystąpią błędy uwierzytelniania, zaczekaj chwilę i spróbuj ponownie.

  1. W portalu Azure znajdź swoje konto magazynowe za pomocą głównego paska wyszukiwania lub nawigacji po lewej stronie.

  2. Na stronie przeglądu konta przechowywania wybierz pozycję Kontrola dostępu (IAM) z menu po lewej stronie.

  3. Na stronie Kontrola dostępu (Zarządzanie dostępem) wybierz kartę Przydziały ról.

  4. Wybierz + Dodaj z górnego menu, a następnie Dodaj przypisanie roli z wyświetlonego menu rozwijanego.

Zrzut ekranu przedstawiający sposób przypisywania roli.

  1. Użyj pola wyszukiwania, aby filtrować wyniki do żądanej roli. W tym przykładzie wyszukaj pozycję Kontrybutor danych w kolejce Storage i wybierz wynik, który pasuje, a następnie wybierz pozycję Dalej.

  2. W obszarze Przypisz dostęp do wybierz Użytkownik, grupa lub jednostka usługi, a następnie wybierz + Wybierz członków.

  3. W oknie dialogowym wyszukaj nazwę użytkownika firmy Microsoft Entra (zazwyczaj adres e-mail user@domain ), a następnie wybierz pozycję Wybierz w dolnej części okna dialogowego.

  4. Wybierz pozycję Przejrzyj i przypisz , aby przejść do ostatniej strony, a następnie ponownie przejrzyj i przypisz, aby ukończyć proces.

Model obiektów

Azure Queue Storage to usługa do przechowywania dużej liczby komunikatów. Komunikat w kolejce może mieć maksymalnie 64 KB rozmiaru. Kolejka może zawierać miliony wiadomości, aż do całkowitego limitu pojemności konta magazynowego. Kolejki są często używane do tworzenia zapasu zaległych zadań w celu asynchronicznego przetwarzania zadań. Usługa Queue Storage oferuje trzy typy zasobów:

  • Konto magazynowe: Wszystkie operacje dostępu do usługi Azure Storage odbywają się za pośrednictwem konta magazynowego. Aby uzyskać więcej informacji na temat kont magazynu, zobacz Omówienie konta magazynu
  • Kolejka: kolejka zawiera zestaw komunikatów. Wszystkie wiadomości muszą być w kolejce. Pamiętaj, że nazwa kolejki może zawierać tylko małe litery. Informacje dotyczące nazewnictwa kolejek można znaleźć w sekcji Naming Queues and Metadata.
  • Komunikat: komunikat w dowolnym formacie, o maksymalnym rozmiarze 64 KB. Komunikat może pozostać w kolejce przez maksymalnie 7 dni. W przypadku wersji 2017-07-29 lub nowszej maksymalny czas wygaśnięcia może być dowolną liczbą dodatnią lub -1 wskazującą, że komunikat nie wygasa. Jeśli ten parametr zostanie pominięty, domyślny czas wygaśnięcia wynosi siedem dni.

Na poniższym diagramie przedstawiono relacje między tymi zasobami.

Diagram architektury przechowywania kolejek

Użyj następujących klas języka Python, aby wchodzić w interakcje z tymi zasobami:

  • QueueServiceClient: QueueServiceClient to umożliwia zarządzanie wszystkimi kolejkami w koncie magazynowym.
  • QueueClient: Klasa QueueClient umożliwia zarządzanie pojedynczą kolejką i jej komunikatami oraz manipulowanie nimi.
  • QueueMessage: Klasa QueueMessage reprezentuje poszczególne obiekty, które są zwracane podczas wywoływania receive_messages na kolejce.

Przykłady kodu

Te przykładowe fragmenty kodu pokazują, jak wykonać następujące czynności za pomocą biblioteki klienta usługi Azure Queue Storage dla języka Python:

Autoryzowanie dostępu i tworzenie obiektu klienta

Upewnij się, że uwierzytelniasz się przy użyciu tego samego konta Microsoft Entra, do którego przypisano rolę. Uwierzytelnianie można przeprowadzić za pomocą interfejsu wiersza polecenia platformy Azure, programu Visual Studio Code lub programu Azure PowerShell.

Zaloguj się do platformy Azure za pomocą interfejsu wiersza polecenia platformy Azure przy użyciu następującego polecenia:

az login

Po uwierzytelnieniu można utworzyć i autoryzować QueueClient obiekt przy użyciu DefaultAzureCredential, aby uzyskać dostęp do danych kolejki na koncie pamięci. DefaultAzureCredential program automatycznie odnajduje i używa konta, które zostało zalogowane w poprzednim kroku.

Aby autoryzować przy użyciu polecenia DefaultAzureCredential, upewnij się, że dodano pakiet azure-identity zgodnie z opisem w temacie Instalowanie pakietów. Pamiętaj również, aby dodać następującą instrukcję importowania w pliku queues-quickstart.py :

from azure.identity import DefaultAzureCredential

Zdecyduj o nazwie kolejki i utwórz wystąpienie klasy QueueClient, używając DefaultAzureCredential do autoryzacji. Używamy tego obiektu klienta do tworzenia i interakcji z zasobem kolejki w koncie magazynowym.

Ważne

Nazwy kolejek mogą zawierać tylko małe litery, cyfry i łączniki oraz muszą zaczynać się literą lub cyfrą. Przed i za każdym łącznikiem musi znajdować się znak nie będący łącznikiem. Nazwa musi również mieć długość od 3 do 63 znaków. Aby uzyskać więcej informacji na temat nazewnictwa kolejek, odwołaj się do Nazewnictwo kolejek i metadanych.

Dodaj następujący kod wewnątrz bloku try i upewnij się, że zastąpiłeś wartość symbolu zastępczego <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)

Komunikaty w kolejce są przechowywane jako tekst. Jeśli chcesz przechowywać dane binarne, skonfiguruj funkcje kodowania i dekodowania Base64 przed umieszczeniem komunikatu w kolejce.

Funkcje kodowania i dekodowania Base64 można skonfigurować podczas tworzenia obiektu klienta:

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

Utwórz kolejkę

Za pomocą obiektu QueueClient wywołaj metodę create_queue, aby utworzyć kolejkę w koncie magazynowym.

Dodaj ten kod na końcu try bloku:

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

Dodaj komunikaty do kolejki

Poniższy fragment kodu dodaje komunikaty do kolejki, wywołując metodę send_message . Zapisuje również zwrócone QueueMessage z trzeciego send_message wywołania. Element saved_message służy do aktualizowania zawartości komunikatu w dalszej części programu.

Dodaj ten kod na końcu try bloku:

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

Zajrzyj do komunikatów w kolejce

Przejrzyj komunikaty w kolejce, wywołując metodę peek_messages. Ta metoda pobiera jeden lub więcej komunikatów z przodu kolejki, ale nie zmienia widoczności komunikatu.

Dodaj ten kod na końcu try bloku:

    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)

Zaktualizuj komunikat w kolejce

Zaktualizuj zawartość komunikatu, wywołując metodę update_message . Ta metoda może zmienić limit czasu widoczności i zawartości komunikatu. Zawartość komunikatu musi być ciągiem zakodowanym w formacie UTF-8 o rozmiarze do 64 KB. Wraz z nową zawartością należy przekazać wartości z wiadomości, która została zapisana wcześniej w kodzie. Wartości saved_message identyfikują komunikat do zaktualizowania.

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

Pobierz długość kolejki

Możesz uzyskać szacunkową liczbę wiadomości w kolejce.

Metoda get_queue_properties zwraca właściwości kolejki, w tym approximate_message_count.

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

Wynik jest przybliżony, ponieważ komunikaty można dodać lub usunąć po odpowiedzi usługi na żądanie.

Odbieranie komunikatów z kolejki

Wcześniej dodane komunikaty można pobrać, wywołując metodę receive_messages .

Dodaj ten kod na końcu try bloku:

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

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

Podczas wywoływania receive_messages metody można opcjonalnie określić wartość max_messagesparametru , czyli liczbę komunikatów do pobrania z kolejki. Wartość domyślna to 1 komunikat, a maksymalna to 32 komunikaty. Można również określić wartość parametru visibility_timeout, która ukrywa komunikaty przed innymi operacjami w okresie przekroczenia limitu czasu. Wartość domyślna to 30 sekund.

Usuwanie komunikatów z kolejki

Usuń wiadomości z kolejki po ich odebraniu i przetworzeniu. W takim przypadku przetwarzanie po prostu wyświetla komunikat na konsoli.

Aplikacja wstrzymuje się, oczekując na reakcję użytkownika przez wywołanie input, zanim przetworzy i usunie komunikaty. Sprawdź w witrynie Azure Portal , czy zasoby zostały utworzone poprawnie, zanim zostaną usunięte. Wiadomości, które nie zostały wyraźnie usunięte, staną się ponownie widoczne w kolejce, aby można było je przetworzyć.

Dodaj ten kod na końcu try bloku:

    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)

Usuń kolejkę

Poniższy kod czyści zasoby utworzone przez aplikację przez usunięcie kolejki przy użyciu delete_queue metody .

Dodaj ten kod na końcu try bloku i zapisz plik:

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

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

    print("Done")

Uruchamianie kodu

Ta aplikacja tworzy i dodaje trzy komunikaty do kolejki platformy Azure. Kod wyświetla listę komunikatów w kolejce, a następnie pobiera je i usuwa przed usunięciem kolejki.

W oknie konsoli przejdź do katalogu zawierającego plik queues-quickstart.py , a następnie użyj następującego python polecenia, aby uruchomić aplikację.

python queues-quickstart.py

Dane wyjściowe aplikacji są podobne do następującego przykładu:

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

Gdy aplikacja wstrzymuje się przed odebraniem komunikatów, sprawdź konto magazynu w witrynie Azure Portal. Sprawdź, czy komunikaty znajdują się w kolejce.

Naciśnij , Enter aby odbierać i usuwać komunikaty. Po wyświetleniu monitu naciśnij ponownie klawisz Enter, aby usunąć kolejkę i zakończyć demonstrację.

Następne kroki

W tej szybkiej instrukcji nauczyłeś się, jak utworzyć kolejkę i dodać do niej komunikaty za pomocą kodu w języku Python. Następnie nauczyłeś się podglądać, pobierać i usuwać wiadomości. Wreszcie nauczyłeś się, jak usuwać kolejkę komunikatów.

Aby zapoznać się z samouczkami, przykładami, przewodnikami szybkiego startu i inną dokumentacją, odwiedź stronę:

Azure dla deweloperów języka Python

  • Last updated on