你当前正在访问 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

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

返回

队列服务客户端。

返回类型

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