Azure Service Bus Python客户端库

Azure Service Bus是一个高性能的云托管消息服务，用于在分布式发送者和接收者之间提供实时和容错通信。

服务总线提供多种机制来实现异步高可靠性通信，例如结构化先进先出消息、发布/订阅功能以及随着需求增长轻松扩展的能力。

使用Service Bus客户端库来实现应用程序和服务之间的通信并实现异步消息模式。

• 创建服务总线命名空间、队列、主题和订阅，并修改它们的设置。
• 在您的服务总线通道中发送和接收消息。
• 利用消息锁定、会话和死信功能来实现复杂消息模式。

源代码 | 包（PyPi） | 包（Conda） | API参考文档 | 产品文档 | 示例 | 更新日志

注意：如果您正在使用0.50版或更低版本，并希望迁移到此包的最新版本，请参阅我们的迁移指南，以从Service Bus V0.50迁移到Service Bus V7。

入门指南

安装包

使用pip安装Azure Service Bus客户端库

pip install azure-servicebus

先决条件

要使用此包，您必须具备

• Azure订阅 - 创建免费帐户
• Azure Service Bus - 命名空间和管理凭据
• Python 3.8或更高版本 - 安装Python

如果您需要Azure服务总线命名空间，您可以通过Azure门户创建它。如果您不想使用图形门户UI，您可以通过Cloud Shell或本地运行Azure CLI，使用以下Azure CLI命令创建它

az servicebus namespace create --resource-group <resource-group-name> --name <servicebus-namespace-name> --location <servicebus-namespace-location>

认证客户端

与服务总线的交互从ServiceBusClient类的实例开始。您需要具有带有SAS密钥的连接字符串或命名空间以及其账户密钥之一来实例化客户端对象。以下链接中的示例演示了如何通过两种方法进行认证。

从连接字符串创建客户端

• 要获取所需的凭据，可以在链接示例的顶部找到的Azure CLI片段（为Bash Shell格式化）中，将环境变量填充为服务总线连接字符串（您也可以通过遵循获取服务总线连接字符串的逐步指南在Azure门户中找到这些值）。

使用azure-identity库创建客户端:

• 此构造函数接受您的Service Bus实例的完全限定命名空间以及实现了TokenCredential协议的凭据。在azure-identity包中提供了对TokenCredential协议的实现。完全限定命名空间的格式为<yournamespace.servicebus.windows.net>。
• 要使用azure-identity提供的凭据类型，请安装以下包：pip install azure-identity
• 此外，要使用异步API，您必须首先安装一个异步传输，例如aiohttp：pip install aiohttp
• 当使用Azure Active Directory时，您的主体必须分配一个允许访问服务总线的角色，例如Azure服务总线数据所有者角色。有关使用Azure Active Directory授权与Service Bus的更多信息，请参阅相关文档。

注意：客户端可以不使用上下文管理器进行初始化，但必须通过client.close()手动关闭以避免资源泄露。

关键概念

初始化 ServiceBusClient 之后，您可以与 Service Bus 命名空间中的主要资源类型进行交互，其中可能存在多个命名空间，实际的消息传输在这些命名空间中发生，命名空间通常充当应用程序容器。

• 队列：允许发送和接收消息。通常用于点对点通信。

• 主题：与队列相比，主题更适合发布/订阅场景。主题可以被发送消息，但需要订阅，可以并行存在多个订阅以接收消息。

• 订阅：从主题接收消息的机制。每个订阅都是独立的，并接收发送到主题的每条消息的副本。可以使用规则和过滤器来定制特定订阅接收哪些消息。

有关这些资源的更多信息，请参阅 什么是 Azure Service Bus？。

要与这些资源交互，应熟悉以下 SDK 概念

• ServiceBusClient：用户首先应初始化此对象以连接到 Service Bus 命名空间。要与队列、主题或订阅交互，将从该客户端派生发送器或接收器。

• ServiceBusSender：要向队列或主题发送消息，您将使用 ServiceBusClient 实例的相应 get_queue_sender 或 get_topic_sender 方法，如 这里 所见。

• ServiceBusReceiver：要从队列或订阅接收消息，您将使用 ServiceBusClient 实例的相应 get_queue_receiver 或 get_subscription_receiver 方法，如 这里 所见。

• ServiceBusMessage：在发送时，这是您将构建以包含有效载荷的类型。在接收时，这是您将访问有效载荷的地方。

线程安全

我们不保证 ServiceBusClient、ServiceBusSender 和 ServiceBusReceiver 是线程安全的。我们不推荐在多个线程之间重用这些实例。应用程序的运行方式必须使用线程安全的方式来使用这些类。

示例

以下部分提供了一些代码片段，涵盖了一些最常见的服务总线任务，包括

• 向队列发送消息
• 从队列接收消息
• 从启用会话的队列发送和接收消息
• 与主题和订阅一起工作
• 在接收后解决消息
• 自动续订消息或会话锁

要执行创建和删除队列/主题/订阅等管理任务，请使用可在此处找到的 azure-mgmt-servicebus 库：这里。

请在此处的 示例 目录中找到更多示例，展示常见的 Service Bus 场景，如发送、接收、会话管理和消息处理。

向队列发送消息

注意：请参阅此处参考文档 这里。

此示例向一个已存在的队列发送单条消息和消息数组，该队列通过Azure门户或az命令创建。

from azure.servicebus import ServiceBusClient, ServiceBusMessage
from azure.identity import DefaultAzureCredential

import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_queue_sender(queue_name) as sender:
        # Sending a single message
        single_message = ServiceBusMessage("Single message")
        sender.send_messages(single_message)

        # Sending a list of messages
        messages = [ServiceBusMessage("First message"), ServiceBusMessage("Second message")]
        sender.send_messages(messages)

注意：可以使用ServiceBusSender.schedule_messages()方法或通过在调用ServiceBusSender.send_messages()之前指定ServiceBusMessage.scheduled_enqueue_time_utc来安排消息的延迟投递。

有关安排和取消安排的更多详细信息，请参阅以下示例：这里。

从队列接收消息

要从队列接收消息，您可以通过receiver.receive_messages()进行临时接收，或通过接收器本身进行持久接收。

通过迭代ServiceBusReceiver从队列接收消息

from azure.servicebus import ServiceBusClient
from azure.identity import DefaultAzureCredential

import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    # max_wait_time specifies how long the receiver should wait with no incoming messages before stopping receipt.
    # Default is None; to receive forever.
    with client.get_queue_receiver(queue_name, max_wait_time=30) as receiver:
        for msg in receiver:  # ServiceBusReceiver instance is a generator.
            print(str(msg))
            # If it is desired to halt receiving early, one can break out of the loop here safely.

注意：任何以receive_mode=PEEK_LOCK（这是默认模式，替代模式RECEIVE_AND_DELETE在接收时立即从队列中删除消息）接收的消息都有一个锁，在锁到期之前如果处理时间超过锁持续时间，则必须通过receiver.renew_message_lock来更新锁。有关在后台自动执行此操作的辅助工具，请参阅AutoLockRenewer。锁持续时间在Azure队列或主题本身上设置。

通过ServiceBusReceiver.receive_messages()从队列接收消息

注意：ServiceBusReceiver.receive_messages()通过临时方法调用接收单条消息或受限制的消息列表，而不是从生成器永久接收。它总是返回一个列表。

from azure.servicebus import ServiceBusClient
from azure.identity import DefaultAzureCredential

import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_queue_receiver(queue_name) as receiver:
        received_message_array = receiver.receive_messages(max_wait_time=10)  # try to receive a single message within 10 seconds
        if received_message_array:
            print(str(received_message_array[0]))

    with client.get_queue_receiver(queue_name) as receiver:
        received_message_array = receiver.receive_messages(max_message_count=5, max_wait_time=10)  # try to receive maximum 5 messages in a batch within 10 seconds
        for message in received_message_array:
            print(str(message))

在此示例中，max_message_count声明在达到指定的最大等待时间（以秒为单位）之前尝试接收的最大消息数。

注意：还应注意的是，与接收相比，ServiceBusReceiver.peek_messages()有细微的区别，因为它不会锁定正在查看的消息，因此它们不能被解决。

从启用会话的队列发送和接收消息

注意：请参阅有关会话的参考文档发送和接收。

会话在队列或订阅之上提供先入先出和单接收语义。虽然实际的接收语法相同，但初始化略有不同。

from azure.servicebus import ServiceBusClient, ServiceBusMessage
from azure.identity import DefaultAzureCredential

import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
queue_name = os.environ['SERVICE_BUS_SESSION_QUEUE_NAME']
session_id = os.environ['SERVICE_BUS_SESSION_ID']

credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_queue_sender(queue_name) as sender:
        sender.send_messages(ServiceBusMessage("Session Enabled Message", session_id=session_id))

    # If session_id is null here, will receive from the first available session.
    with client.get_queue_receiver(queue_name, session_id=session_id) as receiver:
        for msg in receiver:
            print(str(msg))

注意：从会话接收的消息不需要像非会话接收器那样更新其锁；相反，锁管理在会话级别进行，可以使用receiver.session.renew_lock()更新会话锁。

与主题和订阅一起工作

注意：请参阅有关主题和订阅的参考文档。

主题和订阅为发送和接收消息提供了队列的替代方案。有关更详细的说明以及它们与队列的区别，请参阅此处的文档。

from azure.servicebus import ServiceBusClient, ServiceBusMessage
from azure.identity import DefaultAzureCredential


import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
topic_name = os.environ['SERVICE_BUS_TOPIC_NAME']
subscription_name = os.environ['SERVICE_BUS_SUBSCRIPTION_NAME']

credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_topic_sender(topic_name) as sender:
        sender.send_messages(ServiceBusMessage("Data"))

    # If session_id is null here, will receive from the first available session.
    with client.get_subscription_receiver(topic_name, subscription_name) as receiver:
        for msg in receiver:
            print(str(msg))

在接收后解决消息

从队列接收时，您可以对接收到的消息执行多项操作。

注意：您只能解决在ServiceBusReceiveMode.PEEK_LOCK模式（这是默认模式）中接收到的ServiceBusReceivedMessage对象。在ServiceBusReceiveMode.RECEIVE_AND_DELETE模式下，接收时会从队列中删除消息。peek_messages()返回的ServiceBusReceivedMessage消息不能解决，因为消息锁没有像上述接收方法那样被获取。

如果消息有如上所述的锁，则如果消息锁已过期，结算将失败。如果处理时间将超过锁的持续时间，则必须在它过期之前通过receiver.renew_message_lock来维持。锁的持续时间是在Azure的队列或主题本身上设置的。请参阅AutoLockRenewer以获取在后台自动执行此操作的辅助工具。

完成

声明消息处理成功完成，从队列中删除消息。

from azure.servicebus import ServiceBusClient
from azure.identity import DefaultAzureCredential


import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_queue_receiver(queue_name) as receiver:
        for msg in receiver:
            print(str(msg))
            receiver.complete_message(msg)

放弃

暂时放弃处理消息，立即将消息返回到队列，由另一个（或同一个）接收器来接收。

from azure.servicebus import ServiceBusClient
from azure.identity import DefaultAzureCredential


import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_queue_receiver(queue_name) as receiver:
        for msg in receiver:
            print(str(msg))
            receiver.abandon_message(msg)

死信

将消息从主队列转移到特殊的“死信子队列”，可以使用带有参数sub_queue=ServiceBusSubQueue.DEAD_LETTER的ServiceBusClient.get_<queue|subscription>_receiver函数访问它，并像任何其他接收器一样消费。请参阅此处的示例。

from azure.servicebus import ServiceBusClient
from azure.identity import DefaultAzureCredential


import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_queue_receiver(queue_name) as receiver:
        for msg in receiver:
            print(str(msg))
            receiver.dead_letter_message(msg)

延迟

延迟与之前的结算方法略有不同。通过将其放置在一边，防止直接从队列接收消息，必须通过调用ServiceBusReceiver.receive_deferred_messages来按顺序号接收（请参阅此处的示例）。

from azure.servicebus import ServiceBusClient
from azure.identity import DefaultAzureCredential


import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_queue_receiver(queue_name) as receiver:
        for msg in receiver:
            print(str(msg))
            receiver.defer_message(msg)

自动续订消息或会话锁

注意：请参阅有关自动锁续期的参考文档。

AutoLockRenewer是一种确保您的消息或会话即使在长时间内仍然锁定的一种简单方法，如果调用receiver.renew_message_lock/receiver.session.renew_lock不切实际或不受欢迎。内部，它不仅仅是创建一个并发看门狗以在对象接近过期时执行锁续期的简写。它应如下使用

• 消息锁自动续期

from azure.servicebus import ServiceBusClient, AutoLockRenewer
from azure.identity import DefaultAzureCredential


import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

# Can also be called via "with AutoLockRenewer() as renewer" to automate closing.
renewer = AutoLockRenewer()
credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_queue_receiver(queue_name) as receiver:
        for msg in receiver.receive_messages():
            renewer.register(receiver, msg, max_lock_renewal_duration=60)
            # Do your application logic here
            receiver.complete_message(msg)
renewer.close()

• 会话锁自动续期

from azure.servicebus import ServiceBusClient, AutoLockRenewer
from azure.identity import DefaultAzureCredential


import os
fully_qualified_namespace = os.environ['SERVICEBUS_FULLY_QUALIFIED_NAMESPACE']
session_queue_name = os.environ['SERVICE_BUS_SESSION_QUEUE_NAME']
session_id = os.environ['SERVICE_BUS_SESSION_ID']

# Can also be called via "with AutoLockRenewer() as renewer" to automate closing.
renewer = AutoLockRenewer()
credential = DefaultAzureCredential()
with ServiceBusClient(fully_qualified_namespace, credential) as client:
    with client.get_queue_receiver(session_queue_name, session_id=session_id) as receiver:
        renewer.register(receiver, receiver.session, max_lock_renewal_duration=300) # Duration for how long to maintain the lock for, in seconds.

        for msg in receiver.receive_messages():
            # Do your application logic here
            receiver.complete_message(msg)
renewer.close()

如果由于任何原因自动续期被中断或失败，可以通过正在续期的对象的auto_renew_error属性观察到，或者通过在续期器初始化时传递回调给on_lock_renew_failure参数。当尝试对指定的对象采取行动（如完成消息）时，也会体现出来。

故障排除

日志记录

• 启用azure.servicebus日志记录器以收集库的跟踪信息。
• 通过在创建客户端时设置logging_enable=True来启用AMQP帧级别的跟踪。

import logging
import sys

handler = logging.StreamHandler(stream=sys.stdout)
logger = logging.getLogger('azure.servicebus')
logger.setLevel(logging.DEBUG)
logger.addHandler(handler)

...

from azure.servicebus import ServiceBusClient

client = ServiceBusClient(..., logging_enable=True)

超时

用户应了解库中的各种超时。

• 10分钟服务端链路关闭：一旦打开，链路将在10分钟空闲后关闭，以防止服务泄漏资源。这应该对用户来说是透明的，但如果您在如此长时间后注意到重新连接发生，这就是原因。对链路执行任何操作（包括管理操作）都将延长此超时。
• max_wait_time：在创建接收器或调用receive_messages()时提供，在无流量后接收消息的时间。这既适用于命令式receive_messages()函数，也适用于在没有消息的情况下，生成器样式接收运行多长时间后退出。传递None（默认值）将无限期等待，直到10分钟的阈值，如果没有采取其他操作。

注意：如果处理消息或会话的时间足够长，导致超时，那么作为手动调用receiver.renew_message_lock/receiver.session.renew_lock的替代方案，可以利用上面详细说明的AutoLockRenewer功能。

常见异常

Service Bus API在azure.servicebus.exceptions中生成以下异常。

• 服务总线连接错误：在连接到服务的过程中发生了错误。这可能是由于临时网络问题或服务问题造成的。建议重试。
• 服务总线授权错误：在授权连接到服务时发生错误。这可能是由于凭据没有执行操作的正确权限造成的。建议检查凭据的权限。
• 服务总线认证错误：在认证连接到服务时发生错误。这可能是由于凭据不正确造成的。建议检查凭据。
• 操作超时错误：这表明服务未在预期时间内对操作做出响应。这可能是由于临时网络问题或服务问题造成的。服务可能已成功或未成功完成请求；状态未知。建议尝试验证当前状态并在必要时重试。
• 消息大小超出限制错误：这表明消息内容大于服务总线帧大小。这可能发生在批量发送过多的服务总线消息或传递给Message体的内容过大时。建议减少批量发送的消息数量或单个ServiceBusMessage的内容大小。
• 消息已解决：这表明解决消息失败。这可能在尝试解决已解决的消息时发生。
• 消息锁定丢失错误：消息的锁定已过期并被释放回队列。需要再次接收以便解决。您应该注意消息的锁定持续时间，并在长时间处理前在过期前续订锁定。AutoLockRenewer可以帮助自动续订消息的锁定。
• 会话锁定丢失错误：会话的锁定已过期。所有已接收但未解决的消息将无法解决。如需再次接收消息，建议重新连接到会话。您应该注意会话的锁定持续时间，并在长时间处理前在过期前续订锁定。AutoLockRenewer可以帮助自动续订会话的锁定。
• 消息未找到错误：尝试接收具有特定序列号的消息。此消息未找到。请确保消息尚未被接收。检查死信队列以查看消息是否已被死信。
• 消息实体未找到错误：与操作关联的实体不存在或已被删除。请确保实体存在。
• 消息实体禁用错误：对已禁用实体的运行时操作请求。请激活该实体。
• 服务总线配额超出错误：消息实体已达到其最大允许大小，或已超出命名空间的连接最大数量。通过从实体或其子队列接收消息来创建实体空间。
• 服务总线服务器忙错误：服务无法在此时刻处理请求。客户端可以等待一段时间，然后重试操作。
• 服务总线通信错误：客户端无法建立到服务总线的连接。请确保提供的主机名正确且主机可达。如果您的代码在具有防火墙/代理的环境中运行，请确保对服务总线域名/IP地址和端口的流量没有被阻止。
• 会话无法锁定错误：尝试连接到具有特定会话ID的会话，但会话当前被另一个客户端锁定。请确保其他客户端已解锁会话。
• 自动锁定续租失败: 在后台尝试续租消息或会话的锁定失败。这可能在由 AutoLockRenewer 使用的接收器被关闭或可续租的锁定已过期时发生。建议通过接收消息或再次连接到会话实体来重新注册可续租的消息或会话。
• 自动锁定续租超时: 分配用于续租消息或会话锁定的超时时间已过期。您可以重新注册希望自动续租锁定的对象或提前延长超时时间。
• 服务总线错误: 所有其他与服务总线相关的错误。它是上述所有错误的根错误类。

请查看异常参考文档，以获取我们常见异常类型的详细描述。

下一步

更多示例代码

请在此处的 示例 目录中找到更多示例，展示常见的 Service Bus 场景，如发送、接收、会话管理和消息处理。

附加文档

有关服务总线服务的更详细文档，请参阅docs.microsoft.com上的服务总线文档。

管理功能和相关文档

对于想要对服务总线执行管理操作的用户（例如创建队列/主题等、更改过滤器规则、枚举实体），请参阅azure-mgmt-servicebus文档以获取API文档。简短的使用示例可以在这里找到。

纯Python AMQP传输和向后兼容性支持

Azure服务总线客户端库现在基于纯Python AMQP实现。《code>uAMQP 已作为必需依赖项删除。

要使用 uAMQP 作为底层传输

1. 使用pip安装 uamqp。

$ pip install uamqp

2. 在客户端构造期间传递 uamqp_transport=True。

from azure.servicebus import ServiceBusClient
connection_str = '<< CONNECTION STRING FOR THE SERVICE BUS NAMESPACE >>'
queue_name = '<< NAME OF THE QUEUE >>'
client = ServiceBusClient.from_connection_string(
    connection_str, uamqp_transport=True
)

注意：在 ServiceBusMessage/ServiceBusMessageBatch/ServiceBusReceivedMessage 上，之前公开了 uamqp.Message 的 message 属性，现已弃用。已引入“Legacy”对象，以帮助简化过渡。

要启用 uamqp 日志记录器以收集底层 uAMQP 库的跟踪

import logging

uamqp_logger = logging.getLogger('uamqp')
uamqp_logger.setLevel(logging.DEBUG)
uamqp_logger.addHandler(handler)

...

from azure.servicebus import ServiceBusClient

client = ServiceBusClient(..., logging_enable=True)

在某些情况下，您可能认为 uamqp 日志记录过于详细。要抑制不必要的日志记录，请将以下代码片段添加到代码顶部

import logging

# The logging levels below may need to be changed based on the logging that you want to suppress.
uamqp_logger = logging.getLogger('uamqp')
uamqp_logger.setLevel(logging.ERROR)

# or even further fine-grained control, suppressing the warnings in uamqp.connection module
uamqp_connection_logger = logging.getLogger('uamqp.connection')
uamqp_connection_logger.setLevel(logging.ERROR)

从源代码构建uAMQP轮

azure-servicebus 依赖于 uAMQP 以实现AMQP协议。大多数主要操作系统都提供了uAMQP轮，在安装 azure-servicebus 时将自动安装。如果打算将 uAMQP 用作 azure-servicebus 的底层AMQP协议实现，大多数主要操作系统都提供了uAMQP轮。

如果您在未提供uAMQP轮的平台运行，请按照以下uAMQP安装指南从源代码安装。

贡献

此项目欢迎贡献和建议。大多数贡献都需要您同意一份贡献者许可协议（CLA），声明您有权并实际上授予我们使用您的贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人会自动确定您是否需要提供CLA，并以适当的方式装饰PR（例如，标签，注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们CLA的存储库中执行一次此操作。

此项目已采用Microsoft开源代码行为准则。有关更多信息，请参阅代码行为准则FAQ或联系opencode@microsoft.com，如有任何其他问题或评论。

发行历史

7.12.3 (2024-09-19)

已修复的错误

• 修复了在长时间运行操作中令牌刷新未发生的问题（35717）
• 修复了使用TokenCredential创建具有转发功能的订阅时导致ResourceNotFoundError的问题（36545）
• 修复了在一个接收器上接收到的消息无法在另一个接收器上通过管理链路解决的问题（35304）
• 解决了接收大消息时分配了过多的链接信用额度的问题（34270）

7.12.2 (2024-05-08)

已修复的错误

• 修复了在使用AmqpOverWebsocket接收时未捕获到WebsocketConnectionClosedException的问题（34859）
• 修复了对typing-extensions的依赖不正确的问题（34869，感谢@YaroBear）。

7.12.1 (2024-03-20)

已修复的错误

• 修复了客户端在连接断开时未重试的问题（34786）
• 修复了客户端无法正确处理服务上的角色实例交换的问题（34820）

其他更改

• 更新了日志记录，以更准确地表示何时发送帧，从而防止客户端空闲超时（#34793）。

7.12.0 (2024-03-06)

新增功能

• 更新了ServiceBusReceiver构造函数中的max_wait_time，允许用户在使用NEXT_AVAILABLE_SESSION时更改会话的默认服务器超时时间65秒。

其他更改

• 将最低的azure-core版本更新到1.28.0。
• 更新了纯Python AMQP网络跟踪日志，按照OpenTelemetry规范将AMQP连接信息中的None值替换为空字符串（#32190）。
• 更新了纯Python AMQP网络跟踪日志的错误日志，在连接关闭时将错误日志级别调整为警告（PR #34504，感谢@RichardOberdieck）。

7.11.4 (2023-11-13)

已修复的错误

• 修复了由azure amqp错误解析两个字符的会话ID的问题。

7.11.3 (2023-10-11)

已修复的错误

• 修复了在RECEIVE_AND_DELETE模式下，prefetch_count未正确传递，导致消息无法按预期接收的问题（#31712，#31711）。

7.11.2 (2023-09-13)

已修复的错误

• 修复了由于阻塞进程导致的连接断开时抛出的错误NoneType object has no attribute 'settle_messages'。

其他更改

• 在azure.servicebus中添加了__contains__方法（PR #30846，感谢@pamelafox）。
  • ServiceBusConnectionStringProperties
  • amqp.AmqpMessageHeader
  • amqp.AmqpMessageProperties
  • management.AccessRights
  • management.NamespaceProperties
  • management.QueueProperties
  • management.TopicProperties
  • management.SubscriptionProperties
  • management.RuleProperties

7.11.1 (2023-07-12)

已修复的错误

• 修复了当服务发送断开连接时抛出的错误end frame received on invalid channel（#30860）
• 修复了客户端关闭和从服务断开连接时抛出的错误link already closed（#30836）

其他更改

• 尝试完成从非会话实体接收到的已过期锁定的消息时抛出的错误已更新为更细粒度的MessageLockLostError，该错误来自超类ServiceBusError。

7.11.0 (2023-06-12)

新增功能

• 在同步和异步的ServiceBusClient上的get_queue_sender、get_queue_receiver、get_topic_sender和get_subscription_receiver方法中添加了一个新的浮点关键字参数socket_timeout。

已修复的错误

• 修复了在套接字写入超时时发送大消息失败的问题（#30425）。
• 修复了由于delivery_id为None而导致解决大消息失败的问题。

其他更改

• 跟踪更新
  • 如果未找到消息应用程序属性中的traceparent消息应用属性，则接收/发送跨度上的跨度链接现在将回退到使用Diagnostic-Id。
  • 即使消息应用程序属性中找不到上下文传播头，现在也会为接收/发送跨度创建跨度链接。
  • 已从所有跨度中删除了component属性。

7.10.0 (2023-05-09)

版本7.10.0是基于纯Python实现的AMQP堆栈的Azure Service Bus客户端库的第一个稳定版本。

新增功能

• 已向同步和异步ServiceBusClient构造函数添加了新的布尔关键字参数uamqp_transport，该参数指示是否使用uamqp库或默认纯Python AMQP库作为底层传输。

破坏性更改

• 以下作为依赖项添加，用于在WebSocket上执行操作
  • websocket-client用于同步
  • aiohttp用于异步
• 从必需依赖项中删除了uAMQP，并将其添加为使用uamqp_transport关键字的可选依赖项。

已修复的错误

• 修复了同步和异步ServiceBusAdministrationClient期望credential具有get_token方法返回类型为bytes的AccessToken.token而不是str的问题，现在与文档一致。
• 修复了在ServiceReceivedBusMessage上返回的raw_amqp_message.header和message.header属性时，默认设置了由服务设置的durable、first_acquirer和priority属性，而不是服务返回的值的问题。
• 修复了ServiceBusReceivedMessage不可序列化的问题（问题编号#27947）。

其他更改

• ServiceBus/ServiceBusMessageBatch/ServiceBusReceivedMessage上的message属性，之前暴露了uamqp.Message/uamqp.BatchMessage，已被弃用。
  • 引入了LegacyMessage/LegacyBatchMessage对象，以帮助促进过渡。
• 从必需依赖项中删除了uAMQP。
• 将uamqp >= 1.6.3作为使用uamqp_transport关键字的可选依赖项添加。
• 更新跟踪（#29995）
  • 向现有跨度添加了更多属性
    • messaging.system - 消息系统（例如，servicebus）
    • messaging.operation - 操作类型（例如，publish、receive或settle）
    • messaging.batch.message_count - 发送或接收的消息数量（如果有多个）
  • 现在将在调用服务的调用上创建跨度，该服务解决消息。
    • 跨度名称将包含解决操作（例如，ServiceBus.complete）
    • 跨度将包含az.namespace、messaging.destination.name、net.peer.name、messaging.system和messaging.operation属性。
  • 现在，所有send跨度都包含对message跨度的链接。现在，message跨度将不再包含对send跨度的链接。

7.10.0b1（2023-04-13）

新增功能

• 已向同步和异步ServiceBusClient构造函数添加了新的布尔关键字参数uamqp_transport，该参数指示是否使用uamqp库或默认纯Python AMQP库作为底层传输。

已修复的错误

• 修复了同步和异步ServiceBusAdministrationClient期望credential具有get_token方法返回类型为bytes的AccessToken.token而不是str的问题，现在与文档一致。
• 修复了在ServiceReceivedBusMessage上返回的raw_amqp_message.header和message.header属性时，默认设置了由服务设置的durable、first_acquirer和priority属性，而不是服务返回的值的问题。

其他更改

• ServiceBus/ServiceBusMessageBatch/ServiceBusReceivedMessage上的message属性，之前暴露了uamqp.Message/uamqp.BatchMessage，已被弃用。
  • 引入了LegacyMessage/LegacyBatchMessage对象，以帮助促进过渡。
• 从必需依赖项中删除了uAMQP。
• 将uamqp >= 1.6.3作为使用uamqp_transport关键字的可选依赖项添加。

7.9.0 (2023-04-11)

破坏性更改

• 默认情况下，现在已禁用同步和异步ServiceBusAdministrationClient的客户端输入验证。这意味着在输入无效的情况下，ServiceBusAdministrationClient不会引发msrest.exceptions.ValidationError。如果服务器拒绝请求，现在可能会引发azure.core.exceptions.HttpResponseError。

已修复的错误

• 修复了azure.servicebus.management中的枚举成员不遵循大写约定的问题。

其他更改

• 已删除所有纯Python AMQP堆栈相关更改，将在下一个版本中重新添加。
• 更新了最低azure-core版本为1.24.0。
• 删除了msrest依赖项。
• 删除了azure-common依赖项。

7.9.0b1（2023-03-09）

新增功能

• 已将来自Service Bus实体的迭代器添加回。

7.8.3 (2023-03-09)

已修复的错误

• 修复了异步添加分布式跟踪属性的方法未被等待的问题（问题编号 #28738）。

7.8.2 (2023-01-10)

已修复的错误

• 修复了一个在将 None 发送到 set_state 而不是清除会话状态时会导致异常的漏洞（问题编号 #27582）。

其他更改

• 将 uAMQP 依赖项更新到 1.6.3。
  • 添加了对 Python 3.11 的支持。

7.9.0a1（2022-10-11）

版本 7.9.0a1 是我们基于纯 Python 实现的 AMQP 堆栈构建 Azure 服务总线客户端库的首次尝试。

破坏性更改

• 以下功能已被暂时移除，将在未来的预览版中重新添加，因为我们致力于稳定发布
  • 从服务总线实体接收迭代器。

其他更改

• 移除了 uAMQP 依赖项。

7.8.1 (2022-10-11)

此版本和所有未来的版本将需要 Python 3.7+。Python 3.6 将不再受支持。

已修复的错误

• 修复了在异步 ServiceBusClient 中，custom_endpoint_address 和 connection_verify 关键字参数未被正确传递的问题。（问题编号 #26015）

7.8.0 (2022-07-06)

此版本将是最后一个官方支持 Python 3.6 的版本，未来的版本将需要 Python 3.7+。

新增功能

• 在 ServiceBusClient 中，get_queue_receiver、get_subscription_receiver、get_queue_sender 和 get_topic_sender 现在接受一个可选的 client_identifier 参数，允许指定相应的发送器或接收器的自定义标识符。在调试期间这可能很有用，因为服务总线将此 ID 与错误关联，有助于更容易地进行关联。
• ServiceBusReceiver 和 ServiceBusSender 添加了 client_identifier 属性，它返回当前实例的 client_identifier。

7.7.0 (2022-06-07)

已修复的错误

• 修复了默认情况下 AMQP 异常可重试的漏洞，如果不满足非可重试条件，则确保重试 InternalServerErrors。

新增功能

• ServiceBusClient 构造函数现在接受可选的 custom_endpoint_address 参数，允许指定与 Service Bus 服务通信时使用的自定义端点，当您的网络不允许与标准 Service Bus 端点通信时很有用。
• ServiceBusClient 构造函数现在接受可选的 connection_verify 参数，允许指定用于验证连接端点身份的 SSL 证书的自定义 CA_BUNDLE 文件的路径。

7.6.1 (2022-04-11)

其他更改

• 通过在 ServiceBusReceiver 的 prefetch_count 设置为 0 且没有活动接收调用时释放消息，改进了接收，这有助于避免接收过期消息和增加消息的投递计数。

7.6.0 (2022-02-10)

新增功能

• 引入了 ServiceBusMessageState 枚举，可以假定 active、scheduled 或 deferred 的值。
• 在 ServiceBusReceivedMessage 中添加了 state 属性。

7.5.0 (2022-01-12)

此版本和所有未来的版本将需要 Python 3.6+。Python 2.7 将不再受支持。

新增功能

• 添加了对固定（线性）重试退避的支持。
  • Sync/async ServiceBusClient 构造函数和 from_connection_string 接受 retry_mode 作为关键字参数。
• 添加了新的枚举类 ServiceBusSessionFilter，它是现有 NEXT_AVAILABLE_SESSION 值的类型。

已修复的错误

• 修复了当使用 datetime.timedelta 设置 ServiceBusMessage.time_to_live 时，应该尊重 total_seconds 的问题（PR #21869，感谢 @jyggen）。

其他更改

• 改进了令牌刷新时间，以防止在令牌即将过期时阻塞主流程。
• 将 uAMQP 依赖项更新到 1.5.1。

7.4.0 (2021-11-09)

新增功能

• 正式支持在 ServiceBusAdministrationClient 中创建和更新大消息大小的队列和主题。此功能仅适用于 Premium 层服务总线。
  • ServiceBusAdministrationClient 上的 create_queue、create_topic、update_queue 和 update_topic 方法现在接受一个新关键字参数 max_message_size_in_kilobytes。
  • QueueProperties 和 TopicProperties 现在有一个新的实例变量 max_message_size_in_kilobytes。
• ServiceBusAdministrationClient 的构造函数以及 ServiceBusAdministrationClient.from_connection_string 现在接受关键字参数 api_version 以配置服务总线 API 版本。支持的服务版本是 "2021-05" 和 "2017-04"。
• 添加了新的枚举类 azure.servicebus.management.ApiVersion 以表示支持的服务总线 API 版本。

已修复的错误

• 修复了 ServiceBusReceiver 无法连接到会话实体（会话ID为空字符串）的bug。
• 修复了 ServiceBusMessage.partition_key 无法正确解析空字符串的bug。

7.4.0b1 (2021-10-06)

新增功能

• 在 ServiceBusAdministrationClient 中添加了对创建和更新大消息大小的队列和主题的支持。此功能仅适用于高级别的Service Bus。
  • ServiceBusAdministrationClient 上的 create_queue、create_topic、update_queue 和 update_topic 方法现在接受一个新关键字参数 max_message_size_in_kilobytes。
  • QueueProperties 和 TopicProperties 现在有一个新的实例变量 max_message_size_in_kilobytes。

7.3.4 (2021-10-06)

其他更改

• 更新了uAMQP依赖到1.4.3。
  • 添加了对Python 3.10的支持。
  • 修复了win32 socketio和tlsio中的内存泄漏（问题#19777）。
  • 修复了将AMQPValue转换为字符串过程中的内存泄漏（问题#19777）。

7.3.3 (2021-09-08)

已修复的错误

• 改进了 ServiceBusClient 的内存使用，当不再存在对发送器或接收器的强引用时，自动丢弃其处理器集中的 ServiceBusSender 或 ServiceBusReceiver。
• 在续订锁期间降低了 azure.servicebus.AutoLockRenewer 的CPU负载。

7.3.2 (2021-08-10)

已修复的错误

• 修复了 azure.servicebus.aio.AutoLockRenewer 在未注册任何消息时释放会话崩溃的bug（问题#19642）。
• 修复了 azure.servicebus.AutoLockRenewer 只支持每次自动续订 max_workers 个消息/会话的bug（问题#19362）。

7.3.1 (2021-07-07)

修复了

• 修复了当设置 ServiceBusMessage.partition_key 时，输入值不应与None的 session_id 进行验证的bug（PR #19233，感谢 @bishnu-shb）。
• 修复了在Ubuntu 20.04上设置 ServiceBusMessage.time_to_live 导致 OverflowError 错误的bug。
• 修复了 AmqpAnnotatedProperties.creation_time 和 AmqpAnnotatedProperties.absolute_expiry_time 应该以毫秒为单位而不是秒为单位计算的bug。
• 更新了uAMQP依赖到1.4.1。
  • 修复了在MessageProperties上的creation_time、absolute_expiry_time和group_sequence属性应与Python 2.7上的整型类型兼容的bug。

7.3.0 (2021-06-08)

新功能

• 支持发送AMQP注解消息，允许完全访问AMQP消息字段，现已GA。
  • 引入了新的命名空间 azure.servicebus.amqp。
  • 引入了新的类 azure.servicebus.amqp.AmqpMessageHeader 和 azure.servicebus.amqp.AmqpMessageProperties 以访问amqp头和属性。

从7.2.0b1起的重大更改

• 将 azure.servicebus.AMQPAnnotatedMessage 重命名为 azure.servicebus.amqp.AmqpAnnotatedMessage 并移动位置。
• 将 azure.servicebus.AMQPMessageBodyType 重命名为 azure.servicebus.amqp.AmqpMessageBodyType 并移动位置。
• AmqpAnnotatedMessage.header 返回 azure.servicebus.amqp.AmqpMessageHeader 而不是 uamqp.message.MessageHeader。
• AmqpAnnotatedMessage.properties 返回 azure.servicebus.amqp.AmqpMessageProperties 而不是 uamqp.message.MessageProperties。
• ServiceBusMessage 和 ServiceBusReceivedMessage 上的 raw_amqp_message 现在是只读属性而不是实例变量。

错误修复

• 修复了 ServiceBusReceiver 迭代器在从连接错误恢复后停止迭代的bug（问题#18795）。

7.2.0 (2021-05-13)

在7.2.0b1中引入的与AMQPAnnotatedMessage相关的预览功能不包括在本版本中。

新功能

• 添加了对使用 azure.core.credentials.AzureNamedKeyCredential 作为客户端认证凭据的支持。
• 使用 azure.core.credentials.AzureSasCredential 作为客户端认证凭据的支持现已GA。
• ServiceBusAdministrationClient.update_* 方法现在接受关键字参数以覆盖模型实例中指定的属性。

错误修复

• 修复了当属性是实体而不是完整路径时，update_queue 和 update_subscription 方法会修改模型实例的 forward_to 和 forward_dead_lettered_messages_to 属性的bug。
• 改进了 ServiceBusMessage 和 ServiceBusReceivedMessage 上的 repr 以显示更有意义的文本。
• 更新了uAMQP依赖到1.4.0。
  • 修复了在链接附加过程中存在内存泄漏的bug，其中源和目标cython对象没有正确释放（问题#15747）。
  • 改进了管理操作回调，不将非AMQP_TYPE_STRING类型的描述值解析为字符串（问题#18361）。

注意

• 更新了azure-core依赖到1.14.0。

7.2.0b1 (2021-04-07)

新功能

• 添加了对使用azure.core.credentials.AzureSasCredential作为客户端认证凭据的支持。
• 添加了对发送AMQP注释消息的支持，允许完全访问AMQP消息字段。现在azure.servicebus.AMQPAnnotatedMessage是公开的，并且可以用于发送。
• 添加了新的枚举类azure.servicebus.AMQPMessageBodyType来表示消息的消息体类型，包括
  • DATA：消息体由一个或多个数据部分组成，每个部分包含不透明的二进制数据。
  • SEQUENCE：消息体由一个或多个序列部分组成，每个部分包含任意数量的结构化数据元素。
  • VALUE：消息体由一个AMQP值部分组成，该部分包含一个AMQP值。
• 在azure.servicebus.ServiceBusMessage和azure.servicebus.ReceivedMessage上添加了新的属性body_type，它返回azure.servicebus.AMQPMessageBodyType。

7.1.1 (2021-04-07)

本版本和所有未来版本将需要Python 2.7或Python 3.6+，Python 3.5不再受支持。

新功能

• 更新了同步和异步ServiceBusAdministrationClient上的create_queue、update_queue、create_subscription和update_subscription方法中的forward_to和forward_dead_lettered_messages_to参数，使其接受实体，而不仅仅是完整路径。如果传递了实体，则假定该实体位于用于构建ServiceBusAdministrationClient的同一命名空间中。

错误修复

• 将uAMQP依赖项更新到1.3.0。
  • 修复了在底层套接字连接丢失时发送大型消息触发段错误的问题（#13739，#14543）。
  • 修复了链路流控制中的错误，其中链路信用额和交付计数应根据每条消息而不是每帧传输来计算（#16934）。

7.1.0 (2021-03-09)

本版本将是最后一个官方支持Python 3.5的版本，未来版本将需要Python 2.7或Python 3.6+。

新功能

• 更新了以下方法，以便接受列表和Mapping表示的单个实例作为相应的强类型对象参数（PR #14807，感谢@bradleydamato）
  • ServiceBusAdministrationClient上的update_queue、update_topic、update_subscription和update_rule分别接受QueueProperties、TopicProperties、SubscriptionProperties和RuleProperties的Mapping表示。
  • ServiceBusSender的同步和异步版本上的send_messages和schedule_messages接受ServiceBusMessage的Mapping表示的列表或单个实例。
  • ServiceBusMessageBatch上的add_message现在接受ServiceBusMessage的Mapping表示。

错误修复

• 由于连接上10分钟内没有活动而导致的uamqp.errors.LinkForceDetach错误引起的操作失败现在将内部重试，除了会话接收器的情况。
• 具有条件代码amqp:unknown-error的uamqp.errors.AMQPConnectionError错误现在分类为ServiceBusConnectionError而不是通用的ServiceBusError。
• 在ServiceBusManagementClient上的update_*方法在遇到不支持输入类型的情况下将引发TypeError而不是AttributeError。

7.0.1 (2021-01-12)

错误修复

• forward_to和forward_dead_lettered_messages_to在用于队列和订阅的ServiceBusAdministrationClient中不再导致授权错误（#15543）。
• 将uAMQP依赖项更新到1.2.13。
  • 修复了macOS无法检测网络错误的问题（#15473）。
  • 修复了在连接建立期间uamqp.ReceiveClient和uamqp.ReceiveClientAsync接收消息的问题（#15555）。
  • 修复了在macOS上使用Clang 12时连接建立触发不可识别选择器异常的问题（#15567）。
  • 修复了访问消息属性时，当底层的C字节为NULL时触发段错误的问题（#15568）。

7.0.0 (2020-11-23)

注意： 这是 azure-servicebus 包的GA（通用可用）版本，推出在先前的预览版本之上构建的官方API表面区域。建议从 v0.50 迁移的用户查看迁移指南。

新功能

• 现在可以将 sub_queue 和 receive_mode 作为有效的字符串（由它们各自的枚举类型定义）以及它们的枚举形式传递，以构建 ServiceBusReceiver。
• 增加了对发送、接收和计划场景的分布式跟踪的支持。

破坏性更改

• ServiceBusSender 和 ServiceBusReceiver 现在不再可重用，并在尝试在已关闭的处理程序上操作时引发 ValueError。
• 将 ReceiveMode 重命名为 ServiceBusReceiveMode，将 SubQueue 重命名为 ServiceBusSubQueue，并将它们的枚举值从整数转换为可读的字符串。
• 将枚举值 DeadLetter 重命名为 DEAD_LETTER，TransferDeadLetter 重命名为 TRANSFER_DEAD_LETTER，PeekLock 重命名为 PEEK_LOCK，ReceiveAndDelete 重命名为 RECEIVE_AND_DELETE，以符合未来的SDK指南。
• 现在，如果提供空的消息列表或空批次，则 send_messages、schedule_messages、cancel_scheduled_messages 和 receive_deferred_messages 将执行无操作（no-op）而不是引发 ValueError。
• ServiceBusMessage.amqp_annotated_message 已重命名为 ServiceBusMessage.raw_amqp_message，以与其他SDK保持一致。
• 根据服务定义的错误条件重新设计错误层次结构。
  • 由于它是客户端验证，因此 MessageAlreadySettled 现在从 ValueError 继承，而不是从 ServiceBusMessageError 继承。
  • 已删除 NoActiveSession，现在它被 OperationTimeoutError 替换，因为客户端在尝试连接到任何可用会话时超时。
  • 已删除 ServiceBusMessageError，因为基于错误条件的异常提供全面错误信息。
  • 已删除 MessageSettleFailed，因为基于错误条件的异常提供全面错误信息。
  • 已删除 MessageSendFailed，因为基于错误条件的异常提供全面错误信息。
  • 将 MessageContentTooLarge 重命名为 MessageSizeExceededError，以与服务的定义保持一致。
  • 将 MessageLockExpired 重命名为 MessageLockLostError，以与服务的定义保持一致。
  • 将 SessionLockExpired 重命名为 SessionLockLostError，以与服务的定义保持一致。
  • 引入了 MessageNotFoundError，当请求的消息找不到时将引发此异常。
  • 引入了 MessagingEntityNotFoundError，当服务总线服务无法找到服务总线资源时将引发此异常。
  • 引入了 MessagingEntityDisabledError，当消息实体被禁用时将引发此异常。
  • 引入了 MessagingEntityAlreadyExistsError，当在相同命名空间下存在具有相同名称的实体时将引发此异常。
  • 引入了 ServiceBusQuotaExceededError，当与Azure服务总线服务交互时，如果服务总线资源超出限制，将引发此异常。
  • 引入了 ServiceBusServerBusyError，当Azure服务总线服务在响应客户端请求执行操作时报告它正忙时将引发此异常。
  • 引入了 ServiceBusCommunicationError，当在交互Azure服务总线服务时遇到通用通信错误时将引发此异常。
  • 引入了 SessionCannotBeLockedError，当请求的会话无法被锁定时将引发此异常。
• 在特定用例上引入了新的客户端验证。
  • ServiceBusMessage 现在在提供无效的主体类型时将引发 TypeError。有效的主体是字符串、字节和 None。列表不再被接受，因为它们只是简单地将内容连接起来。
  • 现在将 receive_mode 设置为不适当的值将引发 ValueError 而不是 TypeError，以支持可扩展的枚举。
  • 将 ServiceBusMessage.partition_key 设置为与消息实例上的 session_id 不同的值现在将引发 ValueError。
  • ServiceBusClient.get_queue/topic_sender 和 ServiceBusClient.get_queue/subscription_receiver 现在如果 queue_name 或 topic_name 与用于构建 ServiceBusClient 的连接字符串中的 EntityPath 不匹配，将引发 ValueError。
  • 处理已窥视的消息将引发 ValueError。
  • 在 RECEIVE_AND_DELETE 接收模式下处理消息或续订消息的锁将引发 ValueError。
  • 在 ServiceBusMessage 上设置超过 128 个字符的 session_id、reply_to_session_id、message_id 和 partition_key 将引发 ValueError。
• 目前将 ServiceBusReceiver.get_streaming_message_iter 设为内部使用，以便在提交向后兼容性之前评估使用模式；可以通过迭代接收器本身以等效方式迭代消息。

错误修复

• 默认情况下，现在使用 ServiceBusAdministrationClient.create_rule 创建 TrueRuleFilter 规则。
• 现在支持带有可删除空格或协议头（例如 'sb://'）的 FQDN 和连接字符串。
• 在使用 auto_lock_renewer 参数和一个会话接收器的同时使用 ReceiveMode.ReceiveAndDelete 将不再因为无法将消息注册到续订器而失败。

7.0.0b8（2020-11-05）

新功能

• 以下操作已添加对 timeout 参数的支持
  • ServiceBusSender：send_messages、schedule_messages 和 cancel_scheduled_messages
  • ServiceBusReceiver：receive_deferred_messages、peek_messages 和 renew_message_lock
  • ServiceBusSession：get_state、set_state 和 renew_lock
• azure.servicebus.exceptions.ServiceBusError 现在继承自 azure.core.exceptions.AzureError。
• 添加了一个 parse_connection_string 方法，该方法将连接字符串解析为包含其组成部分的属性包。
• 在 get_queue_receiver 和 get_subscription_receiver 调用上添加了对 auto_lock_renewer 参数的支持，以便自动注册消息和会话进行自动续订。

破坏性更改

• 将 AutoLockRenew 重命名为 AutoLockRenewer。
• 已删除类 ServiceBusSessionReceiver，现在它统一在类 ServiceBusReceiver 中。
  • 已删除方法 ServiceBusClient.get_queue_session_receiver 和 ServiceBusClient.get_subscription_session_receiver。
  • ServiceBusClient.get_queue_receiver 和 ServiceBusClient.get_subscription_receiver 现在接受关键字参数 session_id，当获取会话实体的接收器时必须设置。
• ServiceBusError.__init__ 接收的参数 inner_exception 现在已重命名为 error。
• 将 azure.servicebus.exceptions.MessageError 重命名为 azure.servicebus.exceptions.ServiceBusMessageError。
• 已删除错误 azure.servicebus.exceptions.ServiceBusResourceNotFound，因为现在当使用 ServiceBusAdministrationClient 时，如果 Service Bus 资源不存在，将引发 azure.core.exceptions.ResourceNotFoundError。
• 将 Message 重命名为 ServiceBusMessage。
• 将 ReceivedMessage 重命名为 ServiceBusReceivedMessage。
• 将 BatchMessage 重命名为 ServiceBusMessageBatch。
  • 在类中将方法 add 重命名为 add_message。
• 已删除类 PeekedMessage。
• 在模块 azure.servicebus.aio 下删除了类 ReceivedMessage。
• 将 ServiceBusSender.create_batch 重命名为 ServiceBusSender.create_message_batch。
• 异常 MessageSendFailed、MessageSettleFailed 和 MessageLockExpired 现在继承自 azure.servicebus.exceptions.ServiceBusMessageError。
• ServiceBusSession 中的 get_state 现在返回 bytes 而不是 string。
• ServiceBusReceiver.receive_messages/get_streaming_message_iter 和 ServiceBusClient.get_<queue/subscription>_receiver 现在如果给定的 max_wait_time 小于或等于 0，将引发 ValueError。
• 将消息处理方法从 ServiceBusMessage 移至 ServiceBusReceiver。
  • 使用 ServiceBusReceiver.complete_message 代替 ServiceBusReceivedMessage.complete 来完成消息。
  • 使用 ServiceBusReceiver.abandon_message 代替 ServiceBusReceivedMessage.abandon 来放弃消息。
  • 使用 ServiceBusReceiver.defer_message 代替 ServiceBusReceivedMessage.defer 来延迟消息。
  • 使用ServiceBusReceiver.dead_letter_message代替ServiceBusReceivedMessage.dead_letter来将消息放入死信队列。
• 消息结算方法（complete_message、abandon_message、defer_message和dead_letter_message）以及使用amqp管理链接请求的方法（如schedule_messages、received_deferred_messages等）现在除了抛出MessageSettleFailed和ServiceBusError异常外，还会抛出更具体的异常。
• 将消息renew_lock方法从ServiceBusMessage移至ServiceBusReceiver。
  • 将ServiceBusReceivedMessage.renew_lock更改为ServiceBusReceiver.renew_message_lock。
• AutoLockRenewer.register现在以ServiceBusReceiver作为位置参数。
• 从ServiceBusMessage中移除了对encoding的支持。
• 为跨SDK一致性，将ServiceBusMessage.amqp_message重命名为ServiceBusMessage.amqp_annotated_message。
• 现在在ServiceBusAdministrationClient中，所有name参数都精确指定，如queue_name或rule_name。
• ServiceBusMessage.via_partition_key不再公开，因为它没有外部用途，目前仍在等待完整的事务实现。如果需要，仍可以在ServiceBusMessage.amqp_annotated_message.annotations中访问其底层值。
• 将ServiceBusMessage.properties重命名为ServiceBusMessage.application_properties，以与服务的术语保持一致。
• 将子客户端（ServiceBusSender和ServiceBusReceiver）的from_connection_string初始化器设置为内部使用，直到需要。客户端应从根ServiceBusClient初始化。
• ServiceBusMessage.label已重命名为ServiceBusMessage.subject。
• ServiceBusMessage.amqp_annotated_message的类型已从AMQPMessage更改为AMQPAnnotatedMessage。
• AutoLockRenewer的timeout参数已重命名为max_lock_renew_duration。
• 尝试自动续订不可续订的消息（例如，在ReceiveAndDelete模式下接收的消息），或在ReceiveAndDelete接收器上配置自动自动续订，将引发ValueError。
• ServiceBusReceiver.receive_messages上参数max_message_count的默认值现在为1，而不是None。如果给定的值小于或等于0，将引发ValueError。

错误修复

• 已更新uAMQP依赖到1.2.12。
  • 增加了对Python 3.9的支持。
  • 修复了amqp消息的footer和delivery_annotation未编码到输出负载中的问题。

7.0.0b7 (2020-10-05)

破坏性更改

• 将除ReceiveMode之外的任何类型作为参数receive_mode传递现在将抛出TypeError而不是AttributeError。
• 管理客户端调用现在仅接受实体名称，而不是同时接受<Entity>Descriptions，以减少对正在操作的实体的歧义。如果参数类型不正确（非字符串），将抛出TypeError。
• AMQPMessage（Message.amqp_message）属性现在是只读的，对这些属性的更改不会反映在底层消息中。这可能会在GA之前发生变化。

7.0.0b6 (2020-09-10)

新功能

• renew_lock()现在返回锁将过期的时间的UTC datetime。
• receive_deferred_messages()现在可以接受单个序列号以及序列号列表。
• 现在可以连续发送两次消息。
• 与from_connection_string方法一起使用的连接字符串现在支持使用SharedAccessSignature密钥代替sharedaccesskey和sharedaccesskeyname，将正确构造的令牌的字符串作为值。
• 通过Message.amqp_message公开内部AMQP消息属性（标题、页脚、注释、属性等）。

破坏性更改

• 将prefetch重命名为prefetch_count。
• 将ReceiveSettleMode枚举重命名为ReceiveMode，并将相应的mode参数重命名为receive_mode。
• retry_total、retry_backoff_factor和retry_backoff_max现在在ServiceBusClient级别定义，并由从它创建的发送器和接收器继承。
• 不再在azure.servicebus模块中导出NEXT_AVAILABLE。一个空的session_id就足够了。
• 将参数 message_count 重命名为 max_message_count，因为在 peek_messages() 和 receive_messages() 方法中可能存在的消息更少。
• 将 PeekMessage 重命名为 PeekedMessage。
• 将 get_session_state() 和 set_session_state() 分别重命名为 get_state() 和 set_state()。
• 将方法 dead_letter() 中的参数 description 重命名为 error_description。
• 在 AuthorizationRule 和 NamespaceProperties 中，将属性 created_time 和 modified_time 分别重命名为 created_at_utc 和 modified_at_utc。
• 从 SqlRuleFilter 和 SqlRuleAction 中移除了参数 requires_preprocessing。
• 从 NamespaceProperties 中移除了属性 namespace_type。
• 将 ServiceBusManagementClient 重命名为 ServiceBusAdministrationClient。
• 尝试在非 Message、BatchMessage 或 Message 列表对象上调用 send_messages，现在将抛出 TypeError 而不是 ValueError。
• 发送消息两次将不再导致抛出 MessageAlreadySettled 异常。
• ServiceBusClient.close() 现在将关闭派生的发送者和接收者。
• 尝试使用不同的连接字符串实体和指定的实体（例如，queue_name）初始化发送者或接收者将导致出现 AuthenticationError。
• 从管理实体中移除了 is_anonymous_accessible。
• 从 create_queue 和 QueueProperties 中移除了 support_ordering。
• 从 create_topic 和 TopicProperties 中移除了 enable_subscription_partitioning。
• 已移除 get_dead_letter_[queue,subscription]_receiver()。要连接到死信队列，请使用 get_[queue,subscription]_receiver() 提供的 sub_queue 参数，该参数的值来自 SubQueue 枚举。
• 不再导出 ServiceBusSharedKeyCredential。
• 将 entity_availability_status 重命名为 availability_status。

7.0.0b5 (2020-08-10)

新功能

• 为 Message、PeekMessage 和 ReceivedMessage 添加了新的属性：content_type、correlation_id、label、message_id、reply_to、reply_to_session_id 和 to。请参阅文档字符串以获取更多信息。
• 为 PeekMessage 和 ReceivedMessage 添加了新的属性：enqueued_sequence_number、dead_letter_error_description、dead_letter_reason、dead_letter_source、delivery_count 和 expires_at_utc。请参阅文档字符串以获取更多信息。
• 支持通过 ServiceBusSender.send_messages 发送接收到的消息。
• 为 AutoLockRenew.register 添加了参数 on_lock_renew_failure，它接受一个回调，当锁非故意丢失（例如，不是通过结算、关闭或自动锁续期持续时间完成）时调用。
• 为 CorrelationFilter.properties 添加了新的支持值类型：int、float、datetime 和 timedelta。
• 为 SqlRuleFilter 和 SqlRuleAction 添加了新的属性 parameters 和 requires_preprocessing。
• 添加了一个显式方法来获取连续接收迭代器，get_streaming_message_iter()，可以指定 max_wait_time 作为覆盖。

破坏性更改

• 在 Message 上移除/重命名了几个属性和实例变量（这些更改也应用于继承的 Message 类型 PeekMessage 和 ReceivedMessage）。
  • 将属性 user_properties 重命名为 properties。
    • 表示 AMQP 属性的原实例变量 properties 现在成为内部实例变量 _amqp_properties。
  • 移除了属性 enqueue_sequence_number。
  • 移除了属性 annotations。
  • 移除了实例变量 header。
• 在 PeekMessage 和 ReceivedMessage 上移除了几个属性和实例变量。
  • 在两个类型上移除了属性 partition_id。
  • 在两个类型上移除了属性 settled。
  • 在两个类型上移除了实例变量 received_timestamp_utc。
  • 在 PeekMessage 上移除了属性 settled。
  • 在 ReceivedMessage 上移除了属性 expired。
• AutoLockRenew.sleep_time 和 AutoLockRenew.renew_period 已经被更改为内部变量 _sleep_time 和 _renew_period，因为不期望用户需要与其交互。
• AutoLockRenew.shutdown 现在为 AutoLockRenew.close，以与其他等效行为保持一致。
• QueueDescription、TopicDescription、SubscriptionDescription 和 RuleDescription 已重命名为 QueueProperties、TopicProperties、SubscriptionProperties 和 RuleProperties。
• QueueRuntimeInfo、TopicRuntimeInfo 和 SubscriptionRuntimeInfo 已重命名为 QueueRuntimeProperties、TopicRuntimeProperties 和 SubscriptionRuntimeProperties。
• 已从 ServiceBusManagementClient 的 create_queue、create_topic、create_subscription 和 create_rule 中移除参数 queue、topic、subscription 和 rule，并添加了 name 参数和队列属性、主题属性、订阅属性和规则属性的键控参数。
• 已从 ServiceBusManagementClient 的 update_queue 和 update_topic 中移除与模型类属性相关的键控参数。这是为了鼓励使用从 create_*、list_* 或 get_* 操作返回的模型类实例，以确保其正确填充。属性仍可修改。
• 模型类 QueueProperties、TopicProperties、SubscriptionProperties 和 RuleProperties 要求所有参数在创建时都必须存在。这是为了防止由于缺少部分更新而要求指定所有属性。
• get_<queue/subscription>_receiver() 中的 idle_timeout 已重命名为 max_wait_time，以与其他命名保持一致。
• 已更新 uAMQP 依赖项到 1.2.10，这样当生成器超时时，接收器不会关闭，并且可以再次接收。

7.0.0b4 (2020-07-06)

新功能

• 添加了对主题、订阅和规则的管理支持。
• receive_messages()（以前为 receive()）现在支持在无需在 ServiceBusReceiver 初始化期间设置 prefetch 参数的情况下接收一批消息（max_batch_size > 1）。

错误修复

• 修复了同步 AutoLockRenew 无法及时关闭的问题。
• 修复了异步 AutoLockRenew 不支持上下文管理器的问题。

破坏性更改

• receive()、peek()、schedule() 和 send() 已重命名为 receive_messages()、peek_messages()、schedule_messages() 和 send_messages()，以与其他服务总线 SDK 保持一致。
• 如果 max_batch_size 小于在 ServiceBusReceiver 初始化期间设置的 prefetch 参数，则 receive_messages()（以前为 receive()）不再引发 ValueError。

7.0.0b3 (2020-06-08)

新功能

• 添加了对队列实体的管理支持。
  • 使用 azure.servicebus.management.ServiceBusManagementClient（对于 aio 使用 azure.servicebus.management.aio.ServiceBusManagementClient）来创建、更新、删除、列出队列以及获取 ServiceBus 命名空间下队列的设置以及运行时信息。
• 在 ServiceBusClient 中添加了 get_queue_deadletter_receiver 和 get_subscription_deadletter_receiver 方法，以获取目标实体的死信子队列的 ServiceBusReceiver。

错误修复

• 已更新 uAMQP 依赖项到 1.2.8。
  • 修复了在死信消息时未设置原因和描述的问题。

7.0.0b2 (2020-05-04)

新功能

• 在 ServiceBusClient 中添加了 get_topic_sender 方法，以获取特定主题的 ServiceBusSender。
• 在 ServiceBusClient 中添加了 get_subscription_receiver 方法，以获取特定主题下的订阅的 ServiceBusReceiver。
• 添加了对消息调度和已调度消息取消的支持。
  • 使用 ServiceBusSender.schedule(messages, schedule_time_utc) 进行消息调度。
  • 使用 ServiceBusSender.cancel_scheduled_messages(sequence_numbers) 进行已调度消息取消。
• 如果消息适合单个批次，则 ServiceBusSender.send() 可以在单个调用中发送消息列表。如果它们不适合，则抛出 ValueError。
• 如果内容过大，则 BatchMessage.add() 和 ServiceBusSender.send() 会引发 MessageContentTooLarge。
• ServiceBusReceiver.receive() 方法如果其参数 max_batch_size 大于 ServiceBusClient 的参数 prefetch，则会引发 ValueError。
• 增加了异常类 MessageError、MessageContentTooLarge 和 ServiceBusAuthenticationError。
  • MessageError：在发送有问题的消息时，例如已发送的消息或过大的消息。
  • MessageContentTooLarge：在发送过大的消息时。它是 ValueError 和 MessageError 的子类。
  • ServiceBusAuthenticationError：在服务认证失败时。
• 已移除异常类 InvalidHandlerState。

错误修复

• 修复了 http_proxy 和 transport_type 在 ServiceBusClient 中未能正确传递到 Sender/Receiver 创建的问题。
• 已将 uAMQP 依赖更新到 1.2.7。
  • 修复了在 MacOS 上设置 tlsio 证书的 bug。#7201
  • 修复了在 MacOS 上设置 ServiceBusClient 中的 logging_enable 为 True 时导致的段错误。

破坏性更改

• 会话接收器现在通过其自己的顶级函数创建，例如 get_queue_session_receiver 和 get_subscription_session_receiver。非会话接收器不再将 session_id 作为参数。
• ServiceBusSender.send() 不再接受超时参数，因为这与创建客户端时提供的重试选项是冗余的。
• 已从模块 azure.servicebus 中移除异常导入。请从 azure.servicebus.exceptions 导入。
• ServiceBusSender.schedule() 已交换了参数 schedule_time_utc 和 messages 的顺序，以更好地与 send() 语法保持一致。

7.0.0b1 (2020-04-06)

7.0.0b1 是我们努力创建一个用户友好且符合 Python 生态系统的客户端库的预览版。这次更新中大多数更改的原因可以在 Python 的 Azure SDK 设计指南中找到。有关更多信息，请访问 https://aka.ms/azure-sdk-preview1-python。

• 注意：目前此版本中并非所有历史功能都存在。主题、订阅、计划、死信管理等功能将在未来的预览版本中逐步添加。

新功能

• 在创建 ServiceBusClient 时增加了新的配置参数。
  • credential：用于认证的凭据对象，该对象实现了获取令牌的 TokenCredential 接口。
  • http_proxy：包含代理设置的字典。
  • 有关配置参数的详细信息，请参阅 ServiceBusClient 中的文档字符串或参考文档。
• 增加了使用 Azure Identity 凭据进行认证的支持。
• 增加了重试策略的支持。
• 增加了对 http 代理的支持。
• 手动调用 reconnect 不再必要，现在它将隐式执行。
• 手动调用 open 不再必要，现在它将隐式执行。
  • 注意：如果不使用上下文管理器，则仍然需要调用 close()，以避免连接泄露。
• 增加了发送针对异构会话的消息批量的支持。

破坏性更改

• 简化了 API 和客户端集
  • get_queue 已不存在，请使用 get_queue_sender/receiver 代替。
  • peek 和其他 queue_client 函数已移动到相应的发送器/接收器。
  • 将 fetch_next 重命名为 receive。
  • 将 session 重命名为 session_id，以在请求给定会话的接收器时统一命名。
  • reconnect 已不存在，如果需要，将隐式执行。
  • open 已不存在，如果需要，将隐式执行。
• 将顶级客户端参数规范化为惯用和一致的命名。
  • 将 ServiceBusClient 初始化器中的 debug 重命名为 logging_enable。
  • 将 ServiceBusClient 初始化器中的 service_namespace 重命名为 fully_qualified_namespace。
• 新的错误层次结构，具有更具体的语义
  • azure.servicebus.exceptions.ServiceBusError
  • azure.servicebus.exceptions.ServiceBusConnectionError
  • azure.servicebus.exceptions.ServiceBusResourceNotFound
  • azure.servicebus.exceptions.ServiceBusAuthorizationError
  • azure.servicebus.exceptions.NoActiveSession
  • azure.servicebus.exceptions.OperationTimeoutError
  • azure.servicebus.exceptions.InvalidHandlerState
  • azure.servicebus.exceptions.AutoLockRenewTimeout
  • azure.servicebus.exceptions.AutoLockRenewFailed
  • azure.servicebus.exceptions.EventDataSendError
  • azure.servicebus.exceptions.MessageSendFailed
  • azure.servicebus.exceptions.MessageLockExpired
  • azure.servicebus.exceptions.MessageSettleFailed
  • azure.servicebus.exceptions.MessageAlreadySettled
  • azure.servicebus.exceptions.SessionLockExpired
• 现在通过在发送者上的 create_batch 方法启动 BatchMessage 创建，使用批次的 add() 方法添加消息，以强制执行服务端最大批次大小限制。
• 现在通过 session_id 参数或属性在消息本身上设置会话，而不是通过 Send 或 get_sender 上的 session。这是为了允许发送目标为不同会话的消息批。
• 现在将会话管理封装在接收器的属性中，例如 receiver.session，以更好地隔离特定于会话的功能。
  • 要针对会话使用 AutoLockRenew，只需传递内部会话对象，而不是接收器本身。

0.50.2 (2019-12-09)

新功能

• 增加了对交付标签锁令牌的支持

错误修复

• 修复了在尝试通过主题线程传递时，消息在初始化时通过无效的 kwargs 的错误。
• 将 UAMQP 依赖项的最小版本增加到 1.2.5，包括一系列修复，包括处理大消息和缓解段错误。

0.50.1 (2019-06-24)

错误修复

• 修复了解析消息的 enqueued_time 和 scheduled_enqueue_time 时将其解析为本地时间戳而不是 UTC 的错误。

0.50.0 (2019-01-17)

破坏性更改

• 引入了基于 AMQP 的新 API。
• 原始基于 HTTP 的 API 仍在新的命名空间下可用：azure.servicebus.control_client
• 有关完整的 API 更改，请参阅更新的 参考文档。

在新的命名空间中，版本 0.21.1 的原始基于 HTTP 的 API 保持不变（即没有添加新功能或错误修复），因此对于只想使用 HTTP 操作的用户来说，现在更新没有额外的好处。

新功能

• 新 API 支持通过 AMQP 以改进的性能和稳定性发送和接收消息。
• 提供了用于发送、接收和消息处理的新异步 API（使用 asyncio）。
• 支持通过后台线程或异步操作自动锁定消息和会话。
• 现在支持计划消息取消。

0.21.1 (2017-04-27)

此 wheel 包现在使用 azure wheel 扩展构建

0.21.0 (2017-01-13)

新功能

• str 消息现在在 Python 3 中接受，并将以 'utf-8' 编码（不再会引发 TypeError）
• broker_properties 现在可以定义为字典，而不仅仅是 JSON str。 datetime、int、float 和 boolean 被转换。
• #902 添加 send_topic_message_batch 操作（接受消息的可迭代对象）
• #902 添加 send_queue_message_batch 操作（接受消息的可迭代对象）

错误修复

• #820 代码现在对 SB RestAPI 的意外更改更具鲁棒性

0.20.3 (2016-08-11)

新闻

• #547 向 Python 添加获取死信路径的静态方法
• #513 添加续订锁

错误修复

• #628 修复了具有双引号的自定义属性

0.20.2 (2016-06-28)

错误修复

• Rest API 中添加了新头，这破坏了 SDK #658 #657

0.20.1 (2015-09-14)

新闻

• 如果用户未传入，则创建一个 requests.Session()

0.20.0 (2015-08-31)

此包的初始版本，来自 azure 包的拆分。有关详细信息以及 Service Bus 的先前历史，请参阅 1.0.0 的 azure 包发行说明。