Azure Storage Queues-klientbibliotek för Python – version 12.9.0

  • Artikel

Azure Queue Storage är en tjänst för att lagra stora mängder meddelanden som kan nås från var som helst i världen via autentiserade anrop med HTTP eller HTTPS. Ett meddelande i en kö kan vara upp till 64 KiB stort och en kö kan innehålla miljontals meddelanden, upp till den totala kapacitetsgränsen för ett lagringskonto.

Vanliga användningsområden för Queue Storage är:

  • Skapa en lista med kvarvarande uppgifter att bearbeta asynkront
  • Skicka meddelanden mellan olika delar av ett distribuerat program

Källkod | Paket (PyPI) | Paket (Conda) | API-referensdokumentation | Produktdokumentation | Prover

Komma igång

Förutsättningar

Installera paketet

Installera Azure Storage Queues-klientbiblioteket för Python med pip:

pip install azure-storage-queue

Skapa ett lagringskonto

Om du vill skapa ett nytt lagringskonto kan du använda Azure Portal, Azure PowerShell eller 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

Skapa klienten

Med Azure Storage Queues-klientbiblioteket för Python kan du interagera med tre typer av resurser: själva lagringskontot, köer och meddelanden. Interaktionen med dessa resurser börjar med en instans av en klient. För att skapa ett klientobjekt behöver du lagringskontots kötjänstslutpunkts-URL och en autentiseringsuppgift som gör att du kan komma åt lagringskontot:

from azure.storage.queue import QueueServiceClient

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

Leta upp konto-URL:en

Du hittar lagringskontots kötjänst-URL med hjälp av Azure-portalen, Azure PowerShell eller 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"

Typer av autentiseringsuppgifter

Parametern credential kan anges i ett antal olika formulär, beroende på vilken typ av auktorisering du vill använda:

  1. Om du vill använda en SAS-token (signatur för delad åtkomst) anger du token som en sträng. Om din konto-URL innehåller SAS-token utelämnar du parametern för autentiseringsuppgifter. Du kan generera en SAS-token från Azure-portalen under "Signatur för delad åtkomst" eller använda någon av generate_sas() funktionerna för att skapa en sas-token för lagringskontot eller kön:

    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. Om du vill använda en delad nyckel för lagringskontot (även kallad kontonyckel eller åtkomstnyckel) anger du nyckeln som en sträng. Detta finns i Azure-portalen under avsnittet "Åtkomstnycklar" eller genom att köra följande Azure CLI-kommando:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Använd nyckeln som parameter för autentiseringsuppgifter för att autentisera klienten:

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

  3. Om du vill använda en AAD-tokenautentisering (Azure Active Directory) anger du en instans av önskad typ av autentiseringsuppgifter som hämtats från azure-identity-biblioteket . StandardAzureCredential kan till exempel användas för att autentisera klienten.

    Detta kräver en viss inledande konfiguration:

    Använd den returnerade tokenautentiseringsuppgiften för att autentisera klienten:

        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
    )

Skapa klienten från en anslutningssträng

Beroende på användningsfall och auktoriseringsmetod kanske du föredrar att initiera en klientinstans med en lagrings-anslutningssträng i stället för att ange kontots URL och autentiseringsuppgifter separat. Det gör du genom att skicka lagrings-anslutningssträng till klientens from_connection_string klassmetod:

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)

Anslutningssträng till ditt lagringskonto finns i Azure-portalen under avsnittet "Åtkomstnycklar" eller genom att köra följande CLI-kommando:

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

Viktiga begrepp

Följande komponenter utgör Azure Queue Service:

  • Själva lagringskontot
  • En kö i lagringskontot som innehåller en uppsättning meddelanden
  • Ett meddelande i en kö, i valfritt format, på upp till 64 KiB

Med Azure Storage Queues-klientbiblioteket för Python kan du interagera med var och en av dessa komponenter med hjälp av ett dedikerat klientobjekt.

Async-klienter

Det här biblioteket innehåller ett fullständigt asynkront API som stöds i Python 3.5+. Om du vill använda den måste du först installera en asynkron transport, till exempel aiohttp. Mer information finns i dokumentationen om azure-core .

Asynkrona klienter och autentiseringsuppgifter bör stängas när de inte längre behövs. Dessa objekt är asynkrona kontexthanterare och definierar asynkrona close metoder.

Klienter

Två olika klienter tillhandahålls för att interagera med de olika komponenterna i kötjänsten:

  1. QueueServiceClient – den här klienten representerar interaktion med själva Azure Storage-kontot och gör att du kan hämta förkonfigurerade klientinstanser för åtkomst till köerna i. Den tillhandahåller åtgärder för att hämta och konfigurera kontoegenskaper samt lista, skapa och ta bort köer i kontot. Om du vill utföra åtgärder i en specifik kö hämtar du en klient med hjälp av get_queue_client metoden .
  2. QueueClient – den här klienten representerar interaktion med en specifik kö (som inte behöver finnas ännu). Den tillhandahåller åtgärder för att skapa, ta bort eller konfigurera en kö och innehåller åtgärder för att skicka, ta emot, granska, ta bort och uppdatera meddelanden i den.

Meddelanden

  • Skicka – Lägger till ett meddelande i kön och anger eventuellt en tidsgräns för synlighet för meddelandet.
  • Ta emot – Hämtar ett meddelande från kön och gör det osynligt för andra konsumenter.
  • Peek – Hämtar ett meddelande längst fram i kön, utan att ändra meddelandets synlighet.
  • Update – Uppdateringar synlighetstimeouten för ett meddelande och/eller meddelandets innehåll.
  • Ta bort – Tar bort ett angivet meddelande från kön.
  • Rensa – rensar alla meddelanden från kön.

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste lagringsköuppgifterna, inklusive:

Skapa en kö

Skapa en kö i ditt lagringskonto

from azure.storage.queue import QueueClient

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

Använda async-klienten för att skapa en kö

from azure.storage.queue.aio import QueueClient

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

Skicka meddelanden

Skicka meddelanden till kön

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

Skicka meddelanden asynkront

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

Ta emot meddelanden

Ta emot och bearbeta meddelanden från kön

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

Ta emot och bearbeta meddelanden i batchar

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)

Ta emot och bearbeta meddelanden asynkront

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)

Valfri konfiguration

Valfria nyckelordsargument som kan skickas på klient- och åtgärdsnivå.

Konfiguration av återförsöksprincip

Använd följande nyckelordsargument när du instansierar en klient för att konfigurera återförsöksprincipen:

  • retry_total (int): Totalt antal återförsök att tillåta. Har företräde framför andra antal. Skicka in retry_total=0 om du inte vill försöka igen på begäranden. Standardvärdet är 10.
  • retry_connect (int): Hur många anslutningsrelaterade fel som ska försöka igen. Standardvärdet är 3.
  • retry_read (int): Hur många gånger läsfel ska försöka igen. Standardvärdet är 3.
  • retry_status (int): Hur många gånger du försöker igen med felaktiga statuskoder. Standardvärdet är 3.
  • retry_to_secondary (bool): Om begäran ska prövas på nytt till sekundär, om det går. Detta bör endast aktiveras för RA-GRS-konton som används och potentiellt inaktuella data kan hanteras. Standardvärdet är False.

Annan klient/per åtgärd-konfiguration

Andra valfria nyckelordsargument för konfiguration som kan anges för klienten eller per åtgärd.

Argument för klientnyckelord:

  • connection_timeout (int): Antalet sekunder som klienten väntar på att upprätta en anslutning till servern. Standardvärdet är 20 sekunder.
  • read_timeout (int): Antalet sekunder som klienten väntar, mellan efterföljande läsåtgärder, på ett svar från servern. Det här är en tidsgräns på socketnivå och påverkas inte av den totala datastorleken. Tidsgränser för läsning på klientsidan görs automatiskt på nytt. Standardvärdet är 60 sekunder.
  • transport (alla): Transport som tillhandahålls av användaren för att skicka HTTP-begäran.

Nyckelordsargument per åtgärd:

  • raw_response_hook (anropsbar): Det angivna återanropet använder svaret som returneras från tjänsten.
  • raw_request_hook (anropsbar): Den angivna motringningen använder begäran innan den skickas till tjänsten.
  • client_request_id (str): Valfri användare har angett identifiering av begäran.
  • user_agent (str): Lägger till det anpassade värdet i användaragenthuvudet som ska skickas med begäran.
  • logging_enable (bool): Aktiverar loggning på felsökningsnivå. Standardvärdet är Falskt. Kan också skickas in på klientnivå för att aktivera den för alla begäranden.
  • logging_body (bool): Aktiverar loggning av begäran och svarstext. Standardvärdet är Falskt. Kan också skickas in på klientnivå för att aktivera den för alla begäranden.
  • headers (dict): Skicka in anpassade rubriker som nyckel, värdepar. E.g. headers={'CustomValue': value}

Felsökning

Allmänt

Lagringsköklienter genererar undantag som definierats i Azure Core.

Den här listan kan användas som referens för att fånga undantag som genereras. Om du vill hämta den specifika felkoden för undantaget använder du error_code attributet, t.ex. exception.error_code.

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med logging_enable argumentet :

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 På samma sätt kan du aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

service_client.get_service_stats(logging_enable=True)

Nästa steg

Mer exempelkod

Kom igång med våra köexempel.

Flera Python SDK-exempel för lagringsköer är tillgängliga för dig på SDK:s GitHub-lagringsplats. De här exemplen innehåller exempelkod för ytterligare scenarier som ofta påträffas när du arbetar med lagringsköer:

  • queue_samples_hello_world.py (async version) – Exempel som finns i den här artikeln:

    • Skapa klient
    • Skapa en kö
    • Skicka meddelanden
    • Ta emot meddelanden

  • queue_samples_authentication.py (asynkron version) – Exempel för att autentisera och skapa klienten:

    • Från en anslutningssträng
    • Från en delad åtkomstnyckel
    • Från en signaturtoken för delad åtkomst
    • Från Azure Active Directory

  • queue_samples_service.py (asynkron version) – Exempel för att interagera med kötjänsten:

    • Hämta och ange tjänstegenskaper
    • Lista köer i ett lagringskonto
    • Skapa och ta bort en kö från tjänsten
    • Hämta QueueClient

  • queue_samples_message.py (async version) – Exempel för att arbeta med köer och meddelanden:

    • Ange en åtkomstprincip
    • Hämta och ange kömetadata
    • Skicka och ta emot meddelanden
    • Ta bort angivna meddelanden och rensa alla meddelanden
    • Peek och uppdatera meddelanden

Ytterligare dokumentation

Mer omfattande dokumentation om Azure Queue Storage finns i Azure Queue Storage-dokumentationen om docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.