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

QueueClient 类

参考

要与特定队列交互的客户端。

有关更多可选配置，请单击此处。

继承: azure.storage.queue._shared.base_client.StorageAccountHostsMixin

QueueClient

azure.storage.queue._encryption.StorageEncryptionMixin

QueueClient

构造函数

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

参数

account_url: str

必需

存储帐户的 URL。若要在给定队列的完整 URI 的情况下创建客户端，请使用 from_queue_url classmethod。

queue_name: str

必需

队列的名称。

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

辅助终结点的主机名。

message_encode_policy

要对传出消息使用的编码策略。默认不对消息进行编码。其他选项包括 TextBase64EncodePolicy、 BinaryBase64EncodePolicy 或 None。

message_decode_policy

要对传入消息使用的解码策略。默认值为不解码消息。其他选项包括 TextBase64DecodePolicy、 BinaryBase64DecodePolicy 或 None。

audience: str

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

示例

使用 URL 和凭据创建队列客户端。


   token_auth_queue = QueueClient.from_queue_url(
       queue_url=queue.url,
       credential=sas_token
   )

方法

clear_messages	删除指定队列中的所有消息。
close	此方法用于关闭客户端打开的套接字。与上下文管理器一起使用时，不需要使用它。
create_queue	在存储帐户中创建新队列。如果已存在同名的队列，则操作会失败并显示 ResourceExistsError。
delete_message	删除指定的消息。通常，在客户端使用接收消息操作检索消息后，客户端应处理并删除该消息。若要删除消息，必须具有消息对象本身或两个数据项：id 和pop_receipt。 ID 是从上一个receive_messages操作返回的。从最近的 receive_messages 或 update_message 操作返回pop_receipt。为了使delete_message操作成功，请求中指定的pop_receipt必须与或 receive_messages update_message 操作返回的pop_receipt匹配。
delete_queue	删除指定的队列及其包含的任何消息。成功删除队列后，会立即将其标记为删除，客户端不再可访问该队列。该队列将在稍后的垃圾回收期间从队列服务中删除。请注意，删除队列可能需要至少 40 秒才能完成。如果在删除队列时尝试对队列执行操作， <xref:azure.storage.queue.HttpResponseError> 则会引发。
from_connection_string	从连接字符串创建 QueueClient。
from_queue_url	要与特定队列交互的客户端。
get_queue_access_policy	返回有关队列上指定的任何存储访问策略的详细信息，这些策略可与共享访问签名一起使用。
get_queue_properties	返回指定队列的所有用户定义的元数据。返回的数据不包括队列的消息列表。
peek_messages	从队列前面检索一个或多个消息，但不会更改消息的可见性。只能检索可见的消息。首次使用调用 receive_messages检索消息时，其dequeue_count属性设置为 1。如果未删除并随后再次检索，则会递增 dequeue_count 属性。客户端可以使用此值来确定已检索某条消息的次数。请注意，对 peek_messages 的调用不会递增 dequeue_count 的值，但会返回此值供客户端读取。如果在本地服务对象上设置了 key-encryption-key 或 resolver 字段，则消息将在返回之前解密。
receive_message	从队列的前面删除一条消息。从队列中检索消息时，响应包括消息内容和pop_receipt值，这是删除消息所必需的。消息不会自动从队列中删除，但在检索消息后，其他客户端在visibility_timeout参数指定的时间间隔内不可见。如果在本地服务对象上设置了 key-encryption-key 或 resolver 字段，则会在返回之前解密该消息。
receive_messages	从队列的前面删除一个或多个消息。从队列中检索消息时，响应包括消息内容和pop_receipt值，这是删除消息所必需的。消息不会自动从队列中删除，但在检索消息后，其他客户端在visibility_timeout参数指定的时间间隔内不可见。如果) 设置了max_messages，迭代器将持续提取消息，直到队列为空或max_messages到达 (。如果在本地服务对象上设置了 key-encryption-key 或 resolver 字段，则消息将在返回之前解密。
send_message	将新消息添加到消息队列的后面。可见性超时指定消息不可见的时间。在超时到期后，消息将变为可见。如果未指定可见性超时，则使用默认值 0。消息生存时间指定消息在队列中的保留时间。在生存时间到期后，将从队列中删除消息。如果在本地服务对象上设置了 key-encryption-key 字段，则此方法将在上传之前加密内容。
set_queue_access_policy	为队列设置存储访问策略（可与共享访问签名一起使用）。在设置队列的权限时，将替换现有的权限。若要更新队列的权限，请调用 get_queue_access_policy 以提取与队列关联的所有访问策略，修改要更改的访问策略，然后使用完整的数据集调用此函数以执行更新。建立队列的存储访问策略时，它可能最多需要 30 秒才能生效。在此时间间隔内，与存储访问策略关联的共享访问签名将引发， <xref:azure.storage.queue.HttpResponseError> 直到访问策略变为活动状态。
set_queue_metadata	设置指定队列上的用户定义的元数据。元数据以名称-值对的形式与队列相关联。
update_message	汇报消息的可见性超时。也可以使用此操作更新消息的内容。此操作可用于持续扩展队列消息的不可见性。如果希望辅助角色“租用”队列消息，此功能非常有用。例如，如果辅助角色调用 receive_messages 并识别出处理消息需要更多时间，则可以持续延长消息的不可见性，直到处理消息。如果在处理期间辅助角色失败，消息最终将再次变为可见，并且另一个辅助角色可以处理该消息。如果在本地服务对象上设置了 key-encryption-key 字段，则此方法将在上传之前加密内容。

clear_messages

删除指定队列中的所有消息。

clear_messages(**kwargs: Any) -> None

参数

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

示例

清除所有消息。


   queue.clear_messages()

close

此方法用于关闭客户端打开的套接字。与上下文管理器一起使用时，不需要使用它。

close()

create_queue

在存储帐户中创建新队列。

如果已存在同名的队列，则操作会失败并显示 ResourceExistsError。

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

参数

metadata: Dict[str,str]

包含要作为元数据与队列关联的名称/值对的 dict。请注意，元数据名称保留在创建时具有的大小写形式，但在设置或读取时不区分大小写。

timeout: int

无或 cls 的结果 (响应)

返回类型

None

例外

StorageErrorException

示例

创建队列。


   queue.create_queue()

delete_message

删除指定的消息。

通常，在客户端使用接收消息操作检索消息后，客户端应处理并删除该消息。若要删除消息，必须具有消息对象本身或两个数据项：id 和pop_receipt。 ID 是从上一个receive_messages操作返回的。从最近的 receive_messages 或 update_message 操作返回pop_receipt。为了使delete_message操作成功，请求中指定的pop_receipt必须与或 receive_messages update_message 操作返回的pop_receipt匹配。

delete_message(message: str | QueueMessage, pop_receipt: str | None = None, **kwargs: Any) -> None

参数

message: str 或 QueueMessage

必需

标识要删除的消息的消息对象或 ID。

pop_receipt: str

必需

从之前对或 update_message的调用receive_messages返回的有效 pop 回执值。

timeout: int

示例

删除邮件。


   # Get the message at the front of the queue
   msg = next(queue.receive_messages())

   # Delete the specified message
   queue.delete_message(msg)

delete_queue

删除指定的队列及其包含的任何消息。

成功删除队列后，会立即将其标记为删除，客户端不再可访问该队列。该队列将在稍后的垃圾回收期间从队列服务中删除。

请注意，删除队列可能需要至少 40 秒才能完成。如果在删除队列时尝试对队列执行操作， <xref:azure.storage.queue.HttpResponseError> 则会引发。

delete_queue(**kwargs: Any) -> None

参数

timeout: int

返回类型

None

示例

删除队列。


   queue.delete_queue()

from_connection_string

从连接字符串创建 QueueClient。

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

参数

conn_str: str

必需

Azure 存储帐户的连接字符串。

queue_name: str

必需

队列名称。

credential

默认值: None

用于进行身份验证的凭据。如果帐户 URL 已有 SAS 令牌，或者连接字符串已具有共享访问密钥值，则这是可选的。该值可以是 SAS 令牌字符串、AzureSasCredential 的实例或 azure.core.credentials 中的 AzureNamedKeyCredential、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。此处提供的凭据优先于连接字符串中的凭据。如果使用 AzureNamedKeyCredential 的实例，则“name”应为存储帐户名称，“密钥”应为存储帐户密钥。

audience: str

队列客户端。

返回类型

QueueClient

示例

从连接字符串创建队列客户端。


   from azure.storage.queue import QueueClient
   queue = QueueClient.from_connection_string(self.connection_string, "myqueue1")

from_queue_url

要与特定队列交互的客户端。

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

参数

queue_url: str

必需

队列的完整 URI，包括 SAS 令牌（如果使用）。

credential

默认值: None

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

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

audience: str

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

队列客户端。

返回类型

QueueClient

get_queue_access_policy

返回有关队列上指定的任何存储访问策略的详细信息，这些策略可与共享访问签名一起使用。

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

参数

timeout: int

设置操作的服务器端超时（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

与队列关联的访问策略字典。

返回类型

Dict[str, AccessPolicy]

get_queue_properties

返回指定队列的所有用户定义的元数据。

返回的数据不包括队列的消息列表。

get_queue_properties(**kwargs: Any) -> QueueProperties

参数

timeout: int

超时参数以秒表示。

队列的用户定义元数据。

返回类型

QueueProperties

示例

获取队列的属性。


   properties = queue.get_queue_properties().metadata

peek_messages

从队列前面检索一个或多个消息，但不会更改消息的可见性。

只能检索可见的消息。首次使用调用 receive_messages检索消息时，其dequeue_count属性设置为 1。如果未删除并随后再次检索，则会递增 dequeue_count 属性。客户端可以使用此值来确定已检索某条消息的次数。请注意，对 peek_messages 的调用不会递增 dequeue_count 的值，但会返回此值供客户端读取。

如果在本地服务对象上设置了 key-encryption-key 或 resolver 字段，则消息将在返回之前解密。

peek_messages(max_messages: int | None = None, **kwargs: Any) -> List[QueueMessage]

参数

max_messages: int

必需

用来指定要从队列查看的消息数目的非零整数值，最大值为 32。默认情况下，此操作查看队列中的一条消息。

timeout: int

QueueMessage 对象的列表。请注意，next_visible_on和pop_receipt不会填充，因为速览不会弹出邮件，并且只能检索已可见的消息。

返回类型

list(QueueMessage)

示例

速览消息。


   # Peek at one message at the front of the queue
   msg = queue.peek_messages()

   # Peek at the last 5 messages
   messages = queue.peek_messages(max_messages=5)

   # Print the last 5 messages
   for message in messages:
       print(message.content)

receive_message

从队列的前面删除一条消息。

从队列中检索消息时，响应包括消息内容和pop_receipt值，这是删除消息所必需的。消息不会自动从队列中删除，但在检索消息后，其他客户端在visibility_timeout参数指定的时间间隔内不可见。

如果在本地服务对象上设置了 key-encryption-key 或 resolver 字段，则会在返回之前解密该消息。

receive_message(*, visibility_timeout: int | None = None, **kwargs: Any) -> QueueMessage | None

参数

visibility_timeout: int

如果未指定，则默认值为 30。指定新的可见性超时值（秒），它相对于服务器时间。该值必须大于或等于 1，并且不能大于 7 天。消息的可见性超时不能设置为晚于到期时间的值。 visibility_timeout应设置为小于生存时间值的值。

timeout: int

如果队列为空，则返回“无”消息。

返回类型

QueueMessage,

None

示例

从队列接收一条消息。


   # Pop two messages from the front of the queue
   message1 = queue.receive_message()
   message2 = queue.receive_message()
   # We should see message 3 if we peek
   message3 = queue.peek_messages()[0]

   if not message1 or not message2 or not message3:
       raise ValueError("One of the messages are None.")

   print(message1.content)
   print(message2.content)
   print(message3.content)

receive_messages

从队列的前面删除一个或多个消息。

从队列中检索消息时，响应包括消息内容和pop_receipt值，这是删除消息所必需的。消息不会自动从队列中删除，但在检索消息后，其他客户端在visibility_timeout参数指定的时间间隔内不可见。如果) 设置了max_messages，迭代器将持续提取消息，直到队列为空或max_messages到达 (。

如果在本地服务对象上设置了 key-encryption-key 或 resolver 字段，则消息将在返回之前解密。

receive_messages(*, messages_per_page: int | None = None, visibility_timeout: int | None = None, max_messages: int | None = None, **kwargs: Any) -> ItemPaged[QueueMessage]

参数

visibility_timeout: int

max_messages: int

一个整数，指定要从队列中检索的最大消息数。

timeout: int

返回类似 dict 的 Message 对象的消息迭代器。

返回类型

ItemPaged[QueueMessage]

示例

从队列接收消息。


   # Receive messages one-by-one
   messages = queue.receive_messages()
   for msg in messages:
       print(msg.content)

   # Receive messages by batch
   messages = queue.receive_messages(messages_per_page=5)
   for msg_batch in messages.by_page():
       for msg in msg_batch:
           print(msg.content)
           queue.delete_message(msg)

send_message

将新消息添加到消息队列的后面。

可见性超时指定消息不可见的时间。在超时到期后，消息将变为可见。如果未指定可见性超时，则使用默认值 0。

消息生存时间指定消息在队列中的保留时间。在生存时间到期后，将从队列中删除消息。

如果在本地服务对象上设置了 key-encryption-key 字段，则此方法将在上传之前加密内容。

send_message(content: object | None, *, visibility_timeout: int | None = None, time_to_live: int | None = None, **kwargs: Any) -> QueueMessage

参数

content: Optional[object]

必需

消息内容。允许的类型由服务上设置encode_function确定。默认值为 str。编码的消息大小最多可为 64KB。

visibility_timeout: int

如果未指定，则默认值为 0。指定新的可见性超时值（秒），它相对于服务器时间。该值必须大于或等于 0，并且不能大于 7 天。消息的可见性超时不能设置为晚于到期时间的值。 visibility_timeout应设置为小于生存时间值的值。

time_to_live: int

指定消息的生存时间间隔（秒）。生存时间可以是任意正数，也可以是无穷大为 -1。如果省略此参数，则默认生存时间为 7 天。

timeout: int

QueueMessage 对象。此对象也用内容填充，尽管它不是从服务返回的。

返回类型

QueueMessage

示例

发送消息。


   queue.send_message("message1")
   queue.send_message("message2", visibility_timeout=30)  # wait 30s before becoming visible
   queue.send_message("message3")
   queue.send_message("message4")
   queue.send_message("message5")

set_queue_access_policy

为队列设置存储访问策略（可与共享访问签名一起使用）。

在设置队列的权限时，将替换现有的权限。若要更新队列的权限，请调用 get_queue_access_policy 以提取与队列关联的所有访问策略，修改要更改的访问策略，然后使用完整的数据集调用此函数以执行更新。

建立队列的存储访问策略时，它可能最多需要 30 秒才能生效。在此时间间隔内，与存储访问策略关联的共享访问签名将引发， <xref:azure.storage.queue.HttpResponseError> 直到访问策略变为活动状态。

set_queue_access_policy(signed_identifiers: Dict[str, AccessPolicy], **kwargs: Any) -> None

参数

signed_identifiers: Dict[str, AccessPolicy]

必需

要与队列关联的 SignedIdentifier 访问策略。这最多可以包含 5 个元素。空的听写将清除在服务上设置的访问策略。

timeout: int

示例

在队列上设置访问策略。


   # Create an access policy
   from azure.storage.queue import AccessPolicy, QueueSasPermissions
   access_policy = AccessPolicy()
   access_policy.start = datetime.utcnow() - timedelta(hours=1)
   access_policy.expiry = datetime.utcnow() + timedelta(hours=1)
   access_policy.permission = QueueSasPermissions(read=True)
   identifiers = {'my-access-policy-id': access_policy}

   # Set the access policy
   queue.set_queue_access_policy(identifiers)

set_queue_metadata

设置指定队列上的用户定义的元数据。

元数据以名称-值对的形式与队列相关联。

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

参数

metadata: Optional[Dict[str, str]]

必需

包含要作为元数据与队列关联的名称/值对的 dict。

timeout: int

响应标头的字典。

返回类型

Dict[str, Any]

示例

在队列上设置元数据。


   metadata = {'foo': 'val1', 'bar': 'val2', 'baz': 'val3'}
   queue.set_queue_metadata(metadata=metadata)

update_message

汇报消息的可见性超时。也可以使用此操作更新消息的内容。

此操作可用于持续扩展队列消息的不可见性。如果希望辅助角色“租用”队列消息，此功能非常有用。例如，如果辅助角色调用 receive_messages 并识别出处理消息需要更多时间，则可以持续延长消息的不可见性，直到处理消息。如果在处理期间辅助角色失败，消息最终将再次变为可见，并且另一个辅助角色可以处理该消息。

如果在本地服务对象上设置了 key-encryption-key 字段，则此方法将在上传之前加密内容。

update_message(message: str | QueueMessage, pop_receipt: str | None = None, content: object | None = None, *, visibility_timeout: int | None = None, **kwargs: Any) -> QueueMessage

参数

message: str 或 QueueMessage

必需

标识要更新的消息的消息对象或 ID。

pop_receipt: str

必需

以前的receive_messages或update_message操作调用中返回的有效 pop 回执值。

content: Optional[object]

必需

消息内容。允许的类型由服务上设置encode_function确定。默认值为 str。

visibility_timeout: int

指定新的可见性超时值（秒），它相对于服务器时间。新值必须大于或等于 0，但不能大于 7 天。消息的可见性超时不能设置为晚于到期时间的值。可以更新消息，直到将其删除或已过期。标识要更新的消息的消息的消息对象或消息 ID。

timeout: int

QueueMessage 对象。为方便起见，此对象也填充了内容，尽管服务不会返回它。

返回类型

QueueMessage

示例

更新消息。


   # Send a message
   queue.send_message("update me")

   # Receive the message
   messages = queue.receive_messages()

   # Update the message
   list_result = next(messages)
   message = queue.update_message(
       list_result.id,
       pop_receipt=list_result.pop_receipt,
       visibility_timeout=0,
       content="updated")

属性

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

通过

QueueClient 类

构造函数

参数

示例

方法

clear_messages

参数

示例

close

create_queue

参数

返回

返回类型

例外

示例

delete_message

参数

示例

delete_queue

参数

返回类型

示例

from_connection_string

参数

返回

返回类型

示例

from_queue_url

参数

返回

返回类型

get_queue_access_policy

参数

返回

返回类型

get_queue_properties

参数

返回

返回类型

示例

peek_messages

参数

返回

返回类型

示例

receive_message

参数

返回

返回类型

示例

receive_messages

参数

返回

返回类型

示例

send_message

参数

返回

返回类型

示例

set_queue_access_policy

参数

示例

set_queue_metadata

参数

返回

返回类型

示例

update_message

参数

返回

返回类型

示例

属性

api_version

返回类型

location_mode

返回类型

primary_endpoint