你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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 路径 (中包含的任何其他实体（例如队列) ）将被丢弃。可以选择使用 SAS 令牌对此 URL 进行身份验证。

credential

默认值: None

用于进行身份验证的凭据。如果帐户 URL 已有 SAS 令牌，则这是可选的。该值可以是 SAS 令牌字符串、AzureSasCredential 的实例或 azure.core.credentials 中的 AzureNamedKeyCredential、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。如果资源 URI 已包含 SAS 令牌，则会忽略此令牌，转而使用显式凭据

AzureSasCredential 的情况除外，其中冲突的 SAS 令牌将引发 ValueError。如果使用 AzureNamedKeyCredential 的实例，则“name”应为存储帐户名称，“密钥”应为存储帐户密钥。

api_version: str

用于请求的存储 API 版本。默认值是与当前 SDK 兼容的最新服务版本。设置为较旧版本可能会导致功能兼容性降低。

secondary_hostname: str

辅助终结点的主机名。

audience: str

请求 Azure Active Directory 身份验证令牌时要使用的受众。仅当凭据的类型为 TokenCredential 时有效。该值可以是 https://storage.azure.com/ 默认 () 或 https：//.queue.core.windows.net。

示例

使用帐户 URL 和凭据创建 QueueServiceClient。


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

使用 Azure 标识凭据创建 QueueServiceClient。


   # 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) 保留为 None，则保留该服务上该功能的现有设置。

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对的 dict。示例：{'Category'： 'test'}

timeout: int

超时参数以秒表示。

新创建的队列的 QueueClient。

返回类型

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

超时参数以秒表示。

返回类型

None

示例

删除服务中的队列。


   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 的实例或 azure.core.credentials 中的 AzureNamedKeyCredential、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。此处提供的凭据优先于连接字符串中的凭据。如果使用 AzureNamedKeyCredential 的实例，则“name”应为存储帐户名称，“密钥”应为存储帐户密钥。

audience: str

队列服务客户端。

返回类型

QueueClient

示例

使用连接字符串创建 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 对象。

返回类型

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 规则等）的对象。

返回类型

Dict[str, Any]

示例

获取队列服务属性。


   properties = queue_service.get_service_properties()

get_service_stats

检索与队列服务的复制有关的统计信息。

仅当为存储帐户启用读取访问异地冗余复制时，它才可用。

通过地域冗余复制，Azure 存储服务在两个位置维护你的持久数据。在这两个位置，Azure 存储始终维护您数据的多个运行正常副本。读取、创建、更新或删除数据的位置称为“主”存储帐户位置。在通过 Azure 管理 Azure 经典门户（例如美国中北部）创建帐户时所选区域中存在主要位置。数据复制到的位置为“辅助”位置。根据主位置自动确定辅助位置，它在主位置所在区域中的第二个数据中心内。如果为存储帐户启用了“读访问的地域冗余复制”，则可对辅助位置执行只读访问。

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

参数

timeout: int

超时参数以秒表示。

队列服务统计信息。

返回类型

Dict[str, Any]

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 调用要检索的最大队列名称数。如果请求未指定，服务器将返回最多 5,000 个项。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。此函数可能会对服务进行多次调用，在这种情况下，指定的超时值将应用于每个单独的调用。

QueueProperties 的可迭代 (自动分页) 。

返回类型

ItemPaged[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) 保留为 None，则保留该服务上该功能的现有设置。

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 Logging 设置进行分组。

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”和“secondary”。

返回类型

str

primary_endpoint

完整的主终结点 URL。

返回类型

str

primary_hostname

主终结点的主机名。

返回类型

str

secondary_endpoint

完整的辅助终结点 URL（如果已配置）。

如果不可用，将引发 ValueError。若要显式指定辅助主机名，请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。

返回类型

str

例外

ValueError

secondary_hostname

辅助终结点的主机名。

如果不可用，则此项将为“无”。若要显式指定辅助主机名，请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。

返回类型

Optional[str]

url

此实体的完整终结点 URL，包括 SAS 令牌（如果使用）。

这可以是主终结点，也可以是辅助终结点，具体取决于当前 location_mode。：returns：此实体的完整终结点 URL，包括 SAS 令牌（如果使用）。 :rtype：str

通过

QueueServiceClient 类

构造函数

参数

示例

方法

close

create_queue

参数

返回

返回类型

示例

delete_queue

参数

返回类型

示例

from_connection_string

参数

返回

返回类型

示例

get_queue_client

参数

返回

返回类型

示例

get_service_properties

参数

返回

返回类型

示例

get_service_stats

参数

返回

返回类型

list_queues

参数

返回

返回类型

示例

set_service_properties

参数

示例

属性

api_version

返回类型

location_mode

返回类型

primary_endpoint

返回类型

primary_hostname

返回类型

secondary_endpoint

返回类型

例外

secondary_hostname

返回类型

url

其他资源