サブスクリプションフィルターを設定する (Azure Service Bus)

[アーティクル]
07/24/2024

この記事では、Service Bus トピックのサブスクリプションでフィルターを設定する例をいくつか紹介します。フィルターに関する概念情報については、フィルターに関する記事を参照してください。

Azure Portal の使用

Azure portal でサブスクリプションフィルターを設定するには、[Service Bus サブスクリプション] ページの [フィルター] セクションを使用します。

Azure CLI の使用

az servicebus topic subscription rule create を使用して、サブスクリプション上のルールまたはフィルターを作成します。

Azure PowerShell の使用

Set-AzServiceBusRule を使用して、サブスクリプション上のルールまたはフィルターを作成します。

Note

サブスクリプションルールは、フィルターとアクションから構成されます。アクションは CLI と PowerShell を使用することで指定できますが、Azure portal を使用しては指定できません。

システムプロパティのフィルター処理

フィルター内でシステムプロパティを参照するには、sys.<system-property-name> の形式を使用します。

sys.label LIKE '%bus%'
sys.messageid = 'xxxx'
sys.correlationid like 'abc-%'

Note

システムプロパティの一覧については、「メッセージ、ペイロード、およびシリアル化」を参照してください。
フィルターでは Azure.Messaging.ServiceBus.ServiceBusMessage のシステムプロパティ名を使用してください。
Azure.Messaging.ServiceBus.ServiceBusMessage からの Subject は、非推奨の Microsoft.Azure.ServiceBus.Message の Label にマップされます。

メッセージプロパティのフィルター処理

ここでは、フィルター内でアプリケーションまたはユーザーのプロパティを使う例を示します。アプリケーションのプロパティセットには Azure.Messaging.ServiceBus.ServiceBusMessage.ApplicationProperties (最新) を使って、またはユーザーのプロパティセットには Microsoft.Azure.ServiceBus.ServiceBusMessage (非推奨) を使ってアクセスできます。使用する構文は、user.property-name または単に property-name です。

MessageProperty = 'A'
user.SuperHero like 'SuperMan%'

2026 年 9 月 30 日に、Azure SDK ガイドラインに準拠していない Azure Service Bus SDK ライブラリ WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus、および com.microsoft.azure.servicebus は廃止されます。 SBMP プロトコルのサポートも終了するため、2026 年 9 月 30 日以降はこのプロトコルを使用できなくなります。この日付より前に、重要なセキュリティ更新プログラムと強化された機能が提供される、最新の Azure SDK ライブラリに移行してください。

古いライブラリは 2026 年 9 月 30 日以降も引き続き使用できますが、Microsoft から公式のサポートと更新プログラムは提供されなくなります。詳細については、サポート廃止のお知らせに関するページを参照してください。

特殊文字を含むメッセージプロパティのフィルター処理

メッセージプロパティ名に特殊文字が含まれている場合は、二重引用符 (") を使用してプロパティ名を囲みます。たとえば、プロパティ名が "http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName" である場合は、フィルターで次の構文を使用します。

"http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName" = 'account'

数値を含むメッセージプロパティのフィルター処理

次の例は、数値を含むプロパティをフィルター内で使用する方法を示しています。

MessageProperty = 1
MessageProperty > 1
MessageProperty > 2.08
MessageProperty = 1 AND MessageProperty2 = 3
MessageProperty = 1 OR MessageProperty2 = 3

パラメーターベースのフィルター

ここでは、パラメーターベースのフィルターの使用例をいくつか示します。これらの例では、DataTimeMp は DateTime 型のメッセージプロパティで、@dtParam は DateTime オブジェクトとしてフィルターに渡されるパラメーターです。

DateTimeMp < @dtParam
DateTimeMp > @dtParam

(DateTimeMp2-DateTimeMp1) <= @timespan //@timespan is a parameter of type TimeSpan
DateTimeMp2-DateTimeMp1 <= @timespan

IN と NOT IN の使用

StoreId IN('Store1', 'Store2', 'Store3')

sys.To IN ('Store5','Store6','Store7') OR StoreId = 'Store8'

sys.To NOT IN ('Store1','Store2','Store3','Store4','Store5','Store6','Store7','Store8') OR StoreId NOT IN ('Store1','Store2','Store3','Store4','Store5','Store6','Store7','Store8')

C# のサンプルについては、GitHub のトピックフィルターのサンプルを参照してください。

相関関係フィルター

CorrelationID を使用した相関関係フィルター

new CorrelationFilter("Contoso");

CorrelationID が Contoso に設定されたメッセージをフィルター処理します。

Note

.NET の CorrelationRuleFilter クラスは、Azure.Messaging.ServiceBus.Administration 名前空間にあります。 .NET を使用して一般的にフィルターを作成する方法を示すサンプルコードについては、GitHub のこのコードをご覧ください。

システムおよびユーザーのプロパティを使用した相関関係フィルター

var filter = new CorrelationRuleFilter();
filter.Label = "Important";
filter.ReplyTo = "johndoe@contoso.com";
filter.Properties["color"] = "Red";

これは sys.ReplyTo = 'johndoe@contoso.com' AND sys.Label = 'Important' AND color = 'Red' と同等です。

.NET でサブスクリプションフィルターを作成する例

ここでは、次の Service Bus エンティティを作成する .NET C# の例を示します。

topicfiltersampletopic という名前の Service Bus トピック
True Rule フィルターによる AllOrders という名前のトピックのサブスクリプション。これは、式 1=1 の SQL ルールフィルターと同じです。
SQL フィルター式 color='blue' AND quantity=10 による ColorBlueSize10Orders という名前のサブスクリプション
SQL フィルター式 color='red' とアクションによる ColorRed という名前のサブスクリプション
相関関係フィルター式 Subject = "red", CorrelationId = "high" による HighPriorityRedOrders という名前のサブスクリプション

詳細については、インラインコードコメントを参照してください。

namespace CreateTopicsAndSubscriptionsWithFilters
{
    using Azure.Messaging.ServiceBus.Administration;
    using System;
    using System.Threading.Tasks;

    public class Program
    {
        // Service Bus Administration Client object to create topics and subscriptions
        static ServiceBusAdministrationClient adminClient;

        // connection string to the Service Bus namespace
        static readonly string connectionString = "<YOUR SERVICE BUS NAMESPACE - CONNECTION STRING>";

        // name of the Service Bus topic
        static readonly string topicName = "topicfiltersampletopic";

        // names of subscriptions to the topic
        static readonly string subscriptionAllOrders = "AllOrders";
        static readonly string subscriptionColorBlueSize10Orders = "ColorBlueSize10Orders";
        static readonly string subscriptionColorRed = "ColorRed";
        static readonly string subscriptionHighPriorityRedOrders = "HighPriorityRedOrders";

        public static async Task Main()
        {
            try
            {

                Console.WriteLine("Creating the Service Bus Administration Client object");
                adminClient = new ServiceBusAdministrationClient(connectionString);
                
                Console.WriteLine($"Creating the topic {topicName}");
                await adminClient.CreateTopicAsync(topicName);

                Console.WriteLine($"Creating the subscription {subscriptionAllOrders} for the topic with a True filter ");
                // 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()));


                Console.WriteLine($"Creating the subscription {subscriptionColorBlueSize10Orders} with a SQL filter");
                // Create a SQL filter with color set to blue and quantity to 10
                await adminClient.CreateSubscriptionAsync(
                        new CreateSubscriptionOptions(topicName, subscriptionColorBlueSize10Orders), 
                        new CreateRuleOptions("BlueSize10Orders", new SqlRuleFilter("color='blue' AND quantity=10")));

                Console.WriteLine($"Creating the subscription {subscriptionColorRed} with a SQL filter");
                // Create a SQL filter with color equals to red and a SQL action with a set of statements
                await adminClient.CreateSubscriptionAsync(topicName, subscriptionColorRed);
                // remove the $Default rule
                await adminClient.DeleteRuleAsync(topicName, subscriptionColorRed, "$Default");
                // now create the new rule. notice that user. prefix is used for the user/application property
                await adminClient.CreateRuleAsync(topicName, subscriptionColorRed, new CreateRuleOptions 
                                { 
                                    Name = "RedOrdersWithAction",
                                    Filter = new SqlRuleFilter("user.color='red'"),
                                    Action = new SqlRuleAction("SET quantity = quantity / 2; REMOVE priority;SET sys.CorrelationId = 'low';")

                                }
                );

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

                // delete resources
                //await adminClient.DeleteTopicAsync(topicName);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
            }
        }
    }
}

.NET でメッセージを送受信する例

namespace SendAndReceiveMessages
{
    using System;
    using System.Text;
    using System.Threading.Tasks;
    using Azure.Messaging.ServiceBus;
    using Newtonsoft.Json;
    
    public class Program 
    {
        const string TopicName = "TopicFilterSampleTopic";
        const string SubscriptionAllMessages = "AllOrders";
        const string SubscriptionColorBlueSize10Orders = "ColorBlueSize10Orders";
        const string SubscriptionColorRed = "ColorRed";
        const string SubscriptionHighPriorityOrders = "HighPriorityRedOrders";

        // connection string to your Service Bus namespace
        static string connectionString = "<YOUR SERVICE BUS NAMESPACE - CONNECTION STRING>";

        // the client that owns the connection and can be used to create senders and receivers
        static ServiceBusClient client;

        // the sender used to publish messages to the topic
        static ServiceBusSender sender;

        // the receiver used to receive messages from the subscription 
        static ServiceBusReceiver receiver;

        public async Task SendAndReceiveTestsAsync(string connectionString)
        {
            // This sample demonstrates how to use advanced filters with ServiceBus topics and subscriptions.
            // The sample creates a topic and 3 subscriptions with different filter definitions.
            // Each receiver will receive matching messages depending on the filter associated with a subscription.

            // Send sample messages.
            await this.SendMessagesToTopicAsync(connectionString);

            // Receive messages from subscriptions.
            await this.ReceiveAllMessageFromSubscription(connectionString, SubscriptionAllMessages);
            await this.ReceiveAllMessageFromSubscription(connectionString, SubscriptionColorBlueSize10Orders);
            await this.ReceiveAllMessageFromSubscription(connectionString, SubscriptionColorRed);
            await this.ReceiveAllMessageFromSubscription(connectionString, SubscriptionHighPriorityOrders);
        }


        async Task SendMessagesToTopicAsync(string connectionString)
        {
            // Create the clients that we'll use for sending and processing messages.
            client = new ServiceBusClient(connectionString);
            sender = client.CreateSender(TopicName);

            Console.WriteLine("\nSending orders to topic.");

            // Now we can start sending orders.
            await Task.WhenAll(
                SendOrder(sender, new Order()),
                SendOrder(sender, new Order { Color = "blue", Quantity = 5, Priority = "low" }),
                SendOrder(sender, new Order { Color = "red", Quantity = 10, Priority = "high" }),
                SendOrder(sender, new Order { Color = "yellow", Quantity = 5, Priority = "low" }),
                SendOrder(sender, new Order { Color = "blue", Quantity = 10, Priority = "low" }),
                SendOrder(sender, new Order { Color = "blue", Quantity = 5, Priority = "high" }),
                SendOrder(sender, new Order { Color = "blue", Quantity = 10, Priority = "low" }),
                SendOrder(sender, new Order { Color = "red", Quantity = 5, Priority = "low" }),
                SendOrder(sender, new Order { Color = "red", Quantity = 10, Priority = "low" }),
                SendOrder(sender, new Order { Color = "red", Quantity = 5, Priority = "low" }),
                SendOrder(sender, new Order { Color = "yellow", Quantity = 10, Priority = "high" }),
                SendOrder(sender, new Order { Color = "yellow", Quantity = 5, Priority = "low" }),
                SendOrder(sender, new Order { Color = "yellow", Quantity = 10, Priority = "low" })
                );

            Console.WriteLine("All messages sent.");
        }

        async Task SendOrder(ServiceBusSender sender, Order order)
        {
            var message = new ServiceBusMessage(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(order)))
            {
                CorrelationId = order.Priority,
                Subject = order.Color,
                ApplicationProperties =
                {
                    { "color", order.Color },
                    { "quantity", order.Quantity },
                    { "priority", order.Priority }
                }
            };
            await sender.SendMessageAsync(message);

            Console.WriteLine("Sent order with Color={0}, Quantity={1}, Priority={2}", order.Color, order.Quantity, order.Priority);
        }

        async Task ReceiveAllMessageFromSubscription(string connectionString, string subsName)
        {
            var receivedMessages = 0;

            receiver = client.CreateReceiver(TopicName, subsName, new ServiceBusReceiverOptions() { ReceiveMode = ServiceBusReceiveMode.ReceiveAndDelete } );
            
            // Create a receiver from the subscription client and receive all messages.
            Console.WriteLine("\nReceiving messages from subscription {0}.", subsName);

            while (true)
            {
                var receivedMessage = await receiver.ReceiveMessageAsync(TimeSpan.FromSeconds(10));
                if (receivedMessage != null)
                {
                    foreach (var prop in receivedMessage.ApplicationProperties)
                    {
                        Console.Write("{0}={1},", prop.Key, prop.Value);
                    }
                    Console.WriteLine("CorrelationId={0}", receivedMessage.CorrelationId);
                    receivedMessages++;
                }
                else
                {
                    // No more messages to receive.
                    break;
                }
            }
            Console.WriteLine("Received {0} messages from subscription {1}.", receivedMessages, subsName);
        }

       public static async Task Main()
        {
            try
            {
                Program app = new Program();
                await app.SendAndReceiveTestsAsync(connectionString);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
            }
        }
    }

    class Order
    {
        public string Color
        {
            get;
            set;
        }

        public int Quantity
        {
            get;
            set;
        }

        public string Priority
        {
            get;
            set;
        }
    }
}

次のステップ

次のサンプルを参照してください。

Azure Service Bus の機能を確認するために、ご利用中の言語のサンプルを試してみてください。

次の方法で共有

サブスクリプションフィルターを設定する (Azure Service Bus)

Azure Portal の使用

Azure CLI の使用

Azure PowerShell の使用

システムプロパティのフィルター処理

メッセージプロパティのフィルター処理

特殊文字を含むメッセージプロパティのフィルター処理

数値を含むメッセージプロパティのフィルター処理

パラメーターベースのフィルター

IN と NOT IN の使用

相関関係フィルター

CorrelationID を使用した相関関係フィルター

システムおよびユーザーのプロパティを使用した相関関係フィルター

.NET でサブスクリプションフィルターを作成する例

.NET でメッセージを送受信する例

次のステップ

フィードバック

その他のリソース

次の方法で共有

サブスクリプション フィルターを設定する (Azure Service Bus)

Azure Portal の使用

Azure CLI の使用

Azure PowerShell の使用

システム プロパティのフィルター処理

メッセージ プロパティのフィルター処理

特殊文字を含むメッセージ プロパティのフィルター処理

数値を含むメッセージ プロパティのフィルター処理

パラメーター ベースのフィルター

IN と NOT IN の使用

相関関係フィルター

CorrelationID を使用した相関関係フィルター

システムおよびユーザーのプロパティを使用した相関関係フィルター

.NET でサブスクリプション フィルターを作成する例

.NET でメッセージを送受信する例

次のステップ

フィードバック

その他のリソース

サブスクリプションフィルターを設定する (Azure Service Bus)

システムプロパティのフィルター処理

メッセージプロパティのフィルター処理

特殊文字を含むメッセージプロパティのフィルター処理

数値を含むメッセージプロパティのフィルター処理

パラメーターベースのフィルター

.NET でサブスクリプションフィルターを作成する例