QueueServiceClient Class

Reference

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 function.

For more optional configuration, please click here.

Inheritance: azure.storage.queue._shared.base_client.StorageAccountHostsMixin

QueueServiceClient

azure.storage.queue._encryption.StorageEncryptionMixin

QueueServiceClient

Constructor

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

Parameters

Name	Description
account_url Required	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	AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None 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 instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials, an account shared access key, or an instance of a TokenCredentials class from azure.identity. If the resource URI already contains a SAS token, this will be ignored in favor of an explicit credential except in the case of AzureSasCredential, where the conflicting SAS tokens will raise a ValueError. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key. Default value: None

Name

Description

account_url

Required

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

AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None

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 instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials, an account shared access key, or an instance of a TokenCredentials class from azure.identity. If the resource URI already contains a SAS token, this will be ignored in favor of an explicit credential

except in the case of AzureSasCredential, where the conflicting SAS tokens will raise a ValueError. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key.

Default value: None

Keyword-Only Parameters

Name	Description
api_version	str The Storage API version to use for requests. Default value is the most recent service version that is compatible with the current SDK. Setting to an older version may result in reduced feature compatibility.
secondary_hostname	str The hostname of the secondary endpoint.
audience	str The audience to use when requesting tokens for Azure Active Directory authentication. Only has an effect when credential is of type TokenCredential. The value could be https://storage.azure.com/ (default) or https://.queue.core.windows.net.

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 Default Azure Identity credentials.


   # Get a token credential for authentication
   from azure.identity import DefaultAzureCredential
   token_credential = DefaultAzureCredential()

   # 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

close	This method is to close the sockets opened by the client. It need not be used when using with a context manager.
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.

close

This method is to close the sockets opened by the client. It need not be used when using with a context manager.

close()

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: str, metadata: Dict[str, str] | None = None, **kwargs: Any) -> QueueClient

Parameters

Name	Description
name Required	str The name of the queue to create.
metadata Required	Dict[str, str] A dict with name_value pairs to associate with the queue as metadata. Example: {'Category': 'test'}

Keyword-Only Parameters

Name	Description
timeout	int The timeout parameter is expressed in seconds.

Returns

Type	Description
QueueClient	A QueueClient for the newly created Queue.

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: QueueProperties | str, **kwargs: Any) -> None

Parameters

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

Keyword-Only Parameters

Name	Description
timeout	int The timeout parameter is expressed in seconds.

Returns

Type	Description
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: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parameters

Name	Description
conn_str Required	str A connection string to an Azure Storage account.
credential	AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None 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 instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials, an account shared access key, or an instance of a TokenCredentials class from azure.identity. Credentials provided here will take precedence over those in the connection string. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key. Default value: None

Name

Description

conn_str

Required

str

A connection string to an Azure Storage account.

credential

AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None

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 instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials, an account shared access key, or an instance of a TokenCredentials class from azure.identity. Credentials provided here will take precedence over those in the connection string. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key.

Default value: None

Keyword-Only Parameters

Name	Description
audience	str The audience to use when requesting tokens for Azure Active Directory authentication. Only has an effect when credential is of type TokenCredential. The value could be https://storage.azure.com/ (default) or https://.queue.core.windows.net.

Returns

Type	Description
QueueClient	A Queue service client.

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: QueueProperties | str, **kwargs: Any) -> QueueClient

Parameters

Name	Description
queue Required	str or QueueProperties The queue. This can either be the name of the queue, or an instance of QueueProperties.

Returns

Type	Description
QueueClient	A QueueClient object.

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: Any) -> Dict[str, Any]

Keyword-Only Parameters

Name	Description
timeout	int The timeout parameter is expressed in seconds.

Returns

Type	Description
Dict[str, Any]	An object containing queue service properties such as analytics logging, hour/minute metrics, cors rules, etc.

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: Any) -> Dict[str, Any]

Keyword-Only Parameters

Name	Description
timeout	int The timeout parameter is expressed in seconds.

Returns

Type	Description
Dict[str, Any]	The queue service stats.

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: str | None = None, include_metadata: bool | None = False, **kwargs: Any) -> ItemPaged[QueueProperties]

Parameters

Name	Description
name_starts_with Required	str Filters the results to return only queues whose names begin with the specified prefix.
include_metadata Required	bool Specifies that queue metadata be returned in the response.

Keyword-Only Parameters

Name	Description
results_per_page	int The maximum number of queue names to retrieve per API call. If the request does not specify the server will return up to 5,000 items.
timeout	int Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here. This function may make multiple calls to the service in which case the timeout value specified will be applied to each individual call.

Name

Description

results_per_page

int

The maximum number of queue names to retrieve per API call. If the request does not specify the server will return up to 5,000 items.

timeout

int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here. This function may make multiple calls to the service in which case the timeout value specified will be applied to each individual call.

Returns

Type	Description
ItemPaged[QueueProperties]	An iterable (auto-paging) of QueueProperties.

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: QueueAnalyticsLogging | None = None, hour_metrics: Metrics | None = None, minute_metrics: Metrics | None = None, cors: List[CorsRule] | None = None, **kwargs: Any) -> None

Parameters

Name	Description
analytics_logging Required	QueueAnalyticsLogging Groups the Azure Analytics Logging settings.
hour_metrics Required	Metrics The hour metrics settings provide a summary of request statistics grouped by API in hourly aggregates for queues.
minute_metrics Required	Metrics The minute metrics settings provide request statistics for each minute for queues.
cors Required	Optional[List[CorsRule]] 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.

Keyword-Only Parameters

Name	Description
timeout	int The timeout parameter is expressed in seconds.

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)

Attributes

api_version

The version of the Storage API used for requests.

Returns

Type	Description
str

location_mode

The location mode that the client is currently using.

By default this will be "primary". Options include "primary" and "secondary".

Returns

Type	Description
str

primary_endpoint

The full primary endpoint URL.

Returns

Type	Description
str

primary_hostname

The hostname of the primary endpoint.

Returns

Type	Description
str

secondary_endpoint

The full secondary endpoint URL if configured.

If not available a ValueError will be raised. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Returns

Type	Description
str

Exceptions

Type	Description
ValueError

secondary_hostname

The hostname of the secondary endpoint.

If not available this will be None. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Returns

Type	Description
Optional[str]

url

The full endpoint URL to this entity, including SAS token if used.

This could be either the primary endpoint, or the secondary endpoint depending on the current location_mode. :returns: The full endpoint URL to this entity, including SAS token if used. :rtype: str

Share via

QueueServiceClient Class

Constructor

Parameters

Keyword-Only Parameters

Examples

Methods

close

create_queue

Parameters

Keyword-Only Parameters

Returns

Examples

delete_queue

Parameters

Keyword-Only Parameters

Returns

Examples

from_connection_string

Parameters

Keyword-Only Parameters

Returns

Examples

get_queue_client

Parameters

Returns

Examples

get_service_properties

Keyword-Only Parameters

Returns

Examples

get_service_stats

Keyword-Only Parameters

Returns

list_queues

Parameters

Keyword-Only Parameters

Returns

Examples

set_service_properties

Parameters

Keyword-Only Parameters

Examples

Attributes

api_version

Returns

location_mode

Returns

primary_endpoint

Returns

primary_hostname

Returns

secondary_endpoint

Returns

Exceptions

secondary_hostname

Returns

url

Additional resources