QueueServiceClient class

Definition

A client to interact with the Queue Service at the account level.

This client provides operations to retrieve and configure the account properties as well as list, create and delete queues within the account. For operations relating to a specific queue, a client for this entity can be retrieved using the get_queue_client(queue, **kwargs) function.

QueueServiceClient(account_url, credential=None, **kwargs)
Inheritance
builtins.object
azure.storage.queue._shared.base_client.StorageAccountHostsMixin
QueueServiceClient

Parameters

account_url
str

The URL to the queue service endpoint. Any other entities included in the URL path (e.g. queue) will be discarded. This URL can be optionally authenticated with a SAS token.

credential

The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, an account shared access key, or an instance of a TokenCredentials class from azure.identity.

Examples

Creating the QueueServiceClient with an account url and credential.


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

Creating the QueueServiceClient with Azure Identity credentials.


   # Get a token credential for authentication
   from azure.identity 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 import QueueServiceClient
   queue_service = QueueServiceClient(account_url=self.account_url, credential=token_credential)

Methods

create_queue

Creates a new queue under the specified account.

If a queue with the same name already exists, the operation fails. Returns a client with which to interact with the newly created queue.

delete_queue

Deletes the specified queue and any messages it contains.

When a queue is successfully deleted, it is immediately marked for deletion and is no longer accessible to clients. The queue is later removed from the Queue service during garbage collection.

Note that deleting a queue is likely to take at least 40 seconds to complete. If an operation is attempted against the queue while it was being deleted, an <xref:azure.storage.queue.HttpResponseError> will be thrown.

from_connection_string

Create QueueServiceClient from a Connection String.

get_queue_client

Get a client to interact with the specified queue.

The queue need not already exist.

get_service_properties

Gets the properties of a storage account's Queue service, including Azure Storage Analytics.

get_service_stats

Retrieves statistics related to replication for the Queue service.

It is only available when read-access geo-redundant replication is enabled for the storage account.

With geo-redundant replication, Azure Storage maintains your data durable in two locations. In both locations, Azure Storage constantly maintains multiple healthy replicas of your data. The location where you read, create, update, or delete data is the primary storage account location. The primary location exists in the region you choose at the time you create an account via the Azure Management Azure classic portal, for example, North Central US. The location to which your data is replicated is the secondary location. The secondary location is automatically determined based on the location of the primary; it is in a second data center that resides in the same region as the primary location. Read-only access is available from the secondary location, if read-access geo-redundant replication is enabled for your storage account.

list_queues

Returns a generator to list the queues under the specified account.

The generator will lazily follow the continuation tokens returned by the service and stop when all queues have been returned.

set_service_properties

Sets the properties of a storage account's Queue service, including Azure Storage Analytics.

If an element (e.g. analytics_logging) is left as None, the existing settings on the service for that functionality are preserved.

create_queue

Creates a new queue under the specified account.

If a queue with the same name already exists, the operation fails. Returns a client with which to interact with the newly created queue.

create_queue(name, metadata=None, **kwargs)

Parameters

name
str
Required

The name of the queue to create.

metadata
dict(str, str)
Required

A dict with name_value pairs to associate with the queue as metadata. Example: {'Category': 'test'}

Return type

Examples

Create a queue in the service.


   queue_service.create_queue("myqueue1")

delete_queue

Deletes the specified queue and any messages it contains.

When a queue is successfully deleted, it is immediately marked for deletion and is no longer accessible to clients. The queue is later removed from the Queue service during garbage collection.

Note that deleting a queue is likely to take at least 40 seconds to complete. If an operation is attempted against the queue while it was being deleted, an <xref:azure.storage.queue.HttpResponseError> will be thrown.

delete_queue(queue, **kwargs)

Parameters

queue
str or QueueProperties
Required

The queue to delete. This can either be the name of the queue, or an instance of QueueProperties.

Return type

None

Examples

Delete a queue in the service.


   queue_service.delete_queue("myqueue1")

from_connection_string

Create QueueServiceClient from a Connection String.

from_connection_string(conn_str, credential=None, **kwargs)

Parameters

conn_str
str
Required

A connection string to an Azure Storage account.

credential
Required

The credentials with which to authenticate. This is optional if the account URL already has a SAS token, or the connection string already has shared access key values. The value can be a SAS token string, an account shared access key, or an instance of a TokenCredentials class from azure.identity.

credential
default value: None

Returns

A Queue service client.

Return type

Examples

Creating the QueueServiceClient with a connection string.


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

get_queue_client

Get a client to interact with the specified queue.

The queue need not already exist.

get_queue_client(queue, **kwargs)

Parameters

queue
str or QueueProperties
Required

The queue. This can either be the name of the queue, or an instance of QueueProperties.

Returns

A QueueClient object.

Return type

Examples

Get the queue client.


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

get_service_properties

Gets the properties of a storage account's Queue service, including Azure Storage Analytics.

get_service_properties(**kwargs)

Returns

An object containing queue service properties such as analytics logging, hour/minute metrics, cors rules, etc.

Return type

Dict[str, Any]

Examples

Getting queue service properties.


   properties = queue_service.get_service_properties()

get_service_stats

Retrieves statistics related to replication for the Queue service.

It is only available when read-access geo-redundant replication is enabled for the storage account.

With geo-redundant replication, Azure Storage maintains your data durable in two locations. In both locations, Azure Storage constantly maintains multiple healthy replicas of your data. The location where you read, create, update, or delete data is the primary storage account location. The primary location exists in the region you choose at the time you create an account via the Azure Management Azure classic portal, for example, North Central US. The location to which your data is replicated is the secondary location. The secondary location is automatically determined based on the location of the primary; it is in a second data center that resides in the same region as the primary location. Read-only access is available from the secondary location, if read-access geo-redundant replication is enabled for your storage account.

get_service_stats(**kwargs)

Returns

The queue service stats.

Return type

Dict[str, Any]

list_queues

Returns a generator to list the queues under the specified account.

The generator will lazily follow the continuation tokens returned by the service and stop when all queues have been returned.

list_queues(name_starts_with=None, include_metadata=False, **kwargs)

Parameters

name_starts_with
str
Required

Filters the results to return only queues whose names begin with the specified prefix.

include_metadata
bool
Required

Specifies that queue metadata be returned in the response.

Returns

An iterable (auto-paging) of QueueProperties.

Return type

Examples

List queues in the service.


   # List all the queues in the service
   list_queues = queue_service.list_queues()
   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")
   for queue in list_my_queues:
       print(queue)

set_service_properties

Sets the properties of a storage account's Queue service, including Azure Storage Analytics.

If an element (e.g. analytics_logging) is left as None, the existing settings on the service for that functionality are preserved.

set_service_properties(analytics_logging=None, hour_metrics=None, minute_metrics=None, cors=None, **kwargs)

Parameters

analytics_logging
QueueAnalyticsLogging
Required

Groups the Azure Analytics Logging settings.

hour_metrics
Metrics
Required

The hour metrics settings provide a summary of request statistics grouped by API in hourly aggregates for queues.

minute_metrics
Metrics
Required

The minute metrics settings provide request statistics for each minute for queues.

cors
list(CorsRule)
Required

You can include up to five CorsRule elements in the list. If an empty list is specified, all CORS rules will be deleted, and CORS will be disabled for the service.

Return type

None

Examples

Setting queue service properties.


   # 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
   queue_service.set_service_properties(logging, hour_metrics, minute_metrics, cors)