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 メッセージを処理完了にすると、そのメッセージは削除されます。内容の確認にはピークを使用し、再配信／破棄は別途承認を得てください。ペイロードを秘匿化し、クライアントだけでなく認証情報も閉じ、コンシューマーを冪等にしてください。例では、アプリケーションハンドラー、インポート、本番環境でのロック更新を省略しています。これは概要を示すものであり、単独で動作するプログラムではありません。

認証

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	受信時に直ちに削除されます	最大 1 回の配信

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

使用する場面

このスキルは、概要で説明されているワークフローまたはアクションを実行する場合に適用できます。

制限事項

• このスキルは、タスクが上記の範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認してください。