Bibliothèque cliente Files d’attente de stockage Azure pour Python - version 12.9.0

Article
12/05/2023

Les files d’attente de stockage Azure sont un service permettant de stocker un grand nombre de messages accessibles depuis n’importe où dans le monde via des appels authentifiés avec HTTP ou HTTPS. Un message de file d’attente unique peut atteindre 64 Kio et une file d’attente peut contenir des millions de messages, jusqu’à la limite de capacité totale d’un compte de stockage.

Voici quelques utilisations courantes des files d’attente de stockage :

Création d'un journal des travaux en souffrance de travail à traiter de manière asynchrone
Passage de messages entre différentes parties d’une application distribuée

Prise en main

Prérequis

Python 3.7 ou version ultérieure est requis pour utiliser ce package. Pour plus d’informations, consultez notre page sur la stratégie de prise en charge des versions du Kit de développement logiciel (SDK) Azure pour Python.
Vous devez disposer d’un abonnement Azure et d’un compte de stockage Azure pour utiliser ce package.

Installer le package

Installez la bibliothèque cliente Files d’attente de stockage Azure pour Python avec pip :

pip install azure-storage-queue

Créez un compte de stockage.

Si vous souhaitez créer un compte de stockage, vous pouvez utiliser le portail Azure, Azure PowerShell ou 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

Création du client

La bibliothèque cliente Files d’attente de stockage Azure pour Python vous permet d’interagir avec trois types de ressources : le compte de stockage lui-même, les files d’attente et les messages. L’interaction avec ces ressources commence par une instance d’un client. Pour créer un objet client, vous aurez besoin de l’URL du point de terminaison de service de file d’attente du compte de stockage et d’informations d’identification qui vous permettent d’accéder au compte de stockage :

from azure.storage.queue import QueueServiceClient

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

Recherche de l’URL du compte

Vous trouverez l’URL du service de file d’attente du compte de stockage à l’aide du portail Azure, de Azure PowerShell ou d’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"

Types d’informations d’identification

Le credential paramètre peut être fourni sous plusieurs formes différentes, selon le type d’autorisation que vous souhaitez utiliser :

Pour utiliser un jeton de signature d’accès partagé (SAP), fournissez le jeton sous forme de chaîne. Si l’URL de votre compte inclut le jeton SAS, omettez le paramètre des informations d’identification. Vous pouvez générer un jeton SAP à partir du portail Azure sous « Signature d’accès partagé » ou utiliser l’une generate_sas() des fonctions pour créer un jeton SAP pour le compte de stockage ou la file d’attente :

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)

Pour utiliser une clé partagée de compte de stockage (également appelée clé de compte ou clé d’accès), fournissez la clé sous forme de chaîne. Vous pouvez le trouver dans le portail Azure sous la section « Clés d’accès » ou en exécutant la commande Azure CLI suivante :

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Utilisez la clé comme paramètre d’informations d’identification pour authentifier le client :
```
from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")
```
Pour utiliser des informations d’identification de jeton Azure Active Directory (AAD), fournissez une instance du type d’informations d’identification souhaité obtenu à partir de la bibliothèque d’identité Azure. Par exemple, DefaultAzureCredential peut être utilisé pour authentifier le client.

Cela nécessite une configuration initiale :
- Installer azure-identity
- Inscrire une nouvelle application AAD et accorder des autorisations d’accès au Stockage Azure
- Accorder l’accès aux données de file d’attente Azure avec RBAC dans le portail Azure
- Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
Utilisez les informations d’identification de jeton retournées pour authentifier le client :
```
    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
    )
```

Création du client à partir d’un chaîne de connexion

En fonction de votre cas d’usage et de votre méthode d’autorisation, vous préférerez peut-être initialiser un instance client avec un chaîne de connexion de stockage au lieu de fournir l’URL et les informations d’identification du compte séparément. Pour ce faire, transmettez le chaîne de connexion de stockage à la méthode de classe du from_connection_string 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)

La chaîne de connexion à votre compte de stockage se trouve dans le Portail Azure sous la section « Clés d’accès » ou en exécutant la commande CLI suivante :

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

Concepts clés

Les composants suivants composent le service de file d’attente Azure :

Le compte de stockage lui-même
File d’attente dans le compte de stockage, qui contient un ensemble de messages
Un message dans une file d’attente, dans n’importe quel format, de 64 Kio maximum

La bibliothèque cliente Files d’attente de stockage Azure pour Python vous permet d’interagir avec chacun de ces composants via l’utilisation d’un objet client dédié.

Clients asynchrones

Cette bibliothèque inclut une API asynchrone complète prise en charge sur Python 3.5+. Pour l’utiliser, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Pour plus d’informations, consultez la documentation azure-core .

Les clients et les informations d’identification asynchrones doivent être fermés lorsqu’ils ne sont plus nécessaires. Ces objets sont des gestionnaires de contexte asynchrones et définissent des méthodes asynchrones close .

Clients

Deux clients différents sont fournis pour interagir avec les différents composants du service de file d’attente :

QueueServiceClient : ce client représente l’interaction avec le compte de stockage Azure lui-même et vous permet d’acquérir des instances clientes préconfigurées pour accéder aux files d’attente dans. Il fournit des opérations pour récupérer et configurer les propriétés du compte, ainsi que répertorier, créer et supprimer des files d’attente dans le compte. Pour effectuer des opérations sur une file d’attente spécifique, récupérez un client à l’aide de la get_queue_client méthode .
QueueClient : ce client représente l’interaction avec une file d’attente spécifique (qui n’a pas besoin d’exister encore). Il fournit des opérations pour créer, supprimer ou configurer une file d’attente et inclut des opérations d’envoi, de réception, d’aperçu, de suppression et de mise à jour de messages.

Messages

Envoyer : ajoute un message à la file d’attente et définit éventuellement un délai de visibilité pour le message.
Réception : récupère un message de la file d’attente et le rend invisible pour les autres consommateurs.
Aperçu : récupère un message à l’avant de la file d’attente, sans modifier la visibilité du message.
Mise à jour : Mises à jour le délai de visibilité d’un message et/ou son contenu.
Supprimer : supprime un message spécifié de la file d’attente.
Effacer : efface tous les messages de la file d’attente.

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches de file d’attente de stockage les plus courantes, notamment :

Création d’une file d’attente
Envoi de messages
Réception de messages

Création d’une file d’attente

Créer une file d’attente dans votre compte de stockage

from azure.storage.queue import QueueClient

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

Utiliser le client asynchrone pour créer une file d’attente

from azure.storage.queue.aio import QueueClient

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

Envoi de messages

Envoyer des messages à votre file d’attente

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

Envoyer des messages de manière asynchrone

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

Réception de messages

Recevoir et traiter des messages à partir de votre file d’attente

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

Recevoir et traiter des messages par lots

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)

Recevoir et traiter des messages de manière asynchrone

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)

Configuration facultative

Facultatif mot clé arguments qui peuvent être transmis au niveau du client et par opération.

Configuration de la stratégie de nouvelle tentative

Utilisez les arguments mot clé suivants lors de l’instanciation d’un client pour configurer la stratégie de nouvelle tentative :

retry_total (int) : nombre total de nouvelles tentatives à autoriser. Est prioritaire sur d’autres nombres. Transmettez retry_total=0 si vous ne souhaitez pas réessayer sur les demandes. La valeur par défaut est 10.
retry_connect (int) : nombre d’erreurs liées à la connexion à retenter. La valeur par défaut est 3.
retry_read (int) : nombre de nouvelles tentatives en cas d’erreurs de lecture. La valeur par défaut est 3.
retry_status (int) : nombre de nouvelles tentatives sur des codes de status incorrects. La valeur par défaut est 3.
retry_to_secondary (bool) : indique si la demande doit être retentée au niveau secondaire, si possible. Cela ne doit être activé que si les comptes RA-GRS sont utilisés et que les données potentiellement obsolètes peuvent être gérées. La valeur par défaut est False.

Autre configuration client/ par opération

D’autres configurations facultatives mot clé arguments qui peuvent être spécifiés sur le client ou par opération.

Arguments de mot clé client :

connection_timeout (int) : nombre de secondes pendant lesquelles le client attend pour établir une connexion au serveur. La valeur par défaut est de 20 secondes.
read_timeout (int) : nombre de secondes pendant lesquelles le client attend une réponse du serveur entre les opérations de lecture consécutives. Il s’agit d’un délai d’attente au niveau du socket qui n’est pas affecté par la taille globale des données. Les délais de lecture côté client sont automatiquement retentés. La valeur par défaut est de 60 secondes.
transport (Any) : transport fourni par l’utilisateur pour envoyer la requête HTTP.

Arguments de mot clé par opération :

raw_response_hook (appelable) : le rappel donné utilise la réponse retournée par le service.
raw_request_hook (appelable) : le rappel donné utilise la requête avant d’être envoyé au service.
client_request_id (str) : identification facultative spécifiée par l’utilisateur de la demande.
user_agent (str) : ajoute la valeur personnalisée à l’en-tête user-agent à envoyer avec la demande.
logging_enable (bool) : active la journalisation au niveau DEBUG. Valeur par défaut False. Peut également être transmis au niveau du client pour l’activer pour toutes les demandes.
logging_body (bool) : active la journalisation du corps de la requête et de la réponse. Valeur par défaut False. Peut également être transmis au niveau du client pour l’activer pour toutes les demandes.
en-têtes (dict) : passez des en-têtes personnalisés en tant que paires de clés et de valeurs. Par exemple, headers={'CustomValue': value}

Dépannage

Général

Les clients file d’attente de stockage déclenchent des exceptions définies dans Azure Core.

Cette liste peut être utilisée à des fins de référence pour intercepter les exceptions levées. Pour obtenir le code d’erreur spécifique de l’exception, utilisez l’attribut error_code , exception.error_codec’est-à-dire .

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument 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)

De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :

service_client.get_service_stats(logging_enable=True)

Étapes suivantes

Autres exemples de code

Prise en main de nos exemples de file d’attente.

Plusieurs exemples de sdk Python de files d’attente de stockage sont disponibles dans le référentiel GitHub du SDK. Ces exemples fournissent un exemple de code pour des scénarios supplémentaires couramment rencontrés lors de l’utilisation des files d’attente de stockage :

queue_samples_hello_world.py (version asynchrone) - Exemples trouvés dans cet article :
- Création de client
- Créer une file d’attente
- Envoyer des messages
- Recevoir des messages
queue_samples_authentication.py (version asynchrone) : exemples d’authentification et de création du client :
- À partir d’un chaîne de connexion
- À partir d’une clé d’accès partagé
- À partir d’un jeton de signature d’accès partagé
- À partir d’Azure Active Directory
queue_samples_service.py (version asynchrone) : exemples d’interaction avec le service de file d’attente :
- Obtenir et définir des propriétés de service
- Répertorier les files d’attente dans un compte de stockage
- Créer et supprimer une file d’attente du service
- Obtenir file d’attenteClient
queue_samples_message.py (version asynchrone) - Exemples d’utilisation des files d’attente et des messages :
- Définir une stratégie d’accès
- Obtenir et définir des métadonnées de file d’attente
- Envoyer et recevoir des messages
- Supprimer les messages spécifiés et effacer tous les messages
- Aperçu et mettre à jour les messages

Documentation complémentaire

Pour obtenir une documentation plus complète sur le stockage File d’attente Azure, consultez la documentation stockage File d’attente Azure sur docs.microsoft.com.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.