你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
QueueClient 类
要与特定队列交互的客户端。
有关更多可选配置,请 单击此处。
- 继承
-
azure.storage.queue._shared.base_client.StorageAccountHostsMixinQueueClientazure.storage.queue._encryption.StorageEncryptionMixinQueueClient
构造函数
QueueClient(account_url: str, queue_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)
参数
- credential
用于进行身份验证的凭据。 如果帐户 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_messagesupdate_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
参数
- timeout
- int
设置操作的服务器端超时时间(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回
无或 cls 的结果 (响应)
返回类型
例外
示例
创建队列。
queue.create_queue()
delete_message
删除指定的消息。
通常,在客户端使用接收消息操作检索消息后,客户端应处理并删除该消息。 若要删除消息,必须具有消息对象本身或两个数据项:id 和pop_receipt。 ID 是从上一个receive_messages操作返回的。 从最近的 receive_messages 或 update_message 操作返回pop_receipt。 为了使delete_message操作成功,请求中指定的pop_receipt必须与 或 receive_messagesupdate_message 操作返回的pop_receipt匹配。
delete_message(message: str | QueueMessage, pop_receipt: str | None = None, **kwargs: Any) -> None
参数
- timeout
- int
设置操作的服务器端超时时间(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
示例
删除邮件。
# 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
设置操作的服务器端超时时间(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回类型
示例
删除队列。
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
参数
- credential
用于进行身份验证的凭据。 如果帐户 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。
返回
队列客户端。
返回类型
示例
从 连接字符串 创建队列客户端。
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
参数
- credential
用于进行身份验证的凭据。 如果帐户 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。
返回
队列客户端。
返回类型
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 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回
与队列关联的访问策略字典。
返回类型
get_queue_properties
返回指定队列的所有用户定义的元数据。
返回的数据不包括队列的消息列表。
get_queue_properties(**kwargs: Any) -> QueueProperties
参数
- timeout
- int
超时参数以秒表示。
返回
队列的用户定义元数据。
返回类型
示例
获取队列的属性。
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]
参数
- timeout
- int
设置操作的服务器端超时(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回
QueueMessage 对象的列表。 请注意,next_visible_on和pop_receipt不会填充,因为速览不会弹出邮件,并且只能检索已可见的消息。
返回类型
示例
速览消息。
# 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
设置操作的服务器端超时(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回
如果队列为空,则返回“无”消息。
返回类型
示例
从队列接收一条消息。
# 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
如果未指定,则默认值为 30。 指定新的可见性超时值(秒),它相对于服务器时间。 该值必须大于或等于 1,并且不能大于 7 天。 消息的可见性超时不能设置为晚于到期时间的值。 visibility_timeout应设置为小于生存时间值的值。
- max_messages
- int
一个整数,指定要从队列中检索的最大消息数。
- timeout
- int
设置操作的服务器端超时(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回
返回类似 dict 的 Message 对象的消息迭代器。
返回类型
示例
从队列接收消息。
# 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
参数
- visibility_timeout
- int
如果未指定,则默认值为 0。 指定新的可见性超时值(秒),它相对于服务器时间。 该值必须大于或等于 0,并且不能大于 7 天。 消息的可见性超时不能设置为晚于到期时间的值。 visibility_timeout应设置为小于生存时间值的值。
- time_to_live
- int
指定消息的生存时间间隔(秒)。 生存时间可以是任意正数,也可以是无穷大为 -1。 如果省略此参数,则默认生存时间为 7 天。
- timeout
- int
设置操作的服务器端超时(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回
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
设置操作的服务器端超时(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
示例
在队列上设置访问策略。
# 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]
参数
- timeout
- int
设置操作的服务器端超时(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回
响应标头的字典。
返回类型
示例
在队列上设置元数据。
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
参数
- visibility_timeout
- int
指定新的可见性超时值(秒),它相对于服务器时间。 新值必须大于或等于 0,但不能大于 7 天。 消息的可见性超时不能设置为晚于到期时间的值。 可以更新消息,直到将其删除或已过期。 标识要更新的消息的消息的消息对象或消息 ID。
- timeout
- int
设置操作的服务器端超时(以秒为单位)。 有关详细信息,请参阅 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回
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
location_mode
primary_endpoint
primary_hostname
secondary_endpoint
完整的辅助终结点 URL(如果已配置)。
如果不可用,将引发 ValueError。 若要显式指定辅助主机名,请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。
返回类型
例外
secondary_hostname
辅助终结点的主机名。
如果不可用,则此项将为“无”。 若要显式指定辅助主机名,请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。
返回类型
url
此实体的完整终结点 URL,包括 SAS 令牌(如果使用)。
这可以是主终结点,也可以是辅助终结点,具体取决于当前 location_mode。 :returns:此实体的完整终结点 URL,包括 SAS 令牌(如果使用)。 :rtype:str