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

このチュートリアルでは、Ruby アプリケーションを作成して、Service Bus キューとの間でメッセージを送受信する方法を学習します。In this tutorial, you learn how to create Ruby applications to send messages to and receive messages from a Service Bus queue. サンプルは Ruby で記述され、Azure gem を利用しています。The samples are written in Ruby and use the Azure gem.

前提条件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.

      注意

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

Ruby アプリケーションの作成Create a Ruby application

手順については、Microsoft Azure での Ruby アプリケーションの作成 に関するページを参照してください。For instructions, see Create a Ruby Application on Azure.

Service Bus を使用するようにアプリケーションを構成するConfigure Your application to Use Service Bus

Service Bus を使用するには、Azure Ruby パッケージをダウンロードして使用します。このパッケージには、ストレージ REST サービスと通信するための便利なライブラリのセットが含まれています。To use Service Bus, download and use the Azure Ruby package, which includes a set of convenience libraries that communicate with the storage REST services.

RubyGems を使用してパッケージを取得するUse RubyGems to obtain the package

  1. PowerShell (Windows)、ターミナル (Mac)、Bash (Unix) などのコマンド ライン インターフェイスを使用します。Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix).
  2. コマンド ウィンドウに「gem install azure」と入力して、gem と依存関係をインストールします。Type "gem install azure" in the command window to install the gem and dependencies.

パッケージをインポートするImport the package

任意のテキスト エディターを使用して、ストレージを使用するアプリケーションの Ruby ファイルの先頭に次のコードを追加します。Using your favorite text editor, add the following to the top of the Ruby file in which you intend to use storage:

require "azure"

Service Bus 接続の設定Set up a Service Bus connection

名前空間の値、キーの名前、キー、署名者、ホストを設定するには、次のコードを使用します。Use the following code to set the values of namespace, name of the key, key, signer and host:

Azure.configure do |config|
  config.sb_namespace = '<your azure service bus namespace>'
  config.sb_sas_key_name = '<your azure service bus access keyname>'
  config.sb_sas_key = '<your azure service bus access key>'
end
signer = Azure::ServiceBus::Auth::SharedAccessSigner.new
sb_host = "https://#{Azure.sb_namespace}.servicebus.windows.net"

作成した値には、URL 全体ではなく、名前空間値を設定してください。Set the namespace value to the value you created rather than the entire URL. たとえば、 "yourexamplenamespace.servicebus.windows.net" ではなく、"yourexamplenamespace" を使用します。For example, use "yourexamplenamespace", not "yourexamplenamespace.servicebus.windows.net".

キューの作成方法How to create a queue

Azure::ServiceBusService オブジェクトを使用して、キューを操作できます。The Azure::ServiceBusService object enables you to work with queues. キューを作成するには、create_queue() メソッドを使用します。To create a queue, use the create_queue() method. 次の例では、キューを作成するか、すべてのエラーを出力します。The following example creates a queue or prints out any errors.

azure_service_bus_service = Azure::ServiceBus::ServiceBusService.new(sb_host, { signer: signer})
begin
  queue = azure_service_bus_service.create_queue("test-queue")
rescue
  puts $!
end

Azure::ServiceBus::Queue オブジェクトに追加のオプションを渡すこともできます。これにより、メッセージの有効期間やキューの最大サイズなどの既定のキューの設定をオーバーライドできます。You can also pass a Azure::ServiceBus::Queue object with additional options, which enables you to override the default queue settings, such as message time to live or maximum queue size. 次の例は、キューの最大サイズを 5 GB に、有効期間を 1 分に設定する方法を示しています。The following example shows how to set the maximum queue size to 5 GB and time to live to 1 minute:

queue = Azure::ServiceBus::Queue.new("test-queue")
queue.max_size_in_megabytes = 5120
queue.default_message_time_to_live = "PT1M"

queue = azure_service_bus_service.create_queue(queue)

メッセージをキューに送信する方法How to send messages to a queue

メッセージを Service Bus キューに送信するには、アプリケーションで Azure::ServiceBusService オブジェクトの send_queue_message() メソッドを呼び出します。To send a message to a Service Bus queue, your application calls the send_queue_message() method on the Azure::ServiceBusService object. Service Bus キューに送信された (およびキューから受信された) メッセージは Azure::ServiceBus::BrokeredMessage オブジェクトであり、このオブジェクトには、一連の標準的なプロパティ (labeltime_to_live など)、アプリケーションに特有のカスタム プロパティの保持に使用するディクショナリ、および任意のアプリケーション データの本体が備わっています。Messages sent to (and received from) Service Bus queues are Azure::ServiceBus::BrokeredMessage objects, and have a set of standard properties (such as label and time_to_live), a dictionary that is used to hold custom application-specific properties, and a body of arbitrary application data. アプリケーションでは、メッセージとして文字列値を渡すことによってメッセージの本文を設定でき、必須の標準プロパティは既定値に設定されます。An application can set the body of the message by passing a string value as the message and any required standard properties are populated with default values.

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

message = Azure::ServiceBus::BrokeredMessage.new("test queue message")
message.correlation_id = "test-correlation-id"
azure_service_bus_service.send_queue_message("test-queue", message)

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.

キューからメッセージを受信する方法How to receive messages from a queue

キューからメッセージを受信するには、Azure::ServiceBusService オブジェクトの receive_queue_message() メソッドを使用します。Messages are received from a queue using the receive_queue_message() method on the Azure::ServiceBusService object. 既定では、メッセージは読み取られて (ピークされて) ロックされますが、キューからは削除されません。By default, messages are read and locked without being deleted from the queue. ただし、:peek_lock オプションを false に設定すると、読み取ったメッセージをキューから削除できます。However, you can delete messages from the queue as they are read by setting the :peek_lock option to false.

既定の動作では、読み取りと削除が 2 段階の操作になるため、メッセージが失われることを許容できないアプリケーションにも対応することができます。The default behavior makes the reading and deleting a two-stage operation, which also 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. アプリケーションがメッセージの処理を終えた後 (または後で処理するために確実に保存した後)、delete_queue_message() メソッドを呼び出し、削除するメッセージをパラメーターとして指定して、受信処理の第 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 delete_queue_message() method and providing the message to be deleted as a parameter. delete_queue_message() メソッドによって、メッセージが読み取り中としてマークされ、キューから削除されます。The delete_queue_message() method will mark the message as being consumed and remove it from the queue.

:peek_lock パラメーターを false に設定すると、メッセージの読み取りと削除は最もシンプルなモデルになります。これは、障害発生時にアプリケーション側でメッセージを処理しないことを許容できるシナリオに最適です。If the :peek_lock parameter is set to false, reading, and deleting the message becomes 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 has marked the message as being consumed, when the application restarts and begins consuming messages again, it will have missed the message that was consumed prior to the crash.

次の例は receive_queue_message() を使用してメッセージを受信し、処理する方法を示しています。The following example demonstrates how to receive and process messages using receive_queue_message(). この例では、まず :peek_lockfalse に設定し、メッセージを受信して削除します。次に、別のメッセージを受信してから、delete_queue_message() を使用してメッセージを削除します。The example first receives and deletes a message by using :peek_lock set to false, then it receives another message and then deletes the message using delete_queue_message():

message = azure_service_bus_service.receive_queue_message("test-queue",
  { :peek_lock => false })
message = azure_service_bus_service.receive_queue_message("test-queue")
azure_service_bus_service.delete_queue_message(message)

アプリケーションのクラッシュと読み取り不能のメッセージを処理する方法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. 受信側のアプリケーションが何らかの理由によってメッセージを処理できない場合には、Azure::ServiceBusService オブジェクトの unlock_queue_message() メソッドを呼び出すことができます。If a receiver application is unable to process the message for some reason, then it can call the unlock_queue_message() method on the Azure::ServiceBusService object. このメソッドが呼び出されると、Service Bus によってキュー内のメッセージのロックが解除され、メッセージが再度受信できる状態に変わります。メッセージを受信するアプリケーションは、以前と同じものでも、別のものでもかまいません。This call causes 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.

キュー内でロックされているメッセージにはタイムアウトも設定されています。アプリケーションがクラッシュした場合など、ロックがタイムアウトになる前にアプリケーションがメッセージの処理に失敗した場合には、メッセージのロックが自動的に解除され、再度受信できる状態に変わります。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 unlocks the message automatically and makes it available to be received again.

メッセージが処理された後、delete_queue_message() メソッドが呼び出される前にアプリケーションがクラッシュした場合は、アプリケーションが再起動する際にメッセージが再配信されます。In the event that the application crashes after processing the message but before the delete_queue_message() method is called, then the message is redelivered to the application when it restarts. 一般的に、このプロセスは "1 回以上の処理" と呼ばれます。つまり、すべてのメッセージが 1 回以上処理されますが、特定の状況では、同じメッセージが再配信される可能性があります。This process is often called At Least Once Processing; that is, each message is 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. 通常、この問題はメッセージの message_id プロパティを使用して対処します。このプロパティは配信が試行された後も同じ値を保持します。This is often achieved using the message_id property of the message, which remains 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've learned the basics of Service Bus queues, follow these links to learn more.

この記事で説明されている Azure Service Bus キューと、「Ruby から Queue ストレージを使用する方法」の記事で説明されている Azure キューの比較については、「Azure キューと Service Bus キューの比較」を参照してください。For a comparison between the Azure Service Bus queues discussed in this article and Azure Queues discussed in the How to use Queue storage from Ruby article, see Azure Queues and Azure Service Bus Queues - Compared and Contrasted