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.objectazure.storage.queue._shared.base_client.StorageAccountHostsMixinQueueServiceClient
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
The name of the queue to create.
- metadata
- dict(str, str)
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
The queue to delete. This can either be the name of the queue, or an instance of QueueProperties.
Return type
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
A connection string to an Azure Storage account.
- credential
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
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
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
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
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
Filters the results to return only queues whose names begin with the specified prefix.
- include_metadata
- bool
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
- hour_metrics
- Metrics
The hour metrics settings provide a summary of request statistics grouped by API in hourly aggregates for queues.
- minute_metrics
- Metrics
The minute metrics settings provide request statistics for each minute for queues.
- cors
- 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.
Return type
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)