Ruby で Service Bus のトピックとサブスクリプションを使用する方法How to use Service Bus topics and subscriptions with Ruby

この記事では、Ruby アプリケーションから Service Bus のトピックとサブスクリプションを使用する方法について説明します。This article describes how to use Service Bus topics and subscriptions from Ruby applications. 紹介するシナリオは次のとおりです。The scenarios covered include:

  • キュー、トピック、およびサブスクリプションを作成するCreating topics and subscriptions
  • サブスクリプション フィルターを作成するCreating subscription filters
  • メッセージをトピックに送信するSending messages to a topic
  • サブスクリプションからメッセージを受信するReceiving messages from a subscription
  • トピックとサブスクリプションを削除するDeleting topics and subscriptions

前提条件Prerequisites

  1. Azure サブスクリプション。An Azure subscription. このチュートリアルを完了するには、Azure アカウントが必要です。To complete this tutorial, you need an Azure account. Visual Studio または MSDN サブスクライバーの特典を有効にするか、無料アカウントにサインアップしてください。You can activate your Visual Studio or MSDN subscriber benefits or sign-up for a free account.

  2. Quickstart:Use the Azure portal to create a Service Bus topic and subscriptions to the topic」(クイック スタート: Azure portal を使用して Service Bus トピックとその中に含まれるサブスクリプションを作成する) の手順に従って、Service Bus の名前空間を作成し、接続文字列を取得します。Follow steps in the Quickstart: Use the Azure portal to create a Service Bus topic and subscriptions to the topic to create a Service Bus namespace and get the connection string.

    注意

    このクイック スタートでは、Ruby を使用して トピックとその中に含まれるサブスクリプションを作成します。You will create a topic and a subscription to the topic by using Ruby in this quickstart.

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".

トピックを作成するCreate a topic

Azure::ServiceBusService オブジェクトを使用すると、トピックを操作できます。The Azure::ServiceBusService object enables you to work with topics. 次のコードでは、Azure::ServiceBusService オブジェクトを作成します。The following code creates an Azure::ServiceBusService object. トピックを作成するには、create_topic() メソッドを使用します。To create a topic, use the create_topic() method. 次の例ではトピックを作成しており、エラーがあった場合は出力します。The following example creates a topic or prints out any errors.

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

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

topic = Azure::ServiceBus::Topic.new("test-topic")
topic.max_size_in_megabytes = 5120
topic.default_message_time_to_live = "PT1M"

topic = azure_service_bus_service.create_topic(topic)

サブスクリプションを作成するCreate subscriptions

トピック サブスクリプションも、Azure::ServiceBusService オブジェクトで作成します。Topic subscriptions are also created with the Azure::ServiceBusService object. サブスクリプションを指定し、サブスクリプションの仮想キューに配信するメッセージを制限するフィルターを設定できます。Subscriptions are named and can have an optional filter that restricts the set of messages delivered to the subscription's virtual queue.

サブスクリプションは永続的です。Subscriptions are persistent. サブスクリプションは、サブスクリプションが削除されるか、サブスクリプションが関連付けられているトピックが削除されるまで保持されます。They continue to exist until either they, or the topic they are associated with, are deleted. アプリケーションにサブスクリプションを作成するロジックが含まれている場合は、最初に getSubscription メソッドを使用して、サブスクリプションが既に存在しているかどうかを確認する必要があります。If your application contains logic to create a subscription, it should first check if the subscription already exists by using the getSubscription method.

既定の (MatchAll) フィルターを適用したサブスクリプションの作成Create a subscription with the default (MatchAll) filter

新しいサブスクリプションの作成時にフィルターが指定されていない場合は、MatchAll フィルター (既定) が使用されます。If no filter is specified when a new subscription is created, the MatchAll filter (default) is used. MatchAll フィルターを使用すると、トピックに発行されたすべてのメッセージがサブスクリプションの仮想キューに置かれます。When the MatchAll filter is used, all messages published to the topic are placed in the subscription's virtual queue. 次の例では、"all-messages" という名前のサブスクリプションを作成し、既定の MatchAll フィルターを使用します。The following example creates a subscription named "all-messages" and uses the default MatchAll filter.

subscription = azure_service_bus_service.create_subscription("test-topic", "all-messages")

フィルターを適用したサブスクリプションの作成Create subscriptions with filters

トピックに送信されたメッセージのうち、特定のサブスクリプション内に表示されるメッセージを指定するフィルターを定義することもできます。You can also define filters that enable you to specify which messages sent to a topic should show up within a specific subscription.

サブスクリプションでサポートされるフィルターのうち、最も柔軟性の高いものが、SQL92 のサブセットを実装する Azure::ServiceBus::SqlFilter です。The most flexible type of filter supported by subscriptions is the Azure::ServiceBus::SqlFilter, which implements a subset of SQL92. SQL フィルターは、トピックに発行されるメッセージのプロパティに対して適用されます。SQL filters operate on the properties of the messages that are published to the topic. SQL フィルターで使用できる式の詳細については、SqlFilter 構文の説明をご覧ください。For more details about the expressions that can be used with a SQL filter, review the SqlFilter syntax.

Azure::ServiceBusService オブジェクトの create_rule() メソッドを使用して、サブスクリプションにフィルターを追加できます。You can add filters to a subscription by using the create_rule() method of the Azure::ServiceBusService object. このメソッドでは、新しいフィルターを既存のサブスクリプションに追加できます。This method enables you to add new filters to an existing subscription.

既定のフィルターはすべての新しいサブスクリプションに自動的に適用されるため、最初に既定のフィルターを削除する必要があります。削除しないと、 MatchAll によって、指定された他のすべてのフィルターがオーバーライドされます。Since the default filter is applied automatically to all new subscriptions, you must first remove the default filter, or the MatchAll overrides any other filters you may specify. 既定のルールを削除するには、Azure::ServiceBusService オブジェクトの delete_rule() メソッドを使用します。You can remove the default rule by using the delete_rule() method on the Azure::ServiceBusService object.

次の例では、"high-messages" という名前のサブスクリプションを作成し、Azure::ServiceBus::SqlFilter を適用します。このフィルターでは、カスタム プロパティ message_number が 3 を超えるメッセージのみが選択されます。The following example creates a subscription named "high-messages" with an Azure::ServiceBus::SqlFilter that only selects messages that have a custom message_number property greater than 3:

subscription = azure_service_bus_service.create_subscription("test-topic", "high-messages")
azure_service_bus_service.delete_rule("test-topic", "high-messages", "$Default")

rule = Azure::ServiceBus::Rule.new("high-messages-rule")
rule.topic = "test-topic"
rule.subscription = "high-messages"
rule.filter = Azure::ServiceBus::SqlFilter.new({
  :sql_expression => "message_number > 3" })
rule = azure_service_bus_service.create_rule(rule)

同様に、次の例では low-messages という名前のサブスクリプションを作成し、Azure::ServiceBus::SqlFilter を適用します。このフィルターでは、message_number プロパティが 3 以下のメッセージのみが選択されます。Similarly, the following example creates a subscription named low-messages with an Azure::ServiceBus::SqlFilter that only selects messages that have a message_number property less than or equal to 3:

subscription = azure_service_bus_service.create_subscription("test-topic", "low-messages")
azure_service_bus_service.delete_rule("test-topic", "low-messages", "$Default")

rule = Azure::ServiceBus::Rule.new("low-messages-rule")
rule.topic = "test-topic"
rule.subscription = "low-messages"
rule.filter = Azure::ServiceBus::SqlFilter.new({
  :sql_expression => "message_number <= 3" })
rule = azure_service_bus_service.create_rule(rule)

メッセージが test-topic に送信されると、そのメッセージは all-messages トピック サブスクリプションにサブスクライブしている受信者に必ず配信され、さらにメッセージのコンテンツに応じて、high-messageslow-messages トピック サブスクリプションにサブスクライブしている受信者に対して選択的に配信されます。When a message is now sent to test-topic, it is always be delivered to receivers subscribed to the all-messages topic subscription, and selectively delivered to receivers subscribed to the high-messages and low-messages topic subscriptions (depending upon the message content).

メッセージをトピックに送信するSend messages to a topic

メッセージを Service Bus トピックに送信するには、アプリケーションで Azure::ServiceBusService オブジェクトの send_topic_message() メソッドを使用する必要があります。To send a message to a Service Bus topic, your application must use the send_topic_message() method on the Azure::ServiceBusService object. Service Bus トピックに送信されたメッセージは、Azure::ServiceBus::BrokeredMessage オブジェクトのインスタンスです。Messages sent to Service Bus topics are instances of the Azure::ServiceBus::BrokeredMessage objects. Azure::ServiceBus::BrokeredMessage オブジェクトには、(labeltime_to_live などの) 標準的なプロパティ、アプリケーションに特有のカスタム プロパティの保持に使用するディクショナリ、および文字列データの本体が備わっています。Azure::ServiceBus::BrokeredMessage objects 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 string data. アプリケーションは、send_topic_message() メソッドに文字列値を渡すことによってメッセージの本文を設定できます。必須の標準プロパティには既定値が設定されます。An application can set the body of the message by passing a string value to the send_topic_message() method and any required standard properties are populated by default values.

次の例では、test-topic トピックに 5 件のテスト メッセージを送信する方法を示しています。The following example demonstrates how to send five test messages to test-topic. 各メッセージの message_number カスタム プロパティの値が、ループの反復回数に応じて変化することに注意してください (これによってメッセージを受信するサブスクリプションが決定されます)。The message_number custom property value of each message varies on the iteration of the loop (it determines which subscription receives it):

5.times do |i|
  message = Azure::ServiceBus::BrokeredMessage.new("test message " + i,
    { :message_number => i })
  azure_service_bus_service.send_topic_message("test-topic", message)
end

Service Bus トピックでサポートされているメッセージの最大サイズは、Standard レベルでは 256 KB、Premium レベルでは 1 MB です。Service Bus topics 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 つのトピックで保持されるメッセージ数に上限はありませんが、1 つのトピックで保持できるメッセージの合計サイズには上限があります。There is no limit on the number of messages held in a topic but there is a cap on the total size of the messages held by a topic. このトピックのサイズはトピックの作成時に定義します。上限は 5 GB です。This topic size is defined at creation time, with an upper limit of 5 GB.

サブスクリプションからメッセージを受信するReceive messages from a subscription

サブスクリプションからメッセージを受信するには、Azure::ServiceBusService オブジェクトの receive_subscription_message() メソッドを使用します。Messages are received from a subscription using the receive_subscription_message() method on the Azure::ServiceBusService object. 既定では、メッセージは読み取られて (ピークされて) ロックされますが、サブスクリプションからは削除されません。By default, messages are read(peak) and locked without deleting it from the subscription. peek_lock オプションを false に設定すると、サブスクリプションからメッセージを読み取って削除できます。You can read and delete the message from the subscription 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_subscription_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_subscription_message() method and providing the message to be deleted as a parameter. delete_subscription_message() メソッドによって、メッセージが読み取り中としてマークされ、サブスクリプションから削除されます。The delete_subscription_message() method marks the message as being consumed and remove it from the subscription.

: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 when a failure occurs. たとえば、コンシューマーが受信要求を発行した後で、メッセージを処理する前にクラッシュするシナリオを考えてみましょう。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, then when the application restarts and begins consuming messages again, it has missed the message that was consumed prior to the crash.

次の例では、receive_subscription_message() を使用したメッセージの受信および処理の方法を示しています。The following example demonstrates how messages can be received and processed using receive_subscription_message(). この例では、まず :peek_lockfalse に設定し、low-messages サブスクリプションからのメッセージを受信して削除します。次に、high-messages からの別のメッセージを受信してから、delete_subscription_message() を使用してメッセージを削除します。The example first receives and deletes a message from the low-messages subscription by using :peek_lock set to false, then it receives another message from the high-messages and then deletes the message using delete_subscription_message():

message = azure_service_bus_service.receive_subscription_message(
  "test-topic", "low-messages", { :peek_lock => false })
message = azure_service_bus_service.receive_subscription_message(
  "test-topic", "high-messages")
azure_service_bus_service.delete_subscription_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_subscription_message() メソッドを呼び出すことができます。If a receiver application is unable to process the message for some reason, then it can call the unlock_subscription_message() method on the Azure::ServiceBusService object. これにより、Service Bus によりサブスクリプション内のメッセージのロックが解除され、メッセージが再度受信できる状態に変わります。このメッセージは、同じコンシューマー側アプリケーションまたは別のコンシューマー側アプリケーションで受信されます。It causes Service Bus to unlock the message within the subscription 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 subscription, 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 make it available to be received again.

メッセージが処理された後、delete_subscription_message() メソッドが呼び出される前にアプリケーションがクラッシュした場合は、アプリケーションが再起動する際にメッセージが再配信されます。In the event that the application crashes after processing the message but before the delete_subscription_message() method is called, then the message is redelivered to the application when it restarts. このプロセスは、しばしば "1 回以上の処理" と呼ばれます。つまり、すべてのメッセージが 1 回以上処理されますが、状況によっては、同じメッセージが再配信される可能性があります。It 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 logic is often achieved using the message_id property of the message, which remains constant across delivery attempts.

トピックとサブスクリプションを削除するDelete topics and subscriptions

トピックおよびサブスクリプションは永続的であり、Azure ポータルまたはプログラムによって明示的に削除する必要があります。Topics and subscriptions are persistent, and must be explicitly deleted either through the Azure portal or programmatically. 次の例では、test-topic という名前のトピックを削除する方法を示しています。The following example demonstrates how to delete the topic named test-topic.

azure_service_bus_service.delete_topic("test-topic")

トピックを削除すると、そのトピックに登録されたサブスクリプションもすべて削除されます。Deleting a topic also deletes any subscriptions that are registered with the topic. サブスクリプションは、個別に削除することもできます。Subscriptions can also be deleted independently. 次のコードでは、high-messages という名前のサブスクリプションを test-topic トピックから削除する方法を示しています。The following code demonstrates how to delete the subscription named high-messages from the test-topic topic:

azure_service_bus_service.delete_subscription("test-topic", "high-messages")

次の手順Next steps

これで、サービス バス トピックの基本を学習できました。さらに詳細な情報が必要な場合は、次のリンク先をご覧ください。Now that you've learned the basics of Service Bus topics, follow these links to learn more.