Python で Service Bus キューを使用する方法How to use Service Bus queues with Python

このチュートリアルでは、Python アプリケーションを作成して、Service Bus キューとの間でメッセージを送受信する方法を学習します。In this tutorial, you learn how to create Python applications to send messages to and receive messages from a Service Bus queue.

前提条件Prerequisites

  1. Azure サブスクリプション。An Azure subscription. このチュートリアルを完了するには、Azure アカウントが必要です。To complete this tutorial, you need an Azure account. MSDN のサブスクライバー特典を有効にするか、無料アカウントにサインアップしてください。You can activate your MSDN subscriber benefits or sign up for a free account.
  2. Azure portal を使用して Service Bus キューを作成する」の手順に従ってください。Follow steps in the Use Azure portal to create a Service Bus queue article.
    1. Service Bus キュー概要をお読みください。Read the quick overview of Service Bus queues.

    2. Service Bus 名前空間を作成します。Create a Service Bus namespace.

    3. 接続文字列を取得します。Get the connection string.

      注意

      このチュートリアルでは、Python を使用して Service Bus 名前空間でキューを作成します。You will create a queue in the Service Bus namespace by using Python in this tutorial.

  3. Python または Python Azure Service Bus パッケージをインストールする方法については、「Python インストール ガイド」をご覧ください。Install Python or the Python Azure Service Bus package, see the Python Installation Guide. Service Bus Python SDK のドキュメント全体については、ここをご覧ください。See full documentation of Service Bus Python SDK here.

キューを作成するCreate a queue

ServiceBusClient オブジェクトを使用すると、キューを操作できます。The ServiceBusClient object enables you to work with queues. プログラムを使用して Service Bus にアクセスするすべての Python ファイルの先頭付近に次のコードを追加します。Add the following code near the top of any Python file in which you wish to programmatically access Service Bus:

from azure.servicebus import ServiceBusClient

次のコードでは、ServiceBusClient オブジェクトを作成します。The following code creates a ServiceBusClient object. <CONNECTION STRING> を servicebus 接続文字列で置換します。Replace <CONNECTION STRING> with your servicebus connectionstring.

sb_client = ServiceBusClient.from_connection_string('<CONNECTION STRING>')

SAS キーの名前と値は、Azure portal 接続情報に含まれています。また、サーバー エクスプローラーで Service Bus 名前空間を選択すると、Visual Studio の [プロパティ] ウィンドウに表示されます (前のセクションに示されているとおり)。The values for the SAS key name and value can be found in the Azure portal connection information, or in the Visual Studio Properties pane when selecting the Service Bus namespace in Server Explorer (as shown in the previous section).

sb_client.create_queue("taskqueue")

create_queue メソッドは追加のオプションもサポートしています。これにより、メッセージの有効期間 (TTL) や最大キュー サイズなどの既定のキューの設定をオーバーライドできます。The create_queue method also supports additional options, which enable you to override default queue settings such as message time to live (TTL) or maximum queue size. 次の例では、最大キュー サイズを 5 GB に設定し、TTL 値を 1 分に設定しています。The following example sets the maximum queue size to 5 GB, and the TTL value to 1 minute:

sb_client.create_queue("taskqueue", max_size_in_megabytes=5120,
                       default_message_time_to_live=datetime.timedelta(minutes=1))

詳細については、Azure Service Bus Python のドキュメントを参照してください。For more information, see Azure Service Bus Python documentation.

メッセージをキューに送信するSend messages to a queue

メッセージを Service Bus キューに送信するには、アプリケーションで ServiceBusClient オブジェクトに対する send メソッドを呼び出します。To send a message to a Service Bus queue, your application calls the send method on the ServiceBusClient object.

次の例では、send_queue_message を使用して、taskqueue という名前のキューにテスト メッセージを送信する方法を示しています。The following example demonstrates how to send a test message to the queue named taskqueue using send_queue_message:

from azure.servicebus import QueueClient, Message

# Create the QueueClient
queue_client = QueueClient.from_connection_string(
    "<CONNECTION STRING>", "<QUEUE NAME>")

# Send a test message to the queue
msg = Message(b'Test Message')
queue_client.send(msg)

Service Bus キューでサポートされているメッセージの最大サイズは、Standard レベルでは 256 KB、Premium レベルでは 1 MB です。Service Bus queues support a maximum message size of 256 KB in the Standard tier and 1 MB in the Premium tier. 標準とカスタムのアプリケーション プロパティが含まれるヘッダーの最大サイズは 64 KB です。The header, which includes the standard and custom application properties, can have a maximum size of 64 KB. キューで保持されるメッセージ数には上限がありませんが、キュー 1 つあたりが保持できるメッセージの合計サイズには上限があります。There is no limit on the number of messages held in a queue but there is a cap on the total size of the messages held by a queue. このキュー サイズは作成時に定義され、上限は 5 GB です。This queue size is defined at creation time, with an upper limit of 5 GB. クォータの詳細については、「Service Bus のクォータ」を参照してください。For more information about quotas, see Service Bus quotas.

詳細については、Azure Service Bus Python のドキュメントを参照してください。For more information, see Azure Service Bus Python documentation.

キューからメッセージを受信するReceive messages from a queue

メッセージは、ServiceBusServiceオブジェクトのget_receiver メソッドを使用してキューから受信します。Messages are received from a queue using the get_receiver method on the ServiceBusService object:

from azure.servicebus import QueueClient, Message

# Create the QueueClient
queue_client = QueueClient.from_connection_string(
    "<CONNECTION STRING>", "<QUEUE NAME>")

# Receive the message from the queue
with queue_client.get_receiver() as queue_receiver:
    messages = queue_receiver.fetch_next(timeout=3)
    for message in messages:
        print(message)
        message.complete()

詳細については、Azure Service Bus Python のドキュメントを参照してください。For more information, see Azure Service Bus Python documentation.

peek_lock パラメーターが False に設定されていると、メッセージが読み取られるときにキューから削除されます。Messages are deleted from the queue as they are read when the parameter peek_lock is set to False. peek_lock パラメーターを True に設定することによって、キューからメッセージを削除せずに、メッセージを読み取って (ピークして) ロックすることができます。You can read (peek) and lock the message without deleting it from the queue by setting the parameter peek_lock to True.

受信操作の中で行われるメッセージの読み取りと削除の動作は、最もシンプルなモデルであり、障害発生時にアプリケーション側でメッセージを処理しないことを許容できるシナリオに最適です。The behavior of reading and deleting the message as part of the receive operation is the simplest model, and works best for scenarios in which an application can tolerate not processing a message in the event of a failure. このことを理解するために、コンシューマーが受信要求を発行した後で、メッセージを処理する前にクラッシュしたというシナリオを考えてみましょう。To understand this, consider a scenario in which the consumer issues the receive request and then crashes before processing it. Service Bus はメッセージを読み取り済みとしてマークするため、アプリケーションが再起動してメッセージの読み取りを再開すると、クラッシュ前に読み取られていたメッセージは見落とされることになります。Because Service Bus will have marked the message as being consumed, then when the application restarts and begins consuming messages again, it will have missed the message that was consumed prior to the crash.

peek_lock パラメーターが True に設定されている場合、受信処理が 2 段階の動作になり、メッセージが失われることが許容できないアプリケーションに対応することができます。If the peek_lock parameter is set to True, the receive becomes a two stage operation, which makes it possible to support applications that cannot tolerate missing messages. Service Bus は要求を受け取ると、次に読み取られるメッセージを検索して、他のコンシューマーが受信できないようロックしてから、アプリケーションにメッセージを返します。When Service Bus receives a request, it finds the next message to be consumed, locks it to prevent other consumers receiving it, and then returns it to the application. アプリケーションがメッセージの処理を終えた後 (または後で処理するために確実に保存した後)、Message オブジェクトの delete メソッドを呼び出して受信処理の第 2 段階を完了します。After the application finishes processing the message (or stores it reliably for future processing), it completes the second stage of the receive process by calling the delete method on the Message object. delete メソッドによって、メッセージが読み取り中としてマークされ、キューから削除されます。The delete method will mark the message as being consumed and remove it from the queue.

msg.delete()

アプリケーションのクラッシュと読み取り不能のメッセージを処理する方法How to handle application crashes and unreadable messages

Service Bus には、アプリケーションにエラーが発生した場合や、メッセージの処理に問題がある場合に復旧を支援する機能が備わっています。Service Bus provides functionality to help you gracefully recover from errors in your application or difficulties processing a message. 受信側のアプリケーションがなんらかの理由によってメッセージを処理できない場合には、Message オブジェクトの unlock メソッドを呼び出すことができます。If a receiver application is unable to process the message for some reason, then it can call the unlock method on the Message object. このメソッドが呼び出されると、Service Bus によってキュー内のメッセージのロックが解除され、メッセージが再度受信できる状態に変わります。メッセージを受信するアプリケーションは、以前と同じものでも、別のものでもかまいません。This will cause Service Bus to unlock the message within the queue and make it available to be received again, either by the same consuming application or by another consuming application.

キュー内でロックされているメッセージには、タイムアウトも設定されています。アプリケーションがクラッシュした場合など、ロックがタイムアウトになる前にアプリケーションがメッセージの処理に失敗した場合は、Service Bus によってメッセージのロックが自動的に解除され、再度受信できる状態に変わります。There is also a timeout associated with a message locked within the queue, and if the application fails to process the message before the lock timeout expires (for example, if the application crashes), then Service Bus will unlock the message automatically and make it available to be received again.

メッセージが処理された後、delete メソッドが呼び出される前にアプリケーションがクラッシュした場合は、アプリケーションが再起動する際にメッセージが再配信されます。In the event that the application crashes after processing the message but before the delete method is called, then the message will be redelivered to the application when it restarts. 一般的に、この動作は 1 回以上の処理 と呼ばれます。つまり、すべてのメッセージが 1 回以上処理されますが、特定の状況では、同じメッセージが再配信される可能性があります。This is often called at least once processing, that is, each message will be processed at least once but in certain situations the same message may be redelivered. 重複処理が許されないシナリオの場合、重複メッセージの配信を扱うロジックをアプリケーションに追加する必要があります。If the scenario cannot tolerate duplicate processing, then application developers should add additional logic to their application to handle duplicate message delivery. 通常、この問題はメッセージの MessageId プロパティを使用して対処します。このプロパティは配信が試行された後も同じ値を保持します。This is often achieved using the MessageId property of the message, which will remain constant across delivery attempts.

注意

Service Bus リソースは、Service Bus Explorer で管理できます。You can manage Service Bus resources with Service Bus Explorer. Service Bus Explorer を使用すると、ユーザーは Service Bus 名前空間に接続し、簡単な方法でメッセージング エンティティを管理できます。The Service Bus Explorer allows users to connect to a Service Bus namespace and administer messaging entities in an easy manner. このツールには、インポート/エクスポート機能や、トピック、キュー、サブスクリプション、リレー サービス、通知ハブ、イベント ハブをテストする機能などの高度な機能が用意されています。The tool provides advanced features like import/export functionality or the ability to test topic, queues, subscriptions, relay services, notification hubs and events hubs.

次の手順Next steps

これで、Service Bus キューの基本を学習できました。さらに詳細な情報が必要な場合は、次の記事をご覧ください。Now that you have learned the basics of Service Bus queues, see these articles to learn more.