azure-servicebus-py

捆绑的上游支持文件

支持文件包含在相对于技能的路径中。有关其固定来源、许可证、哈希值和导入变更，请参阅 UPSTREAM-NOTICE.md。

恢复的辅助工具安全说明

scripts/setup_servicebus.py 可以创建或删除 Service Bus 队列、主题和订阅。删除命令必须使用 --confirm-delete；创建订阅时使用 --filter 会替换新建订阅上的默认规则。在实际使用前，请与用户确认命名空间以及确切的实体和操作；优先使用一次性测试命名空间。

Azure Service Bus SDK for Python

用于实现可靠云通信的企业消息传递，支持队列和发布/订阅主题。

安装

pip install azure-servicebus azure-identity aiohttp

环境变量

SERVICEBUS_FULLY_QUALIFIED_NAMESPACE=<namespace>.servicebus.windows.net
SERVICEBUS_QUEUE_NAME=myqueue
SERVICEBUS_TOPIC_NAME=mytopic
SERVICEBUS_SUBSCRIPTION_NAME=mysubscription

示例边界

接收或结算消息会改变代理状态；完成 DLQ 消息会将其删除。检查时使用 peek，单独授权重放或丢弃操作，编辑有效负载以移除敏感信息，并同时关闭凭据和客户端，且确保消费者具备幂等性。示例省略了应用处理程序、导入和生产环境中的锁续期；它们只是草图，并非可独立运行的程序。

身份验证

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

credential = DefaultAzureCredential()
namespace = "<namespace>.servicebus.windows.net"

client = ServiceBusClient(
    fully_qualified_namespace=namespace,
    credential=credential
)

客户端类型

客户端	用途	获取方式
ServiceBusClient	连接管理	直接实例化
ServiceBusSender	发送消息	client.get_queue_sender() / get_topic_sender()
ServiceBusReceiver	接收消息	client.get_queue_receiver() / get_subscription_receiver()

发送消息（异步）

import asyncio
from azure.servicebus.aio import ServiceBusClient
from azure.servicebus import ServiceBusMessage
from azure.identity.aio import DefaultAzureCredential

async def send_messages():
    credential = DefaultAzureCredential()
    
    async with ServiceBusClient(
        fully_qualified_namespace="<namespace>.servicebus.windows.net",
        credential=credential
    ) as client:
        sender = client.get_queue_sender(queue_name="myqueue")
        
        async with sender:
            # Single message
            message = ServiceBusMessage("Hello, Service Bus!")
            await sender.send_messages(message)
            
            # Batch of messages
            messages = [ServiceBusMessage(f"Message {i}") for i in range(10)]
            await sender.send_messages(messages)
            
            # Message batch (for size control)
            batch = await sender.create_message_batch()
            for i in range(100):
                try:
                    batch.add_message(ServiceBusMessage(f"Batch message {i}"))
                except ValueError:  # Batch full
                    await sender.send_messages(batch)
                    batch = await sender.create_message_batch()
                    batch.add_message(ServiceBusMessage(f"Batch message {i}"))
            await sender.send_messages(batch)

asyncio.run(send_messages())

接收消息（异步）

async def receive_messages():
    credential = DefaultAzureCredential()
    
    async with ServiceBusClient(
        fully_qualified_namespace="<namespace>.servicebus.windows.net",
        credential=credential
    ) as client:
        receiver = client.get_queue_receiver(queue_name="myqueue")
        
        async with receiver:
            # Receive batch
            messages = await receiver.receive_messages(
                max_message_count=10,
                max_wait_time=5  # seconds
            )
            
            for msg in messages:
                print(f"Received: {str(msg)}")
                await receiver.complete_message(msg)  # Remove from queue

asyncio.run(receive_messages())

接收模式

模式	行为	使用场景
PEEK_LOCK（默认）	锁定消息，必须完成或放弃	可靠处理
RECEIVE_AND_DELETE	接收时立即移除	至多一次投递

from azure.servicebus import ServiceBusReceiveMode

receiver = client.get_queue_receiver(
    queue_name="myqueue",
    receive_mode=ServiceBusReceiveMode.RECEIVE_AND_DELETE
)

消息结算

async with receiver:
    messages = await receiver.receive_messages(max_message_count=1)
    
    for msg in messages:
        try:
            # Process message...
            await receiver.complete_message(msg)  # Success - remove from queue
        except ProcessingError:
            await receiver.abandon_message(msg)  # Retry later
        except PermanentError:
            await receiver.dead_letter_message(
                msg,
                reason="ProcessingFailed",
                error_description="Could not process"
            )

操作	效果
complete_message()	从队列中移除（成功）
abandon_message()	释放锁，立即重试
dead_letter_message()	移至死信队列
defer_message()	暂存，之后通过序列号接收

主题和订阅

# Send to topic
sender = client.get_topic_sender(topic_name="mytopic")
async with sender:
    await sender.send_messages(ServiceBusMessage("Topic message"))

# Receive from subscription
receiver = client.get_subscription_receiver(
    topic_name="mytopic",
    subscription_name="mysubscription"
)
async with receiver:
    messages = await receiver.receive_messages(max_message_count=10)

会话（FIFO）

# Send with session
message = ServiceBusMessage("Session message")
message.session_id = "order-123"
await sender.send_messages(message)

# Receive from specific session
receiver = client.get_queue_receiver(
    queue_name="session-queue",
    session_id="order-123"
)

# Receive from next available session
from azure.servicebus import NEXT_AVAILABLE_SESSION
receiver = client.get_queue_receiver(
    queue_name="session-queue",
    session_id=NEXT_AVAILABLE_SESSION
)

定时消息

from datetime import datetime, timedelta, timezone

message = ServiceBusMessage("Scheduled message")
scheduled_time = datetime.now(timezone.utc) + timedelta(minutes=10)

# Schedule message
sequence_number = await sender.schedule_messages(message, scheduled_time)

# Cancel scheduled message
await sender.cancel_scheduled_messages(sequence_number)

死信队列

from azure.servicebus import ServiceBusSubQueue

# Receive from dead-letter queue
dlq_receiver = client.get_queue_receiver(
    queue_name="myqueue",
    sub_queue=ServiceBusSubQueue.DEAD_LETTER
)

async with dlq_receiver:
    messages = await dlq_receiver.receive_messages(max_message_count=10)
    for msg in messages:
        print(f"Dead-lettered: {msg.dead_letter_reason}")
        await dlq_receiver.complete_message(msg)

同步客户端（用于简单脚本）

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

with ServiceBusClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=DefaultAzureCredential()
) as client:
    with client.get_queue_sender("myqueue") as sender:
        sender.send_messages(ServiceBusMessage("Sync message"))
    
    with client.get_queue_receiver("myqueue") as receiver:
        for msg in receiver:
            print(str(msg))
            receiver.complete_message(msg)

最佳实践

1. 生产工作负载使用异步客户端
2. 使用上下文管理器（async with）正确清理资源
3. 成功处理后完成消息
4. 使用死信队列处理有问题的消息
5. 使用会话实现有序的 FIFO 处理
6. 在高吞吐量场景中使用消息批次
7. 设置 max_wait_time，避免无限期阻塞

参考文件

文件	内容
references/patterns.md	竞争消费者、会话、重试模式、请求-响应、事务
references/dead-letter.md	DLQ 处理、有问题的消息、重新处理策略
scripts/setup_servicebus.py	用于管理队列、主题和订阅以及监控 DLQ 的 CLI

适用场景

此技能适用于执行概述中描述的工作流或操作。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。