Klientská knihovna Fronty služby Azure Storage pro Python – verze 12.9.0

Článek
12/06/2023

Azure Queue Storage je služba pro ukládání velkého počtu zpráv, ke které můžete získat přístup z jakéhokoli místa na světě prostřednictvím ověřených volání s využitím protokolu HTTP nebo HTTPS. Jedna zpráva ve frontě může mít velikost až 64 KiB a fronta může obsahovat miliony zpráv až do limitu celkové kapacity účtu úložiště.

Toto jsou některá běžná použití úložiště služby Queue Storage:

Vytvoření backlogu práce k asynchronnímu zpracování
Předávání zpráv mezi různými částmi distribuované aplikace

Začínáme

Požadavky

K použití tohoto balíčku se vyžaduje Python 3.7 nebo novější. Další podrobnosti najdete na naší stránce věnované zásadám podpory verzí sady Azure SDK pro Python.
Abyste mohli tento balíček používat, musíte mít předplatné Azure a účet úložiště Azure .

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Storage Queues pro Python pomocí pip:

pip install azure-storage-queue

Vytvoření účtu úložiště

Pokud chcete vytvořit nový účet úložiště, můžete použít Azure Portal, Azure PowerShell nebo Azure CLI:

# 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

Vytvoření klienta

Klientská knihovna Fronty služby Azure Storage pro Python umožňuje interakci se třemi typy prostředků: samotným účtem úložiště, frontami a zprávami. Interakce s těmito prostředky začíná instancí klienta. K vytvoření objektu klienta budete potřebovat adresu URL koncového bodu služby fronty účtu úložiště a přihlašovací údaje, které vám umožní přístup k účtu úložiště:

from azure.storage.queue import QueueServiceClient

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

Vyhledání adresy URL účtu

Adresu URL fronty účtu úložiště můžete najít pomocí webu Azure Portal, Azure PowerShell nebo Azure CLI:

# 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 přihlašovacích údajů

Parametr credential může být k dispozici v různých formách v závislosti na typu autorizace , kterou chcete použít:

Pokud chcete použít token sdíleného přístupového podpisu (SAS), zadejte token jako řetězec. Pokud adresa URL vašeho účtu obsahuje token SAS, vyněžte parametr credential. Token SAS můžete vygenerovat na webu Azure Portal v části Sdílený přístupový podpis nebo můžete použít některou z generate_sas() funkcí k vytvoření tokenu SAS pro účet nebo frontu úložiště:

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)

Pokud chcete použít sdílený klíč účtu úložiště (neboli přístupový klíč účtu), zadejte ho jako řetězec. Najdete ho na webu Azure Portal v části Přístupové klíče nebo spuštěním následujícího příkazu Azure CLI:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

K ověření klienta použijte klíč jako parametr přihlašovacích údajů:
```
from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")
```
Pokud chcete použít přihlašovací údaje tokenu Azure Active Directory (AAD), zadejte instanci požadovaného typu přihlašovacích údajů získané z knihovny azure-identity . Například DefaultAzureCredential se dá použít k ověření klienta.

To vyžaduje určité počáteční nastavení:
- Instalace azure-identity
- Registrace nové aplikace AAD a udělení oprávnění pro přístup k Azure Storage
- Udělení přístupu k datům fronty Azure pomocí RBAC na webu Azure Portal
- Nastavte hodnoty ID klienta, ID tenanta a tajného klíče klienta aplikace AAD jako proměnné prostředí: AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET
K ověření klienta použijte vrácené přihlašovací údaje tokenu:
```
    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
    )
```

Vytvoření klienta ze připojovací řetězec

V závislosti na vašem případu použití a metodě autorizace můžete dát přednost inicializaci instance klienta s připojovací řetězec úložiště místo zadání adresy URL účtu a přihlašovacích údajů zvlášť. Uděláte to tak, že předáte připojovací řetězec úložiště metodě třídy 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)

Připojovací řetězec k účtu úložiště najdete na webu Azure Portal v části Přístupové klíče nebo spuštěním následujícího příkazu rozhraní příkazového řádku:

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

Klíčové koncepty

Službu Azure Queue Service tvoří následující komponenty:

Samotný účet úložiště
Fronta v rámci účtu úložiště, která obsahuje sadu zpráv
Zpráva ve frontě v libovolném formátu až 64 KiB

Klientská knihovna Fronty služby Azure Storage pro Python umožňuje interakci s každou z těchto komponent pomocí vyhrazeného objektu klienta.

Asynchronní klienti

Tato knihovna obsahuje kompletní asynchronní rozhraní API podporované v Pythonu 3.5 nebo novějším. Abyste ho mohli používat, musíte nejdřív nainstalovat asynchronní přenos, například aiohttp. Další informace najdete v dokumentaci k azure-core .

Asynchronní klienti a přihlašovací údaje by se měly zavřít, když už je nepotřebujete. Tyto objekty jsou správci asynchronního kontextu a definují asynchronní close metody.

Klienti

K interakci s různými komponentami frontové služby jsou k dispozici dva různí klienti:

QueueServiceClient – tento klient představuje interakci se samotným účtem úložiště Azure a umožňuje získat předem nakonfigurované instance klientů pro přístup k frontám v rámci. Poskytuje operace pro načtení a konfiguraci vlastností účtu a také výpis, vytvoření a odstranění front v rámci účtu. Pokud chcete provádět operace s konkrétní frontou, načtěte klienta pomocí metody .get_queue_client
QueueClient – tento klient představuje interakci s konkrétní frontou (která ještě nemusí existovat). Poskytuje operace pro vytvoření, odstranění nebo konfiguraci fronty a zahrnuje operace pro odesílání, přijímání, náhled, odstraňování a aktualizaci zpráv v ní.

Zprávy

Odeslat – Přidá zprávu do fronty a volitelně nastaví časový limit viditelnosti zprávy.
Receive – Načte zprávu z fronty a znemožní ji ostatním příjemcům.
Náhled – načte zprávu z přední části fronty beze změny viditelnosti zprávy.
Aktualizace – Aktualizace časový limit viditelnosti zprávy nebo obsahu zprávy.
Odstranit – odstraní zadanou zprávu z fronty.
Vymazat – Vymaže všechny zprávy z fronty.

Příklady

Následující části obsahují několik fragmentů kódu, které pokrývají některé nejběžnější úlohy fronty služby Storage, mezi které patří:

Vytvoření fronty
Odesílání zpráv
Příjem zpráv

Vytvoření fronty

Vytvoření fronty v účtu úložiště

from azure.storage.queue import QueueClient

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

Vytvoření fronty pomocí asynchronního klienta

from azure.storage.queue.aio import QueueClient

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

Odesílání zpráv

Odesílání zpráv do fronty

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

Asynchronní odesílání zpráv

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

Příjem zpráv

Příjem a zpracování zpráv z fronty

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

Příjem a zpracování zpráv v dávkách

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)

Asynchronní příjem a zpracování zpráv

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)

Volitelná konfigurace

Volitelné argumenty klíčových slov, které je možné předat na úrovni klienta a jednotlivých operací.

Konfigurace zásad opakování

Při vytváření instance klienta ke konfiguraci zásad opakování použijte následující argumenty s klíčovými slovy:

retry_total (int): Celkový počet povolených opakování. Má přednost před ostatními počty. retry_total=0 Pokud nechcete opakovat pokusy na žádostech, předejte je. Výchozí hodnota je 10.
retry_connect (int): Kolik chyb souvisejících s připojením se má opakovat. Výchozí hodnota je 3.
retry_read (int): Kolikrát se má opakovat při čtení chyb. Výchozí hodnota je 3.
retry_status (int): Kolikrát se má opakovat chybný stavový kód. Výchozí hodnota je 3.
retry_to_secondary (bool): Určuje, jestli se má požadavek opakovat do sekundárního systému, pokud je to možné. Tato možnost by měla být povolená jenom u účtů RA-GRS a je možné zpracovávat potenciálně zastaralá data. Výchozí hodnota je False.

Konfigurace jiného klienta nebo operace

Další volitelné argumenty klíčového slova konfigurace, které lze zadat v klientovi nebo pro každou operaci.

Argumenty klíčových slov klienta:

connection_timeout (int): Počet sekund, po které bude klient čekat na navázání připojení k serveru. Výchozí hodnota je 20 sekund.
read_timeout (int): Počet sekund, po které bude klient čekat mezi po sobě jdoucími operacemi čtení na odpověď ze serveru. Jedná se o časový limit na úrovni soketů, který nemá vliv na celkovou velikost dat. Automaticky se budou opakovat časové limity čtení na straně klienta. Výchozí hodnota je 60 sekund.
transport (Any): Přenos poskytnutý uživatelem k odeslání požadavku HTTP.

Argumenty klíčových slov pro jednotlivé operace:

raw_response_hook (volatelné): Dané zpětné volání použije odpověď vrácenou službou.
raw_request_hook (volatelné): Dané zpětné volání použije požadavek před odesláním do služby.
client_request_id (str): Nepovinný uživatel zadal identifikaci požadavku.
user_agent (str): Připojí vlastní hodnotu k hlavičce uživatelského agenta, která se má odeslat spolu s požadavkem.
logging_enable (bool): Povolí protokolování na úrovni LADĚNÍ. Výchozí hodnota je False. Můžete ho také předat na úrovni klienta, abyste ho povolili pro všechny požadavky.
logging_body (bool): Povolí protokolování textu požadavku a odpovědi. Výchozí hodnota je False. Můžete ho také předat na úrovni klienta, abyste ho povolili pro všechny požadavky.
headers (dict): Předejte vlastní hlavičky jako klíče a páry hodnot. Např. headers={'CustomValue': value}

Řešení potíží

Obecné

Klienti fronty úložiště vyvolávají výjimky definované v Azure Core.

Tento seznam lze použít jako referenci k zachycení vyvolaných výjimek. Pokud chcete získat konkrétní kód chyby výjimky, použijte error_code atribut , exception.error_codetj. .

protokolování

Tato knihovna používá pro protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a nereagovaných hlaviček, je možné povolit na klientovi s 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)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

service_client.get_service_stats(logging_enable=True)

Další kroky

Další ukázkový kód

Začněte s našimi ukázkami front.

Několik ukázek sady Python SDK pro fronty úložiště je k dispozici v úložišti sady SDK Na GitHubu. Tyto ukázky poskytují příklad kódu pro další scénáře, se kterými se při práci s frontami úložiště běžně setkáváme:

queue_samples_hello_world.py (asynchronní verze) – příklady v tomto článku:
- Vytvoření klienta
- Vytvoření fronty
- Odesílání zpráv
- Příjem zpráv
queue_samples_authentication.py (asynchronní verze) – příklady ověřování a vytvoření klienta:
- Z připojovací řetězec
- Ze sdíleného přístupového klíče
- Z tokenu sdíleného přístupového podpisu
- Z Azure Active Directory
queue_samples_service.py (asynchronní verze) – příklady pro interakci se službou queue:
- Získání a nastavení vlastností služby
- Výpis front v účtu úložiště
- Vytvoření a odstranění fronty ze služby
- Získání QueueClient
queue_samples_message.py (asynchronní verze) – příklady pro práci s frontami a zprávami:
- Nastavení zásad přístupu
- Získání a nastavení metadat fronty
- Odesílání a příjem zpráv
- Odstranění zadaných zpráv a vymazání všech zpráv
- Náhled a aktualizační zprávy

Další dokumentace

Rozsáhlejší dokumentaci ke službě Azure Queue Storage najdete v dokumentaci ke službě Azure Queue Storage na docs.microsoft.com.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.

Sdílet prostřednictvím