Udostępnij za pośrednictwem

Biblioteka klienta kolejki usługi Azure Storage dla języka Python — wersja 12.9.0

  • Artykuł

Azure Queue Storage to usługa do przechowywania dużej liczby komunikatów, do której można uzyskać dostęp z dowolnego miejsca na świecie za pośrednictwem uwierzytelnionego połączenia za pomocą protokołu HTTP lub HTTPS. Pojedynczy komunikat w kolejce może mieć rozmiar do 64 KiB, a kolejka może zawierać miliony komunikatów, maksymalnie do całkowitego limitu pojemności konta magazynu.

Najczęstsze zastosowania usługi Queue Storage obejmują:

  • Tworzenie zaległości pracy do przetwarzania asynchronicznego
  • Przekazywanie komunikatów między różnymi częściami aplikacji rozproszonej

Kod | źródłowyPakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | APIDokumentacja | produktuPróbki

Wprowadzenie

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta kolejki usługi Azure Storage dla języka Python przy użyciu narzędzia pip:

pip install azure-storage-queue

Tworzenie konta magazynu

Jeśli chcesz utworzyć nowe konto magazynu, możesz użyć witryny Azure Portal, Azure PowerShell lub interfejsu wiersza polecenia platformy Azure:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Tworzenie klienta

Biblioteka klienta kolejki usługi Azure Storage dla języka Python umożliwia interakcję z trzema typami zasobów: samym kontem magazynu, kolejkami i komunikatami. Interakcja z tymi zasobami rozpoczyna się od wystąpienia klienta. Aby utworzyć obiekt klienta, potrzebny będzie adres URL punktu końcowego usługi kolejki konta magazynu oraz poświadczenia umożliwiające uzyskanie dostępu do konta magazynu:

from azure.storage.queue import QueueServiceClient

service = QueueServiceClient(account_url="https://<my-storage-account-name>.queue.core.windows.net/", credential=credential)

Szukanie adresu URL konta

Adres URL usługi kolejki konta magazynu można znaleźć za pomocą witryny Azure Portal, Azure PowerShell lub interfejsu wiersza polecenia platformy Azure:

# Get the queue service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.queue"

Typy poświadczeń

Parametr credential może być podany w wielu różnych formularzach, w zależności od typu autoryzacji , której chcesz użyć:

  1. Aby użyć tokenu sygnatury dostępu współdzielonego (SAS), podaj token jako ciąg. Jeśli adres URL konta zawiera token SAS, pomiń parametr poświadczeń. Token sygnatury dostępu współdzielonego można wygenerować w witrynie Azure Portal w obszarze "Sygnatura dostępu współdzielonego" lub użyć jednej z generate_sas() funkcji, aby utworzyć token sas dla konta magazynu lub kolejki:

    from datetime import datetime, timedelta
from azure.storage.queue import QueueServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    start=datetime.utcnow(),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

queue_service_client = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential=sas_token)

  2. Aby użyć klucza współużytkowanego konta magazynu (czyli klucza konta lub klucza dostępu), podaj klucz jako ciąg. Można to znaleźć w witrynie Azure Portal w sekcji "Klucze dostępu" lub uruchamiając następujące polecenie interfejsu wiersza polecenia platformy Azure:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Użyj klucza jako parametru poświadczeń, aby uwierzytelnić klienta:

    from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")

  3. Aby użyć poświadczeń tokenu usługi Azure Active Directory (AAD), podaj wystąpienie żądanego typu poświadczeń uzyskanego z biblioteki azure-identity . Na przykład wartość DefaultAzureCredential może służyć do uwierzytelniania klienta.

    Wymaga to konfiguracji początkowej:

    Użyj zwróconego poświadczenia tokenu, aby uwierzytelnić klienta:

        from azure.identity import DefaultAzureCredential
    from azure.storage.queue import QueueServiceClient
    token_credential = DefaultAzureCredential()

    queue_service_client = QueueServiceClient(
        account_url="https://<my_account_name>.queue.core.windows.net",
        credential=token_credential
    )

Tworzenie klienta na podstawie parametry połączenia

W zależności od przypadku użycia i metody autoryzacji możesz wolisz zainicjować wystąpienie klienta z magazynem parametry połączenia zamiast podać adres URL konta i poświadczenia oddzielnie. W tym celu przekaż parametry połączenia magazynu do metody klasy klientafrom_connection_string:

from azure.storage.queue import QueueServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = QueueServiceClient.from_connection_string(conn_str=connection_string)

Parametry połączenia konta magazynu można znaleźć w witrynie Azure Portal w sekcji "Klucze dostępu" lub uruchamiając następujące polecenie interfejsu wiersza polecenia:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Kluczowe pojęcia

Następujące składniki składają się na usługę Azure Queue Service:

  • Samo konto magazynu
  • Kolejka na koncie magazynu, która zawiera zestaw komunikatów
  • Komunikat w kolejce w dowolnym formacie do 64 KiB

Biblioteka klienta kolejki usługi Azure Storage dla języka Python umożliwia interakcję z każdym z tych składników przy użyciu dedykowanego obiektu klienta.

Klienci asynchroniczny

Ta biblioteka zawiera kompletny interfejs API asynchroniczny obsługiwany w języku Python 3.5 lub nowszym. Aby go użyć, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Aby uzyskać więcej informacji, zobacz dokumentację platformy azure-core .

Klienci asynchroniczny i poświadczenia powinny być zamknięte, gdy nie są już potrzebne. Te obiekty są asynchronicznych menedżerów kontekstów i definiują metody asynchroniczne close .

Klienci

Dwóch różnych klientów jest dostarczanych do interakcji z różnymi składnikami usługi Kolejki:

  1. QueueServiceClient — ten klient reprezentuje interakcję z samym kontem usługi Azure Storage i umożliwia uzyskanie wstępnie skonfigurowanych wystąpień klienta w celu uzyskania dostępu do kolejek w obrębie. Zapewnia operacje pobierania i konfigurowania właściwości konta, a także tworzenia i usuwania kolejek w ramach konta. Aby wykonać operacje w określonej kolejce, pobierz klienta przy użyciu get_queue_client metody .
  2. QueueClient — ten klient reprezentuje interakcję z określoną kolejką (która nie musi jeszcze istnieć). Zapewnia operacje tworzenia, usuwania lub konfigurowania kolejki oraz obejmuje operacje wysyłania, odbierania, podglądu, usuwania i aktualizowania komunikatów w niej.

Komunikaty

  • Send — dodaje komunikat do kolejki i opcjonalnie ustawia limit czasu widoczności komunikatu.
  • Odbierz — pobiera komunikat z kolejki i sprawia, że jest niewidoczny dla innych użytkowników.
  • Podgląd — pobiera komunikat z przodu kolejki bez zmiany widoczności komunikatu.
  • Update — Aktualizacje limit czasu widoczności komunikatu i/lub zawartości wiadomości.
  • Delete — usuwa określony komunikat z kolejki.
  • Clear — czyści wszystkie komunikaty z kolejki.

Przykłady

W poniższych sekcjach przedstawiono kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań kolejki magazynu, w tym:

Tworzenie kolejki

Tworzenie kolejki na koncie magazynu

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.create_queue()

Tworzenie kolejki przy użyciu klienta asynchronicznego

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await queue.create_queue()

Wysyłanie komunikatów

Wysyłanie komunikatów do kolejki

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.send_message("I'm using queues!")
queue.send_message("This is my second message")

Wysyłanie komunikatów asynchronicznie

import asyncio
from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await asyncio.gather(
    queue.send_message("I'm using queues!"),
    queue.send_message("This is my second message")
)

Odbieranie komunikatów

Odbieranie i przetwarzanie komunikatów z kolejki

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

for message in response:
    print(message.content)
    queue.delete_message(message)

# Printed messages from the front of the queue:
# >> I'm using queues!
# >> This is my second message

Odbieranie i przetwarzanie komunikatów w partiach

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages(messages_per_page=10)

for message_batch in response.by_page():
    for message in message_batch:
        print(message.content)
        queue.delete_message(message)

Odbieranie i przetwarzanie komunikatów asynchronicznie

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

async for message in response:
    print(message.content)
    await queue.delete_message(message)

Konfiguracja opcjonalna

Opcjonalne argumenty słów kluczowych, które można przekazać na poziomie klienta i na poziomie operacji.

Konfiguracja zasad ponawiania prób

Użyj następujących argumentów słów kluczowych podczas tworzenia wystąpienia klienta, aby skonfigurować zasady ponawiania prób:

  • retry_total (int): całkowita liczba ponownych prób do zezwolenia. Ma pierwszeństwo przed innymi liczbami. Przekaż polecenie , retry_total=0 jeśli nie chcesz ponowić próby na żądaniach. Wartość domyślna to 10.
  • retry_connect (int): ile błędów związanych z połączeniem należy ponowić próbę. Wartość domyślna to 3.
  • retry_read (int): ile razy należy ponowić próbę w przypadku błędów odczytu. Wartość domyślna to 3.
  • retry_status (int): ile razy należy ponowić próbę w przypadku nieprawidłowych kodów stanu. Wartość domyślna to 3.
  • retry_to_secondary (bool): czy żądanie powinno zostać ponowione do pomocniczej, jeśli jest możliwe. Powinno być włączone tylko konta RA-GRS są używane i potencjalnie nieaktualne dane mogą być obsługiwane. Wartość domyślna to False.

Inna konfiguracja klienta/operacji

Inne opcjonalne argumenty słowa kluczowego konfiguracji, które można określić na kliencie lub na operację.

Argumenty słów kluczowych klienta:

  • connection_timeout (int): liczba sekund oczekiwania klienta na nawiązanie połączenia z serwerem. Wartość domyślna to 20 sekund.
  • read_timeout (int): liczba sekund oczekiwania klienta między kolejnymi operacjami odczytu na odpowiedź z serwera. Jest to limit czasu na poziomie gniazda i nie ma to wpływu na ogólny rozmiar danych. Limity czasu odczytu po stronie klienta zostaną automatycznie ponawiane. Wartość domyślna to 60 sekund.
  • transport (dowolny): transport dostarczony przez użytkownika w celu wysłania żądania HTTP.

Argumenty słów kluczowych dla operacji:

  • raw_response_hook (możliwe do wywołania): podane wywołanie zwrotne używa odpowiedzi zwróconej z usługi.
  • raw_request_hook (z możliwością wywołania): podane wywołanie zwrotne używa żądania przed wysłaniem do usługi.
  • client_request_id (str): opcjonalna identyfikacja żądania przez użytkownika.
  • user_agent (str): dołącza wartość niestandardową do nagłówka user-agent, który ma zostać wysłany wraz z żądaniem.
  • logging_enable (wartość logiczna): włącza rejestrowanie na poziomie DEBUG. Wartość domyślna to False. Można również przekazać na poziomie klienta, aby włączyć je dla wszystkich żądań.
  • logging_body (wartość logiczna): umożliwia rejestrowanie treści żądania i odpowiedzi. Wartość domyślna to False. Można również przekazać na poziomie klienta, aby włączyć je dla wszystkich żądań.
  • nagłówki (dict): przekazuj nagłówki niestandardowe jako pary klucz, wartość. Przykład. headers={'CustomValue': value}

Rozwiązywanie problemów

Ogólne

Klienci kolejki usługi Storage zgłaszają wyjątki zdefiniowane w usłudze Azure Core.

Ta lista może służyć do przywoływania zgłaszanych wyjątków. Aby uzyskać określony kod błędu wyjątku, użyj atrybutu error_code , tj exception.error_code. .

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem logging_enable :

import sys
import logging
from azure.storage.queue import QueueServiceClient

# Create a logger for the 'azure.storage.queue' SDK
logger = logging.getLogger('azure.storage.queue')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = QueueServiceClient.from_connection_string("your_connection_string", logging_enable=True)

logging_enable Podobnie można włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

service_client.get_service_stats(logging_enable=True)

Następne kroki

Więcej przykładów kodu

Rozpocznij pracę z naszymi przykładami kolejek.

Kilka przykładów zestawu SDK dla języka Python kolejek usługi Storage jest dostępnych w repozytorium GitHub zestawu SDK. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy, które często występują podczas pracy z kolejkami magazynu:

  • queue_samples_hello_world.py (wersja asynchronizna) — przykłady znalezione w tym artykule:

    • Tworzenie klienta
    • Tworzenie kolejki
    • Wysyłanie komunikatów
    • Odbieranie komunikatów

  • queue_samples_authentication.py (wersja asynchronicka) — przykłady uwierzytelniania i tworzenia klienta:

    • Z parametry połączenia
    • Z klucza dostępu współdzielonego
    • Z tokenu sygnatury dostępu współdzielonego
    • Z usługi Azure Active Directory

  • queue_samples_service.py (wersja asynchroniowa) — przykłady interakcji z usługą kolejki:

    • Pobieranie i ustawianie właściwości usługi
    • Wyświetlanie listy kolejek na koncie magazynu
    • Tworzenie i usuwanie kolejki z usługi
    • Pobieranie elementu QueueClient

  • queue_samples_message.py (wersja asynchroniowa) — przykłady pracy z kolejkami i komunikatami:

    • Ustawianie zasad dostępu
    • Pobieranie i ustawianie metadanych kolejki
    • Wysyłanie i odbieranie komunikatów
    • Usuń określone komunikaty i wyczyść wszystkie komunikaty
    • Podgląd i aktualizowanie komunikatów

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Azure Queue Storage, zobacz dokumentację usługi Azure Queue Storage dotyczącą docs.microsoft.com.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.