Azure Storage Queues-clientbibliotheek voor Python - versie 12.9.0

Artikel
12/05/2023

Azure Queue Storage is een service voor de opslag van grote aantallen berichten die via HTTP of HTTPS overal vandaan kunnen worden opgevraagd met geverifieerde aanroepen. Eén wachtrijbericht kan maximaal 64 KiB groot zijn en een wachtrij kan miljoenen berichten bevatten, tot de totale capaciteitslimiet van een opslagaccount.

Veelvoorkomende toepassingen van Queue Storage zijn onder andere:

Het maken van een voorraad werk dat asynchroon moet worden verwerkt
Berichten doorgeven tussen verschillende onderdelen van een gedistribueerde toepassing

Aan de slag

Vereisten

Python 3.7 of hoger is vereist voor het gebruik van dit pakket. Lees onze pagina over ondersteuningsbeleid voor Azure SDK voor Python-versies voor meer informatie.
U moet een Azure-abonnement en een Azure-opslagaccount hebben om dit pakket te kunnen gebruiken.

Het pakket installeren

Installeer de Azure Storage Queues-clientbibliotheek voor Python met pip:

pip install azure-storage-queue

Create a storage account

Als u een nieuw opslagaccount wilt maken, kunt u Azure Portal, Azure PowerShell of Azure CLI gebruiken:

# 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

De client maken

Met de Azure Storage Queues-clientbibliotheek voor Python kunt u werken met drie typen resources: het opslagaccount zelf, wachtrijen en berichten. Interactie met deze resources begint met een exemplaar van een client. Als u een clientobject wilt maken, hebt u de service-eindpunt-URL voor de wachtrij van het opslagaccount en een referentie nodig waarmee u toegang hebt tot het opslagaccount:

from azure.storage.queue import QueueServiceClient

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

De account-URL opzoeken

U kunt de SERVICE-URL voor de wachtrij van het opslagaccount vinden met behulp van de Azure-portal, Azure PowerShell of 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"

Typen referenties

De credential parameter kan in verschillende vormen worden opgegeven, afhankelijk van het type autorisatie dat u wilt gebruiken:

Als u een SAS-token (Shared Access Signature) wilt gebruiken, geeft u het token op als een tekenreeks. Als uw account-URL het SAS-token bevat, laat u de referentieparameter weg. U kunt een SAS-token genereren vanuit de Azure-portal onder Shared Access Signature of een van de generate_sas() functies gebruiken om een SAS-token te maken voor het opslagaccount of de wachtrij:

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)

Als u een gedeelde sleutel voor een opslagaccount (ook wel accountsleutel of toegangssleutel genoemd) wilt gebruiken, geeft u de sleutel op als een tekenreeks. U kunt dit vinden in Azure Portal onder de sectie Toegangssleutels of door de volgende Azure CLI-opdracht uit te voeren:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Gebruik de sleutel als referentieparameter om de client te verifiëren:
```
from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")
```
Als u een AAD-tokenreferentie (Azure Active Directory) wilt gebruiken, geeft u een exemplaar op van het gewenste referentietype dat is verkregen uit de azure-identity-bibliotheek . DefaultAzureCredential kan bijvoorbeeld worden gebruikt om de client te verifiëren.

Hiervoor is enige initiële installatie vereist:
- Azure-identity installeren
- Een nieuwe AAD-toepassing registreren en machtigingen verlenen voor toegang tot Azure Storage
- Toegang verlenen tot Azure Queue-gegevens met RBAC in Azure Portal
- Stel de waarden van de client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET
Gebruik de geretourneerde tokenreferentie om de client te verifiëren:
```
    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
    )
```

De client maken op basis van een verbindingsreeks

Afhankelijk van uw gebruiksscenario en autorisatiemethode, kunt u er de voorkeur aan geven om een clientexemplaren te initialiseren met een opslag-verbindingsreeks in plaats van de account-URL en referenties afzonderlijk op te geven. U doet dit door de opslag-verbindingsreeks door te geven aan de klassemethode van from_connection_string de client:

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)

De verbindingsreeks voor uw opslagaccount vindt u in Azure Portal onder de sectie Toegangssleutels of door de volgende CLI-opdracht uit te voeren:

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

Belangrijkste concepten

De Azure Queue Service bestaat uit de volgende onderdelen:

Het opslagaccount zelf
Een wachtrij in het opslagaccount, die een set berichten bevat
Een bericht in een wachtrij, in elke indeling, van maximaal 64 KiB

Met de Azure Storage Queues-clientbibliotheek voor Python kunt u met elk van deze onderdelen communiceren via het gebruik van een toegewezen clientobject.

Asynchrone clients

Deze bibliotheek bevat een volledige asynchrone API die wordt ondersteund in Python 3.5+. Als u deze wilt gebruiken, moet u eerst een asynchroon transport installeren, zoals aiohttp. Zie azure-core-documentatie voor meer informatie.

Asynchrone clients en referenties moeten worden gesloten wanneer ze niet meer nodig zijn. Deze objecten zijn asynchrone contextbeheerders en definiëren asynchrone close methoden.

Clients

Er zijn twee verschillende clients beschikbaar om te communiceren met de verschillende onderdelen van de Queue Service:

QueueServiceClient : deze client vertegenwoordigt interactie met het Azure-opslagaccount zelf en stelt u in staat om vooraf geconfigureerde clientexemplaren te verkrijgen voor toegang tot de wachtrijen binnen. Het biedt bewerkingen voor het ophalen en configureren van de accounteigenschappen, evenals het weergeven, maken en verwijderen van wachtrijen binnen het account. Als u bewerkingen wilt uitvoeren op een specifieke wachtrij, haalt u een client op met behulp van de get_queue_client methode .
QueueClient : deze client vertegenwoordigt interactie met een specifieke wachtrij (die nog niet hoeft te bestaan). Het biedt bewerkingen voor het maken, verwijderen of configureren van een wachtrij en bevat bewerkingen voor het verzenden, ontvangen, bekijken, verwijderen en bijwerken van berichten in de wachtrij.

Berichten

Verzenden : voegt een bericht toe aan de wachtrij en stelt desgewenst een zichtbaarheidstime-out in voor het bericht.
Ontvangen : haalt een bericht op uit de wachtrij en maakt het onzichtbaar voor andere gebruikers.
Kort weergeven: haalt een bericht op van de voorkant van de wachtrij, zonder de zichtbaarheid van het bericht te wijzigen.
Bijwerken: Updates de zichtbaarheidstime-out van een bericht en/of de berichtinhoud.
Verwijderen : hiermee verwijdert u een opgegeven bericht uit de wachtrij.
Wissen : hiermee wist u alle berichten uit de wachtrij.

Voorbeelden

De volgende secties bevatten verschillende codefragmenten voor enkele van de meest voorkomende opslagwachtrijtaken, waaronder:

Een wachtrij maken
Berichten verzenden
Berichten ontvangen

Een wachtrij maken

Een wachtrij maken in uw opslagaccount

from azure.storage.queue import QueueClient

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

De asynchrone client gebruiken om een wachtrij te maken

from azure.storage.queue.aio import QueueClient

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

Berichten verzenden

Berichten verzenden naar uw wachtrij

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

Berichten asynchroon verzenden

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

Berichten ontvangen

Berichten van uw wachtrij ontvangen en verwerken

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

Berichten in batches ontvangen en verwerken

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)

Berichten asynchroon ontvangen en verwerken

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)

Optionele configuratie

Optionele trefwoordargumenten die kunnen worden doorgegeven op het niveau van de client en per bewerking.

Configuratie van beleid voor opnieuw proberen

Gebruik de volgende trefwoordargumenten bij het instantiëren van een client om het beleid voor opnieuw proberen te configureren:

retry_total (int): het totale aantal nieuwe pogingen dat moet worden toegestaan. Heeft voorrang op andere aantallen. Geef door retry_total=0 als u aanvragen niet opnieuw wilt proberen. De standaardwaarde is 10.
retry_connect (int): hoeveel verbindingsfouten u opnieuw wilt proberen. Standaardwaarde is 3.
retry_read (int): hoe vaak moet u het opnieuw proberen bij leesfouten. Standaardwaarde is 3.
retry_status (int): hoe vaak moet u ongeldige statuscodes opnieuw proberen. Standaardwaarde is 3.
retry_to_secondary (bool): of de aanvraag opnieuw moet worden geprobeerd naar secundaire, indien mogelijk. Dit mag alleen worden ingeschakeld wanneer RA-GRS-accounts worden gebruikt en mogelijk verouderde gegevens kunnen worden verwerkt. De standaardwaarde is False.

Andere client/configuratie per bewerking

Andere optionele configuratiezoekwoordargumenten die kunnen worden opgegeven op de client of per bewerking.

Trefwoordargumenten voor client:

connection_timeout (int): het aantal seconden dat de client wacht om verbinding te maken met de server. De standaardwaarde is 20 seconden.
read_timeout (int): het aantal seconden dat de client tussen opeenvolgende leesbewerkingen wacht op een antwoord van de server. Dit is een time-out op socketniveau en wordt niet beïnvloed door de totale gegevensgrootte. Time-outs aan de clientzijde worden automatisch opnieuw geprobeerd. De standaardwaarde is 60 seconden.
transport (Any): door de gebruiker opgegeven transport om de HTTP-aanvraag te verzenden.

Trefwoordargumenten per bewerking:

raw_response_hook (aanroepbaar): de opgegeven callback gebruikt het antwoord dat is geretourneerd door de service.
raw_request_hook (aanroepbaar): de opgegeven callback gebruikt de aanvraag voordat deze naar de service wordt verzonden.
client_request_id (str): optionele door de gebruiker opgegeven identificatie van de aanvraag.
user_agent (str): voegt de aangepaste waarde toe aan de header user-agent die samen met de aanvraag moet worden verzonden.
logging_enable (bool): hiermee schakelt u logboekregistratie in op het niveau VAN FOUTOPSPORING. Standaard ingesteld op False. Kan ook worden doorgegeven op clientniveau om het voor alle aanvragen in te schakelen.
logging_body (bool): hiermee schakelt u logboekregistratie van de aanvraag- en antwoordtekst in. Standaard ingesteld op False. Kan ook worden doorgegeven op clientniveau om het voor alle aanvragen in te schakelen.
headers (dict): geef aangepaste headers door als sleutel- en waardeparen. Bijvoorbeeld. headers={'CustomValue': value}

Problemen oplossen

Algemeen

Storage Queue-clients genereren uitzonderingen die zijn gedefinieerd in Azure Core.

Deze lijst kan worden gebruikt ter referentie om opgetreden uitzonderingen te ondervangen. Als u de specifieke foutcode van de uitzondering wilt ophalen, gebruikt u het error_code kenmerk, dat wil doen exception.error_code.

Logboekregistratie

Deze bibliotheek gebruikt de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-geredigeerde headers, kan worden ingeschakeld op een client met het logging_enable argument:

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)

Op dezelfde manier kan logging_enable logboekregistratie voor één bewerking inschakelen, zelfs wanneer dit niet is ingeschakeld voor de client:

service_client.get_service_stats(logging_enable=True)

Volgende stappen

Meer voorbeeldcode

Ga aan de slag met onze wachtrijvoorbeelden.

Er zijn verschillende Python SDK-voorbeelden voor Storage Queues beschikbaar in de GitHub-opslagplaats van de SDK. Deze voorbeelden bevatten voorbeeldcode voor aanvullende scenario's die vaak voorkomen tijdens het werken met Opslagwachtrijen:

queue_samples_hello_world.py (asynchrone versie): voorbeelden in dit artikel:
- Client maken
- Een wachtrij maken
- Berichten verzenden
- Berichten ontvangen
queue_samples_authentication.py (asynchrone versie): voorbeelden voor het verifiëren en maken van de client:
- Vanuit een verbindingsreeks
- Vanuit een gedeelde toegangssleutel
- Vanuit een Shared Access Signature-token
- Vanuit Azure Active Directory
queue_samples_service.py (asynchrone versie): voorbeelden voor interactie met de wachtrijservice:
- Service-eigenschappen ophalen en instellen
- Wachtrijen in een opslagaccount weergeven
- Een wachtrij maken en verwijderen uit de service
- De QueueClient ophalen
queue_samples_message.py (asynchrone versie): voorbeelden voor het werken met wachtrijen en berichten:
- Een toegangsbeleid instellen
- Metagegevens van wachtrij ophalen en instellen
- Berichten verzenden en ontvangen
- Opgegeven berichten verwijderen en alle berichten wissen
- berichten Kort weergeven en bijwerken

Aanvullende documentatie

Zie de Documentatie over Azure Queue Storage over docs.microsoft.com voor uitgebreidere documentatie over Azure Queue Storage .

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Delen via