Festlegen von Abonnementfiltern (Azure Service Bus)

Dieser Artikel enthält einige Beispiele zum Festlegen von Filtern für Abonnements von Service Bus-Themen. Konzeptionelle Informationen zu Filtern finden Sie unter Filter.

Verwenden des Azure-Portals

Um Abonnementfilter im Azure-Portal festzulegen, verwenden Sie den Abschnitt Filter der Seite Service Bus-Abonnement.

Mithilfe der Azure-Befehlszeilenschnittstelle

Verwenden Sie az servicebus topic subscription rule create, um eine Regel oder einen Filter für ein Abonnement zu erstellen.

Mithilfe von Azure PowerShell

Verwenden Sie Set-AzServiceBusRule, um eine Regel oder einen Filter für ein Abonnement zu erstellen.

Hinweis

Eine Abonnementregel besteht aus Filtern und Aktionen. Sie können Aktionen mithilfe der CLI und von PowerShell angeben, aber nicht über das Azure-Portal.

Filter für Systemeigenschaften

Verwenden Sie das folgende Format, um in einem Filter auf eine Systemeigenschaft zu verweisen: sys.<system-property-name>.

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

Hinweis

• Eine Liste der Systemeigenschaften finden Sie unter Nachrichten, Nutzlasten und Serialisierung.
• Verwenden Sie Systemeigenschaftennamen aus Azure.Messaging.ServiceBus.ServiceBusMessage in Ihren Filtern.
• Subject aus Azure.Messaging.ServiceBus.ServiceBusMessage wird Label im veralteten Microsoft.Azure.ServiceBus.Message zugeordnet.

Filter für Nachrichteneigenschaften

Dies sind die Beispiele für die Verwendung von Anwendungs- oder Benutzereigenschaften in einem Filter. Sie können auf Anwendungseigenschaften zugreifen, die mit Azure.Messaging.ServiceBus.ServiceBusMessage.ApplicationProperties (aktuell) festgelegt wurden, oder auf Benutzereigenschaften, die mit Microsoft.Azure.ServiceBus.ServiceBusMessage (veraltet) festgelegt wurden. Verwenden Sie dabei die Syntax user.property-name oder einfach property-name.

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

Am 30. September 2026 werden die Azure Service Bus SDK-Bibliotheken „WindowsAzure.ServiceBus“, „Microsoft.Azure.ServiceBus“ und „com.microsoft.azure.servicebus“ eingestellt, da sie nicht den Azure SDK-Richtlinien entsprechen. Außerdem wird die Unterstützung des SBMP-Protokolls beendet, sodass Sie dieses Protokoll nach dem 30. September 2026 nicht mehr verwenden können. Migrieren Sie vor diesem Datum zu den neuesten Azure SDK-Bibliotheken, die wichtige Sicherheitsupdates und verbesserte Funktionen bieten.

Obwohl die älteren Bibliotheken noch über den 30. September 2026 hinaus verwendet werden können, erhalten sie keinen offiziellen Support und keine Updates mehr von Microsoft. Weitere Informationen finden Sie in der Ankündigung der Supporteinstellung.

Filter für Nachrichteneigenschaften mit Sonderzeichen

Wenn der Name der Nachrichteneigenschaft Sonderzeichen enthält, sollten Sie den Namen in doppelte Anführungszeichen (") setzen. Verwenden Sie im Filter beispielsweise die folgende Syntax, wenn der Eigenschaftsname "http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName" lautet.

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

Filter für Nachrichteneigenschaften mit numerischen Werten

In den folgenden Beispielen wird veranschaulicht, wie Sie Eigenschaften mit numerischen Werten in Filtern verwenden können.

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

Parameterbasierte Filter

Hier sind einige Beispiele für die Verwendung von parameterbasierten Filtern angegeben. In diesen Beispielen ist DataTimeMp eine Nachrichteneigenschaft vom Typ DateTime und @dtParam ein Parameter, der als DateTime-Objekt an den Filter übergeben wird.

DateTimeMp < @dtParam
DateTimeMp > @dtParam

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

Verwenden von IN und 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')

Ein C# Beispiel finden Sie im Beispiel für Themenfilter auf GitHub.

Korrelationsfilter

Korrelationsfilter mithilfe der CorrelationID

new CorrelationFilter("Contoso");

Filtert Nachrichten, bei denen CorrelationID auf Contoso festgelegt ist

Hinweis

Die CorrelationRuleFilter-Klasse in .NET befindet sich im Namespace Azure.Messaging.ServiceBus.Administration. Beispielcode, der zeigt, wie Filter im Allgemeinen mithilfe von .NET erstellt werden, finden Sie in hier auf GitHub.

Korrelationsfilter mithilfe von System- und Benutzereigenschaften

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

Entspricht sys.ReplyTo = 'johndoe@contoso.com' AND sys.Label = 'Important' AND color = 'Red'

.NET-Beispiel zum Erstellen von Abonnementfiltern

Nachfolgend finden Sie ein .NET C#-Beispiel, das die folgenden Service Bus-Entitäten erstellt:

• Service Bus-Thema namens topicfiltersampletopic
• Abonnement des Themas namens AllOrders mit einem True Rule-Filter, der einem SQL-Regelfilter mit dem Ausdruck 1=1 entspricht.
• Abonnement namens ColorBlueSize10Orders mit einem SQL-Filterausdruck color='blue' AND quantity=10
• Abonnement namens ColorRed mit einem SQL-Filterausdruck color='red' und einer Aktion
• Abonnement namens HighPriorityRedOrders mit einem Korrelationsfilterausdruck Subject = "red", CorrelationId = "high"

Weitere Informationen finden Sie in den Inlinecodekommentaren.

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-Beispiel zum Senden und Empfangen von Nachrichten

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;
        }
    }
}

Nächste Schritte

Sehen Sie sich die folgenden Beispiele an:

• Verwalten von Regeln
• .NET – Themenfilter
• Azure Resource Manager-Vorlage

Sehen Sie sich die Beispiele in der Sprache Ihrer Wahl an, um sich mit Azure Service Bus-Features vertraut zu machen.

• Azure Service Bus-Clientbibliothekbeispiele für .NET (neueste Version)
• Azure Service Bus-Clientbibliothekbeispiele für Java (neueste Version)
• Azure Service Bus-Clientbibliothekbeispiele für Python
• Azure Service Bus-Clientbibliothekbeispiele für JavaScript
• Azure Service Bus-Clientbibliothekbeispiele für TypeScript