Поделиться через


QueueServiceClient Класс

Клиент для взаимодействия со службой очередей на уровне учетной записи.

Этот клиент предоставляет операции по получению и настройке свойств учетной записи, а также перечислению, созданию и удалению очередей в учетной записи. Для операций, связанных с определенной очередью, клиент для этой сущности можно получить с помощью get_queue_client функции .

Дополнительные сведения о настройке см. здесь.

Наследование
azure.storage.queue._shared.base_client.StorageAccountHostsMixin
QueueServiceClient
azure.storage.queue._encryption.StorageEncryptionMixin
QueueServiceClient

Конструктор

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

Параметры

account_url
str
Обязательно

URL-адрес конечной точки службы очередей. Все другие сущности, включенные в URL-путь (например, очередь), будут удалены. Этот URL-адрес можно при необходимости пройти проверку подлинности с помощью маркера SAS.

credential
значение по умолчанию: None

Учетные данные, с помощью которых выполняется проверка подлинности. Это необязательно, если URL-адрес учетной записи уже содержит маркер SAS. Значением может быть строка маркера SAS, экземпляр AzureSasCredential или AzureNamedKeyCredential из azure.core.credentials, общий ключ доступа учетной записи или экземпляр класса TokenCredentials из azure.identity. Если URI ресурса уже содержит маркер SAS, он будет игнорироваться в пользу явных учетных данных.

  • за исключением случаев AzureSasCredential, где конфликтующие маркеры SAS вызовет ValueError. При использовании экземпляра AzureNamedKeyCredential "имя" должно быть именем учетной записи хранения, а "ключ" — ключом учетной записи хранения.
api_version
str

Версия API хранилища, используемая для запросов. Значение по умолчанию — последняя версия службы, совместимая с текущим пакетом SDK. Установка более старой версии может привести к снижению совместимости функций.

secondary_hostname
str

Имя узла вторичной конечной точки.

audience
str

Аудитория, используемая при запросе маркеров для проверки подлинности Azure Active Directory. Действует только в том случае, если учетные данные имеют тип TokenCredential. Значение может быть https://storage.azure.com/ (по умолчанию) или https://.queue.core.windows.net.

Примеры

Создание QueueServiceClient с URL-адресом учетной записи и учетными данными.


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

Создание QueueServiceClient с учетными данными удостоверений Azure.


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

Методы

close

Этот метод позволяет закрыть сокеты, открытые клиентом. Его не нужно использовать при использовании с диспетчером контекста.

create_queue

Создает новую очередь в указанной учетной записи.

Если очередь с таким именем уже существует, операция завершается сбоем. Возвращает клиент, с которым необходимо взаимодействовать с созданной очередью.

delete_queue

Удаляет указанную очередь и все содержащиеся в ней сообщения.

После успешного удаления очередь сразу помечается для удаления и больше не доступна клиентам. Впоследствии очередь удаляется из службы очередей в процессе сборки мусора.

Обратите внимание, что удаление очереди, скорее всего, займет не менее 40 секунд. При попытке выполнить операцию с очередью во время ее удаления будет выдано <xref:azure.storage.queue.HttpResponseError> исключение .

from_connection_string

Создайте QueueServiceClient из строки подключения.

get_queue_client

Получение клиента для взаимодействия с указанной очередью.

Очередь еще не должна существовать.

get_service_properties

Возвращает свойства службы очередей учетной записи хранения, включая azure Аналитика Службы хранилища.

get_service_stats

Получает статистику, связанную с репликацией службы очередей.

Он доступен, только если для учетной записи хранения включена геоизбыточная репликация с доступом на чтение.

Благодаря географически избыточной репликации хранилище Azure надежно хранит ваши данные в двух расположениях. В обоих расположениях хранилище Azure поддерживает несколько работоспособных копий данных. Расположение, в котором вы читаете, создаете, обновляете или удаляете данные, является первичным расположением учетной записи хранилища. Основное расположение находится в регионе, выбранном при создании учетной записи с помощью классического портала Azure управления Azure, например в центрально-северной части США. Расположение, в которое ваши данные реплицируются, — это вторичное расположение. Оно определяется автоматически, исходя из выбранного первичного расположения. Это второй центр обработки данных в том же регионе, где находится первичное расположение. Во вторичном расположении предоставляется доступ только для чтения, если для вашей учетной записи хранилища включена географически избыточная репликация с доступом только для чтения.

list_queues

Возвращает генератор для вывода списка очередей в указанной учетной записи.

Генератор будет отложенно следовать маркерам продолжения, возвращенным службой, и останавливаться, когда будут возвращены все очереди.

set_service_properties

Задает свойства службы очередей учетной записи хранения, включая Аналитика Службы хранилища Azure.

Если элемент (например, analytics_logging) остается как Нет, существующие в службе параметры для этой функции сохраняются.

close

Этот метод позволяет закрыть сокеты, открытые клиентом. Его не нужно использовать при использовании с диспетчером контекста.

close()

create_queue

Создает новую очередь в указанной учетной записи.

Если очередь с таким именем уже существует, операция завершается сбоем. Возвращает клиент, с которым необходимо взаимодействовать с созданной очередью.

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

Параметры

name
str
Обязательно

Имя создаваемой очереди.

metadata
Dict[str, str]
Обязательно

Дикт с name_value парами для связывания с очередью в качестве метаданных. Пример: {'Category': 'test'}

timeout
int

Параметр времени ожидания указывается в секундах.

Возвращаемое значение

QueueClient для созданной очереди.

Возвращаемый тип

Примеры

Создайте очередь в службе.


   queue_service.create_queue("myqueue1")

delete_queue

Удаляет указанную очередь и все содержащиеся в ней сообщения.

После успешного удаления очередь сразу помечается для удаления и больше не доступна клиентам. Впоследствии очередь удаляется из службы очередей в процессе сборки мусора.

Обратите внимание, что удаление очереди, скорее всего, займет не менее 40 секунд. При попытке выполнить операцию с очередью во время ее удаления будет выдано <xref:azure.storage.queue.HttpResponseError> исключение .

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

Параметры

queue
str или QueueProperties
Обязательно

Удаляемая очередь. Это может быть имя очереди или экземпляр QueueProperties.

timeout
int

Параметр времени ожидания указывается в секундах.

Возвращаемый тип

Примеры

Удаление очереди в службе.


   queue_service.delete_queue("myqueue1")

from_connection_string

Создайте QueueServiceClient из строки подключения.

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

Параметры

conn_str
str
Обязательно

Строка подключения в учетную запись хранения Azure.

credential
значение по умолчанию: None

Учетные данные, с помощью которых выполняется проверка подлинности. Это необязательно, если в URL-адресе учетной записи уже есть маркер SAS или у строка подключения уже есть значения общего ключа доступа. Значением может быть строка маркера SAS, экземпляр AzureSasCredential или AzureNamedKeyCredential из azure.core.credentials, общий ключ доступа учетной записи или экземпляр класса TokenCredentials из azure.identity. Предоставленные здесь учетные данные будут иметь приоритет над учетными данными в строка подключения. При использовании экземпляра AzureNamedKeyCredential "имя" должно быть именем учетной записи хранения, а "ключ" — ключом учетной записи хранения.

audience
str

Аудитория, используемая при запросе маркеров для проверки подлинности Azure Active Directory. Действует только в том случае, если учетные данные имеют тип TokenCredential. Значение может быть https://storage.azure.com/ (по умолчанию) или https://.queue.core.windows.net.

Возвращаемое значение

Клиент службы очередей.

Возвращаемый тип

Примеры

Создание QueueServiceClient с строка подключения.


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

get_queue_client

Получение клиента для взаимодействия с указанной очередью.

Очередь еще не должна существовать.

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

Параметры

queue
str или QueueProperties
Обязательно

Очередь. Это может быть имя очереди или экземпляр QueueProperties.

Возвращаемое значение

Объект QueueClient.

Возвращаемый тип

Примеры

Получите клиент очереди.


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

get_service_properties

Возвращает свойства службы очередей учетной записи хранения, включая azure Аналитика Службы хранилища.

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

Параметры

timeout
int

Параметр времени ожидания указывается в секундах.

Возвращаемое значение

Объект, содержащий свойства службы очередей, такие как ведение журнала аналитики, метрики по часам в минуту, правила cors и т. д.

Возвращаемый тип

Примеры

Получение свойств службы очередей.


   properties = queue_service.get_service_properties()

get_service_stats

Получает статистику, связанную с репликацией службы очередей.

Он доступен, только если для учетной записи хранения включена геоизбыточная репликация с доступом на чтение.

Благодаря географически избыточной репликации хранилище Azure надежно хранит ваши данные в двух расположениях. В обоих расположениях хранилище Azure поддерживает несколько работоспособных копий данных. Расположение, в котором вы читаете, создаете, обновляете или удаляете данные, является первичным расположением учетной записи хранилища. Основное расположение находится в регионе, выбранном при создании учетной записи с помощью классического портала Azure управления Azure, например в центрально-северной части США. Расположение, в которое ваши данные реплицируются, — это вторичное расположение. Оно определяется автоматически, исходя из выбранного первичного расположения. Это второй центр обработки данных в том же регионе, где находится первичное расположение. Во вторичном расположении предоставляется доступ только для чтения, если для вашей учетной записи хранилища включена географически избыточная репликация с доступом только для чтения.

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

Параметры

timeout
int

Параметр времени ожидания указывается в секундах.

Возвращаемое значение

Статистика службы очередей.

Возвращаемый тип

list_queues

Возвращает генератор для вывода списка очередей в указанной учетной записи.

Генератор будет отложенно следовать маркерам продолжения, возвращенным службой, и останавливаться, когда будут возвращены все очереди.

list_queues(name_starts_with: str | None = None, include_metadata: bool | None = False, **kwargs: Any) -> ItemPaged[QueueProperties]

Параметры

name_starts_with
str
Обязательно

Фильтрует результаты, чтобы возвращать только очереди, имена которых начинаются с указанного префикса.

include_metadata
bool
Обязательно

Указывает, что в ответе возвращаются метаданные очереди.

results_per_page
int

Максимальное количество имен очередей для получения на вызов API. Если в запросе не указано, сервер вернет до 5000 элементов.

timeout
int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations. Это значение не отслеживается и не проверяется на клиенте. Чтобы настроить время ожидания сети на стороне клиента, см. здесь. Эта функция может выполнять несколько вызовов службы, в этом случае указанное значение времени ожидания будет применяться к каждому отдельному вызову.

Возвращаемое значение

Итерируемое (автоматическое разбиение по страницам) объекта QueueProperties.

Возвращаемый тип

Примеры

Вывод списка очередей в службе.


   # 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

Задает свойства службы очередей учетной записи хранения, включая Аналитика Службы хранилища Azure.

Если элемент (например, analytics_logging) остается как Нет, существующие в службе параметры для этой функции сохраняются.

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

Параметры

analytics_logging
QueueAnalyticsLogging
Обязательно

Группирует параметры ведения журнала Azure Analytics.

hour_metrics
Metrics
Обязательно

Параметры часовых метрик предоставляют сводку статистики запросов, сгруппированной по API, в почасовых статистических выражениях для очередей.

minute_metrics
Metrics
Обязательно

Параметры метрик минуты предоставляют статистику запросов за каждую минуту для очередей.

cors
Optional[List[CorsRule]]
Обязательно

В список можно включить до пяти элементов CorsRule. Если указан пустой список, все правила CORS будут удалены, а CORS будет отключен для службы.

timeout
int

Параметр времени ожидания указывается в секундах.

Примеры

Настройка свойств службы очередей.


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

Атрибуты

api_version

Версия API хранилища, используемого для запросов.

Возвращаемый тип

str

location_mode

Режим расположения, который в настоящее время использует клиент.

По умолчанию это будет "primary". Варианты включают "primary" и "secondary".

Возвращаемый тип

str

primary_endpoint

Полный URL-адрес основной конечной точки.

Возвращаемый тип

str

primary_hostname

Имя узла основной конечной точки.

Возвращаемый тип

str

secondary_endpoint

Полный URL-адрес вторичной конечной точки, если он настроен.

Если он недоступен, будет вызван параметр ValueError. Чтобы явно указать дополнительное имя узла, используйте необязательный аргумент secondary_hostname ключевое слово при создании экземпляра.

Возвращаемый тип

str

Исключения

secondary_hostname

Имя узла вторичной конечной точки.

Если этот параметр недоступен, это будет Значение Нет. Чтобы явно указать дополнительное имя узла, используйте необязательный аргумент secondary_hostname ключевое слово при создании экземпляра.

Возвращаемый тип

url

Полный URL-адрес конечной точки для этой сущности, включая маркер SAS, если он используется.

Это может быть либо основная конечная точка, либо вторичная конечная точка в зависимости от текущей location_mode. :returns: полный URL-адрес конечной точки для этой сущности, включая маркер SAS, если используется. :rtype: str