Partager via

QueueServiceClient Classe

  • Référence

Client pour interagir avec le service de file d’attente au niveau du compte.

Ce client 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 les opérations relatives à une file d’attente spécifique, un client pour cette entité peut être récupéré à l’aide de la get_queue_client fonction .

Héritage
azure.storage.queue._shared.base_client_async.AsyncStorageAccountHostsMixin
QueueServiceClient
azure.storage.queue._shared.base_client.StorageAccountHostsMixin
QueueServiceClient
azure.storage.queue._encryption.StorageEncryptionMixin
QueueServiceClient

Constructeur

QueueServiceClient(account_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | AsyncTokenCredential | None = None, **kwargs: Any)

Paramètres

account_url
str
Obligatoire

URL du point de terminaison du service de file d’attente. Toutes les autres entités incluses dans le chemin d’URL (par exemple, file d’attente) sont ignorées. Cette URL peut éventuellement être authentifiée avec un jeton SAS.

credential
valeur par défaut: None

Informations d’identification avec lesquelles s’authentifier. Cela est facultatif si l’URL du compte a déjà un jeton SAS. La valeur peut être une chaîne de jeton SAS, une instance d’azureSasCredential ou AzureNamedKeyCredential à partir d’azure.core.credentials, une clé d’accès partagé de compte ou une instance d’une classe TokenCredentials à partir d’azure.identity. Si l’URI de ressource contient déjà un jeton SAS, celui-ci est ignoré au profit d’informations d’identification explicites.

  • sauf dans le cas d’AzureSasCredential, où les jetons SAP en conflit déclenchent un ValueError. Si vous utilisez une instance d’AzureNamedKeyCredential, « name » doit être le nom du compte de stockage et « key » doit être la clé de compte de stockage.
api_version
str

Version de l’API de stockage à utiliser pour les requêtes. La valeur par défaut est la version de service la plus récente compatible avec le KIT de développement logiciel (SDK) actuel. La définition d’une version antérieure peut réduire la compatibilité des fonctionnalités.

secondary_hostname
str

Nom d’hôte du point de terminaison secondaire.

audience
str

Audience à utiliser lors de la demande de jetons pour l’authentification Azure Active Directory. A un effet uniquement lorsque les informations d’identification sont de type TokenCredential. La valeur peut être https://storage.azure.com/ (par défaut) ou https ://.queue.core.windows.net.

Exemples

Création de QueueServiceClient avec une URL de compte et des informations d’identification.


   from azure.storage.queue.aio import QueueServiceClient
   queue_service = QueueServiceClient(account_url=self.account_url, credential=self.access_key)

Création de QueueServiceClient avec les informations d’identification Azure Identity.


   # Get a token credential for authentication
   from azure.identity.aio import ClientSecretCredential
   token_credential = ClientSecretCredential(
       self.active_directory_tenant_id,
       self.active_directory_application_id,
       self.active_directory_application_secret
   )

   # Instantiate a QueueServiceClient using a token credential
   from azure.storage.queue.aio import QueueServiceClient
   queue_service = QueueServiceClient(account_url=self.account_url, credential=token_credential)

Méthodes

close

Cette méthode consiste à fermer les sockets ouverts par le client. Il n’est pas nécessaire de l’utiliser lors de l’utilisation avec un gestionnaire de contexte.
create_queue

Crée une file d’attente sous le compte spécifié.

Si une file d’attente portant le même nom existe déjà, l’opération échoue. Retourne un client avec lequel interagir avec la file d’attente nouvellement créée.
delete_queue

Supprime la file d’attente spécifiée et tous les messages qu’elle contient.

Lorsqu’une file d’attente est supprimée, elle est immédiatement marquée pour suppression et n’est plus accessible aux clients. La file d'attente est ensuite supprimée du service de File d'attente pendant le garbage collection.

Notez que la suppression d’une file d’attente peut prendre au moins 40 secondes. Si une opération est tentée sur la file d’attente pendant sa suppression, une <xref:azure.storage.queue.aio.HttpResponseError> opération est levée.
from_connection_string

Créez QueueServiceClient à partir d’une chaîne de connexion.
get_queue_client

Obtenir un client pour interagir avec la file d’attente spécifiée.

La file d’attente n’a pas besoin d’exister.
get_service_properties

Obtient les propriétés du service file d’attente d’un compte de stockage, y compris Azure Storage Analytics.
get_service_stats

Récupère des statistiques relatives à la réplication pour le service de File d'attente.

Elle est disponible uniquement lorsque la réplication géoredondante avec accès en lecture est activée pour le compte de stockage.

Avec la réplication géographique redondante, le stockage Azure conserve vos données dans deux emplacements. Dans les deux emplacements, le stockage Azure conserve constamment plusieurs réplicas sains de vos données. L'emplacement où vous lisez, créez, mettez à jour ou supprimez les données est l'emplacement du compte de stockage principal. L’emplacement principal existe dans la région que vous choisissez au moment où vous créez un compte via le portail Azure Management Azure Classic, par exemple, USA Centre Nord. L'emplacement dans lequel vos données sont répliquées est l'emplacement secondaire. L'emplacement secondaire est automatiquement déterminé en fonction de l'emplacement principal ; il se trouve dans un deuxième centre de données qui réside dans la même région que l'emplacement principal. L'accès en lecture seule est disponible à partir de l'emplacement secondaire, si la réplication géographique redondante avec accès en lecture est activée pour votre compte de stockage.
list_queues

Retourne un générateur pour répertorier les files d’attente sous le compte spécifié.

Le générateur suit paresseusement les jetons de continuation retournés par le service et s’arrête lorsque toutes les files d’attente ont été retournées.
set_service_properties

Définit les propriétés du service file d’attente d’un compte de stockage, y compris Azure Storage Analytics.

Si un élément (par exemple, analytics_logging) reste aucun, les paramètres existants sur le service pour cette fonctionnalité sont conservés.

close

Cette méthode consiste à fermer les sockets ouverts par le client. Il n’est pas nécessaire de l’utiliser lors de l’utilisation avec un gestionnaire de contexte.

async close()

create_queue

Crée une file d’attente sous le compte spécifié.

Si une file d’attente portant le même nom existe déjà, l’opération échoue. Retourne un client avec lequel interagir avec la file d’attente nouvellement créée.

async create_queue(name: str, metadata: Dict[str, str] | None = None, **kwargs: Any) -> QueueClient

Paramètres

name
str
Obligatoire

Nom de la file d’attente à créer.

metadata
Dict[str, str]
Obligatoire

Un dict avec name_value paires à associer à la file d’attente en tant que métadonnées. Exemple : {'Category' : 'test'}

timeout
int

Le paramètre timeout est exprimé en secondes.

Retours

QueueClient pour la file d’attente nouvellement créée.

Type de retour

QueueClient

Exemples

Créez une file d’attente dans le service.


   await queue_service.create_queue("myqueue1")

delete_queue

Supprime la file d’attente spécifiée et tous les messages qu’elle contient.

Lorsqu’une file d’attente est supprimée, elle est immédiatement marquée pour suppression et n’est plus accessible aux clients. La file d'attente est ensuite supprimée du service de File d'attente pendant le garbage collection.

Notez que la suppression d’une file d’attente peut prendre au moins 40 secondes. Si une opération est tentée sur la file d’attente pendant sa suppression, une <xref:azure.storage.queue.aio.HttpResponseError> opération est levée.

async delete_queue(queue: QueueProperties | str, **kwargs: Any) -> None

Paramètres

queue
str ou QueueProperties
Obligatoire

File d’attente à supprimer. Il peut s’agir du nom de la file d’attente ou d’un instance de QueueProperties.

timeout
int

Le paramètre timeout est exprimé en secondes.

Type de retour

None

Exemples

Supprimez une file d’attente dans le service.


   await queue_service.delete_queue("myqueue1")

from_connection_string

Créez QueueServiceClient à partir d’une chaîne de connexion.

from_connection_string(conn_str: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | AsyncTokenCredential | None = None, **kwargs: Any) -> Self

Paramètres

conn_str
str
Obligatoire

Une chaîne de connexion à un compte de stockage Azure.

credential
valeur par défaut: None

Informations d’identification avec lesquelles s’authentifier. Cela est facultatif si l’URL du compte a déjà un jeton SAS ou si l’chaîne de connexion a déjà des valeurs de clé d’accès partagé. La valeur peut être une chaîne de jeton SAS, une instance d’azureSasCredential ou AzureNamedKeyCredential à partir d’azure.core.credentials, une clé d’accès partagé de compte ou une instance d’une classe TokenCredentials à partir d’azure.identity. Les informations d’identification fournies ici sont prioritaires sur celles du chaîne de connexion. Si vous utilisez une instance d’AzureNamedKeyCredential, « name » doit être le nom du compte de stockage et « key » doit être la clé de compte de stockage.

Retours

Un client de service de file d’attente.

Type de retour

QueueClient

Exemples

Création de QueueServiceClient avec un chaîne de connexion.


   from azure.storage.queue import QueueServiceClient
   queue_service = QueueServiceClient.from_connection_string(conn_str=self.connection_string)

get_queue_client

Obtenir un client pour interagir avec la file d’attente spécifiée.

La file d’attente n’a pas besoin d’exister.

get_queue_client(queue: QueueProperties | str, **kwargs: Any) -> QueueClient

Paramètres

queue
str ou QueueProperties
Obligatoire

File d'attente. Il peut s’agir du nom de la file d’attente ou d’un instance de QueueProperties.

Retours

Objet QueueClient.

Type de retour

QueueClient

Exemples

Obtenir le client de file d’attente.


   # Get the queue client to interact with a specific queue
   queue = queue_service.get_queue_client(queue="myqueue2")

get_service_properties

Obtient les propriétés du service file d’attente d’un compte de stockage, y compris Azure Storage Analytics.

async get_service_properties(**kwargs: Any) -> Dict[str, Any]

Paramètres

timeout
int

Le paramètre timeout est exprimé en secondes.

Retours

Objet contenant des propriétés de service de file d’attente telles que la journalisation analytique, les métriques d’heure/minute, les règles cors, etc.

Type de retour

Dict[str, Any]

Exemples

Obtention des propriétés du service de file d’attente.


   properties = await queue_service.get_service_properties()

get_service_stats

Récupère des statistiques relatives à la réplication pour le service de File d'attente.

Elle est disponible uniquement lorsque la réplication géoredondante avec accès en lecture est activée pour le compte de stockage.

Avec la réplication géographique redondante, le stockage Azure conserve vos données dans deux emplacements. Dans les deux emplacements, le stockage Azure conserve constamment plusieurs réplicas sains de vos données. L'emplacement où vous lisez, créez, mettez à jour ou supprimez les données est l'emplacement du compte de stockage principal. L’emplacement principal existe dans la région que vous choisissez au moment où vous créez un compte via le portail Azure Management Azure Classic, par exemple, USA Centre Nord. L'emplacement dans lequel vos données sont répliquées est l'emplacement secondaire. L'emplacement secondaire est automatiquement déterminé en fonction de l'emplacement principal ; il se trouve dans un deuxième centre de données qui réside dans la même région que l'emplacement principal. L'accès en lecture seule est disponible à partir de l'emplacement secondaire, si la réplication géographique redondante avec accès en lecture est activée pour votre compte de stockage.

async get_service_stats(**kwargs: Any) -> Dict[str, Any]

Paramètres

timeout
int

Le paramètre timeout est exprimé en secondes.

Retours

Statistiques du service de File d'attente.

Type de retour

Dict[str, Any]

list_queues

Retourne un générateur pour répertorier les files d’attente sous le compte spécifié.

Le générateur suit paresseusement les jetons de continuation retournés par le service et s’arrête lorsque toutes les files d’attente ont été retournées.

list_queues(name_starts_with: str | None = None, include_metadata: bool | None = False, **kwargs: Any) -> AsyncItemPaged

Paramètres

name_starts_with
str
Obligatoire

Filtre les résultats pour renvoyer uniquement les files d’attente dont le nom commence par le préfixe spécifié.

include_metadata
bool
Obligatoire

Spécifie que les métadonnées de file d’attente doivent être retournées dans la réponse.

results_per_page
int

Nombre maximal de noms de file d’attente à récupérer par appel d’API. Si la demande ne spécifie pas, le serveur retourne jusqu’à 5 000 éléments.

timeout
int

Définit le délai d’expiration côté serveur pour l’opération en secondes. Pour plus d’informations, consultez https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations. Cette valeur n’est pas suivie ou validée sur le client. Pour configurer les délais d’expiration du réseau côté client, consultez ici. Cette fonction peut effectuer plusieurs appels au service, auquel cas la valeur de délai d’expiration spécifiée sera appliquée à chaque appel individuel.

Retours

Itérable (pagination automatique) de QueueProperties.

Type de retour

<xref:azure.core.paging.AsyncItemPaged>[QueueProperties]

Exemples

Répertorier les files d’attente dans le service.


   # List all the queues in the service
   list_queues = queue_service.list_queues()
   async for queue in list_queues:
       print(queue)

   # List the queues in the service that start with the name "my_"
   list_my_queues = queue_service.list_queues(name_starts_with="my_")
   async for queue in list_my_queues:
       print(queue)

set_service_properties

Définit les propriétés du service file d’attente d’un compte de stockage, y compris Azure Storage Analytics.

Si un élément (par exemple, analytics_logging) reste aucun, les paramètres existants sur le service pour cette fonctionnalité sont conservés.

async set_service_properties(analytics_logging: QueueAnalyticsLogging | None = None, hour_metrics: Metrics | None = None, minute_metrics: Metrics | None = None, cors: List[CorsRule] | None = None, **kwargs: Any) -> None

Paramètres

analytics_logging
QueueAnalyticsLogging
Obligatoire

Regroupe les paramètres de journalisation d'analyse Azure.

hour_metrics
Metrics
Obligatoire

Les paramètres de métriques d’heure fournissent un résumé des statistiques de requête regroupées par API dans des agrégats horaires pour les files d’attente.

minute_metrics
Metrics
Obligatoire

Les paramètres de métriques de minute fournissent des statistiques de requête pour chaque minute pour les files d’attente.

cors
Optional[List(CorsRule)]
Obligatoire

Vous pouvez inclure jusqu’à cinq éléments CorsRule dans la liste. Si une liste vide est spécifiée, toutes les règles CORS sont supprimées et CORS est désactivé pour le service.

timeout
int

Le paramètre timeout est exprimé en secondes.

Exemples

Définition des propriétés du service de file d’attente.


   # Create service properties
   from azure.storage.queue import QueueAnalyticsLogging, Metrics, CorsRule, RetentionPolicy

   # Create logging settings
   logging = QueueAnalyticsLogging(read=True, write=True, delete=True, retention_policy=RetentionPolicy(enabled=True, days=5))

   # Create metrics for requests statistics
   hour_metrics = Metrics(enabled=True, include_apis=True, retention_policy=RetentionPolicy(enabled=True, days=5))
   minute_metrics = Metrics(enabled=True, include_apis=True, retention_policy=RetentionPolicy(enabled=True, days=5))

   # Create CORS rules
   cors_rule1 = CorsRule(['www.xyz.com'], ['GET'])
   allowed_origins = ['www.xyz.com', "www.ab.com", "www.bc.com"]
   allowed_methods = ['GET', 'PUT']
   max_age_in_seconds = 500
   exposed_headers = ["x-ms-meta-data*", "x-ms-meta-source*", "x-ms-meta-abc", "x-ms-meta-bcd"]
   allowed_headers = ["x-ms-meta-data*", "x-ms-meta-target*", "x-ms-meta-xyz", "x-ms-meta-foo"]
   cors_rule2 = CorsRule(
       allowed_origins,
       allowed_methods,
       max_age_in_seconds=max_age_in_seconds,
       exposed_headers=exposed_headers,
       allowed_headers=allowed_headers
   )

   cors = [cors_rule1, cors_rule2]

   # Set the service properties
   await queue_service.set_service_properties(logging, hour_metrics, minute_metrics, cors)

Attributs

api_version

Version de l’API de stockage utilisée pour les requêtes.

Type de retour

str

location_mode

Mode d’emplacement que le client utilise actuellement.

Par défaut, il s’agit de « primary ». Les options incluent « principal » et « secondaire ».

Type de retour

str

primary_endpoint

URL complète du point de terminaison principal.

Type de retour

str

primary_hostname

Nom d’hôte du point de terminaison principal.

Type de retour

str

secondary_endpoint

URL complète du point de terminaison secondaire si elle est configurée.

S’il n’est pas disponible, un objet ValueError est déclenché. Pour spécifier explicitement un nom d’hôte secondaire, utilisez l’argument facultatif mot clé secondary_hostname lors de l’instanciation.

Type de retour

str

Exceptions

ValueError

secondary_hostname

Nom d’hôte du point de terminaison secondaire.

S’il n’est pas disponible, il s’agit de None. Pour spécifier explicitement un nom d’hôte secondaire, utilisez l’argument facultatif mot clé secondary_hostname lors de l’instanciation.

Type de retour

Optional[str]

url

URL complète du point de terminaison de cette entité, y compris le jeton SAS s’il est utilisé.

Il peut s’agir du point de terminaison principal ou du point de terminaison secondaire en fonction du actuel location_mode. :returns : URL de point de terminaison complète de cette entité, y compris le jeton SAP s’il est utilisé. :rtype: str