トピック フィルターとアクション

  • [アーティクル]

サブスクライバーは、トピックから受信するメッセージを定義できます。 これらのメッセージは、1 つ以上の名前付きのサブスクリプション ルールの形式で指定されます。 各ルールは、特定のメッセージを選択するフィルター条件と、選択したメッセージに注釈を付けるアクション (省略可能) で構成されます。

アクションのないすべてのルールは OR 条件を使用して結合され、複数の照合ルールがある場合でも、サブスクリプションで 1 つのメッセージになります。

アクションを含むルールはそれぞれ、1 つのメッセージのコピーを生成します。 このメッセージには RuleName というプロパティがあり、その値は照合ルールの名前です。 アクションによって、プロパティの追加や更新を行ったり、元のメッセージからプロパティを削除したりして、サブスクリプションでメッセージを生成できます。

サブスクリプションに 5 つのルール (アクションを含む 2 つのルールとアクションのない他の 3 つのルール) があるシナリオを考えてみましょう。 この例では、5 つすべてのルールに一致する 1 つのメッセージを送信すると、サブスクリプションで 3 つのメッセージが取得されます。 これは、アクションを含む 2 つのルールに対する 2 つのメッセージと、アクションのない 3 つのルールに対する 1 つのメッセージです。

新しく作成された各トピック サブスクリプションには、既定の初期サブスクリプション ルールがあります。 ルールのフィルター条件を明示的に指定しない場合、サブスクリプションに選択されたすべてのメッセージが有効になる true フィルターが適用されます。 既定のルールに関連付けられている注釈アクションはありません。

Note

この記事は、JMS 以外のシナリオに適用されます。 JMS シナリオの場合は、メッセージ・セレクターを使用します。

フィルター

Service Bus は、次の 3 つのフィルターをサポートします。

  • SQL フィルター
  • ブール値フィルター
  • 相関関係フィルター

以下のセクションでは、これらのフィルターについて詳しく説明します。

SQL フィルター

SqlFilter には、受信メッセージのユーザー定義のプロパティとシステム プロパティに対して、ブローカーで評価される、SQL に似た条件式が入っています。 すべてのシステム プロパティの条件式にはプレフィックスとして sys. を付ける必要があります。 フィルター条件の SQL 言語のサブセットは、プロパティ (EXISTS) や null 値 (IS NULL)、論理 NOT/AND/OR、関係演算子、単純な数値演算、および LIKE による単純なテキスト パターン マッチングの存在をテストします。

これは SQL フィルターを定義するための .NET の例です。

adminClient = new ServiceBusAdministrationClient(connectionString);    

// Create a SQL filter with color set to blue and quantity to 10
await adminClient.CreateSubscriptionAsync(
		new CreateSubscriptionOptions(topicName, "ColorBlueSize10Orders"), 
		new CreateRuleOptions("BlueSize10Orders", new SqlRuleFilter("color='blue' AND quantity=10")));

// Create a SQL filter with color set to red
// Action is defined to set the quantity to half if the color is red
await adminClient.CreateRuleAsync(topicName, "ColorRed", new CreateRuleOptions 
{ 
	Name = "RedOrdersWithAction",
	Filter = new SqlRuleFilter("user.color='red'"),
	Action = new SqlRuleAction("SET quantity = quantity / 2;")
}

ブール値フィルター

TrueFilter と FalseFilter により、すべての受信メッセージがサブスクリプションに選択される (true) か、いずれも選択されない (false) かのいずれかになります。 これら 2 つのフィルターは、SQL フィルターから派生します。

これはブール値フィルターを定義するための .NET の例です。

// Create a True Rule filter with an expression that always evaluates to true
// It's equivalent to using SQL rule filter with 1=1 as the expression
await adminClient.CreateSubscriptionAsync(
		new CreateSubscriptionOptions(topicName, subscriptionAllOrders), 
		new CreateRuleOptions("AllOrders", new TrueRuleFilter()));

相関関係フィルター

CorrelationFilter には、受信メッセージのユーザーおよびシステム プロパティの 1 つ以上と照合される条件セットが入っています。 一般的な使用方法は CorrelationId プロパティの照合ですが、アプリケーションでは次のプロパティに対して照合することもできます。

  • ContentType
  • Label
  • MessageId
  • ReplyTo
  • ReplyToSessionId
  • SessionId
  • To
  • 任意のユーザー定義プロパティ。

受信メッセージのプロパティ値が相関関係フィルターに指定された値と等しいときに、一致するものが存在すると判断されます。 文字列式の比較では大文字と小文字を区別します。 照合するプロパティを複数指定すると、フィルターでは論理 AND 条件として結合され、フィルターが一致するには、すべての条件が一致する必要があります。

これは相関関係フィルターを定義するための .NET の例です。

// Create a correlation filter with color set to Red and priority set to High
await adminClient.CreateSubscriptionAsync(
		new CreateSubscriptionOptions(topicName, "HighPriorityRedOrders"), 
		new CreateRuleOptions("HighPriorityRedOrdersRule", new CorrelationRuleFilter() {Subject = "red", CorrelationId = "high"} ));

String 引数を受け取る CorrelationRuleFilter コンストラクターを使用して、関連付け ID を持つ関連付けフィルターを作成します。

CorrelationRuleFilter既定のコンストラクターを使用する場合は、システム プロパティ (ContentType、Label、MessageId、ReplyTo、ReplyToSessionId、SessionId、To)、およびユーザー定義プロパティをフィルター処理に割り当てることができます。 関連付けフィルターのユーザー定義プロパティを指定するには、IDictionary <string, object> 型の Properties プロパティを使用します。 このディクショナリのキーは、メッセージを検索するユーザー定義のプロパティです。 キーに関連付けられている値は、関連付ける値です。 次に例を示します。

var filter = new CorrelationFilter();
filter.Label = "abc";
filter.ReplyTo = "xdeu@hotmail.com";
filter.Properties["prop1"] = "abc";
filter.Properties["prop2"] = "xyz";

注意

  • すべてのフィルターでは、メッセージのプロパティが評価されます。 フィルターは、メッセージの本文は評価できません。
  • 複雑なフィルター ルールでは、処理能力が必要になります。 特に、SQL フィルター ルールを使用すると、サブスクリプション、トピック、名前空間レベルでメッセージのスループット全体が低下します。 可能な場合は、アプリケーションでは、SQL に似たフィルターではなく、処理効率が高く、スループットに与える影響が少ない、相関関係フィルターを選択してください。

Actions

SQL フィルター条件を使用すると、プロパティとその値を追加、削除、または置き換えることによってメッセージに注釈を付けることができるアクションを定義できます。 アクションでは、SQL UPDATE ステートメント構文を大まかに基にした SQL に似た式を使用します。 アクションは、メッセージが照合された後にサブスクリプションへと選択される前に、メッセージに対して実行されます。 メッセージのプロパティへの変更は、サブスクリプションにコピーされたメッセージにのみ有効です。

色が赤のときに数量を更新するアクションを含む SQL ルールを作成する .NET の例を次に示します。

adminClient = new ServiceBusAdministrationClient(connectionString);    

// Create a SQL filter with color set to red
// Action is defined to set the quantity to half if the color is red
await adminClient.CreateRuleAsync(topicName, "ColorRed", new CreateRuleOptions 
{ 
	Name = "RedOrdersWithAction",
	Filter = new SqlRuleFilter("user.color='red'"),
	Action = new SqlRuleAction("SET quantity = quantity / 2;")
}

使用パターン

  • ブロードキャストパターン

    最も簡単なトピックの使用シナリオでは、すべてのサブスクリプションが、トピックに送信された各メッセージのコピーを取得し、これにより、ブロードキャスト パターンが作成されます。

  • パーティション分割パターン

    パーティション分割では、フィルターを使用して、予測可能で相互に排他的な方法で複数の既存のトピック サブスクリプションにメッセージを配布します。 パーティション分割のパターンは、それぞれが、たとえば顧客プロファイル情報のようなデータ全体の中のサブセットをそれぞれが保持する、機能的には同一のコンパートメントにある多数の異なるコンテキストを処理するために、システムを拡張する場合に使用されます。 パーティション分割では、発行元は、パーティション分割モデルの知識がなくても、トピックにメッセージを送信できます。 メッセージは、正しいサブスクリプションに移動され、パーティションのメッセージ ハンドラーはそこからメッセージを取得できます。

  • ルーティングパターン

    ルーティングでは、フィルターを使用して、予測可能な方法で複数のトピック サブスクリプションにメッセージを配布しますが、必ずしも排他的ではありません。 トピック フィルターは、自動転送機能と組み合わせると、Azure リージョン内にメッセージを配布するための Service Bus 名前空間内での複雑なルーティング グラフの作成に使用することができます。 Azure Functions または Azure Logic Apps を Azure Service Bus 名前空間の間の仲介役として機能させることで、基幹業務アプリケーションに直接統合された複雑なグローバル トポロジを作成できます。

Note

Azure portal で Service Bus Explorer の機能がサポートされるようになったため、サブスクリプション フィルターをポータルから作成したり編集したりすることができます。

次のステップ

例については、Service Bus フィルターの例を参照してください。