Ustawianie filtrów subskrypcji (Azure Service Bus)

Ten artykuł zawiera kilka przykładów dotyczących ustawiania filtrów dla subskrypcji dla tematów usługi Service Bus. Aby uzyskać informacje koncepcyjne dotyczące filtrów, zobacz Filtry.

Korzystanie z witryny Azure Portal

Aby ustawić filtry subskrypcji w witrynie Azure Portal, użyj sekcji Filtry na stronie Subskrypcja usługi Service Bus.

Interfejs wiersza polecenia platformy Azure

Użyj polecenia , az servicebus topic subscription rule create aby utworzyć regułę lub filtrować dla subskrypcji.

Korzystanie z programu Azure PowerShell

Użyj polecenia , Set-AzServiceBusRule aby utworzyć regułę lub filtrować dla subskrypcji.

Uwaga

Reguła subskrypcji składa się z filtrów i akcji. Akcje można określić przy użyciu interfejsu wiersza polecenia i programu PowerShell, ale nie przy użyciu witryny Azure Portal.

Filtrowanie we właściwościach systemu

Aby odwołać się do właściwości systemowej w filtrze, użyj następującego formatu: sys.<system-property-name>.

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

Uwaga

• Aby uzyskać listę właściwości systemu, zobacz Komunikaty, ładunki i serializacji.
• Użyj nazw właściwości systemowych z elementu Azure.Messaging.ServiceBus.ServiceBusMessage w filtrach.
• Subject z elementu Azure.Messaging.ServiceBus.ServiceBusMessage jest mapowany na Label element w przestarzałym pliku Microsoft.Azure.ServiceBus.Message.

Filtrowanie właściwości komunikatów

Poniżej przedstawiono przykłady używania właściwości aplikacji lub użytkownika w filtrze. Możesz uzyskać dostęp do właściwości aplikacji ustawionych przy użyciu właściwości azure.Messaging.ServiceBus.ServiceBusMessage.ApplicationProperties) (najnowsza wersja) lub właściwości użytkownika ustawionych przez microsoft.Azure.ServiceBusMessage (przestarzałe) przy użyciu składni: user.property-name lub tylko property-name.

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

30 września 2026 r. wycofamy biblioteki zestawu SDK usługi Azure Service Bus WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus i com.microsoft.azure.servicebus, które nie są zgodne z wytycznymi dotyczącymi zestawu Azure SDK. Zakończymy również obsługę protokołu SBMP, więc nie będzie można już używać tego protokołu po 30 września 2026 r. Przeprowadź migrację do najnowszych bibliotek zestawu Azure SDK, które oferują krytyczne aktualizacje zabezpieczeń i ulepszone możliwości przed tą datą.

Mimo że starsze biblioteki mogą być nadal używane poza 30 września 2026 r., nie będą już otrzymywać oficjalnej pomocy technicznej i aktualizacji od firmy Microsoft. Aby uzyskać więcej informacji, zobacz ogłoszenie o wycofaniu pomocy technicznej.

Filtruj właściwości wiadomości z znakami specjalnymi

Jeśli nazwa właściwości komunikatu ma znaki specjalne, użyj cudzysłowów podwójnych ("), aby ująć nazwę właściwości. Jeśli na przykład nazwa właściwości to "http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName", użyj następującej składni w filtrze.

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

Filtrowanie właściwości komunikatów przy użyciu wartości liczbowych

W poniższych przykładach pokazano, jak można używać właściwości z wartościami liczbowymi w filtrach.

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

Filtry oparte na parametrach

Oto kilka przykładów używania filtrów opartych na parametrach. W tych przykładach DataTimeMp jest właściwością komunikatu typu DateTime i @dtParam jest parametrem przekazywanym do filtru DateTime jako obiektu.

DateTimeMp < @dtParam
DateTimeMp > @dtParam

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

Używanie funkcji IN i 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')

Aby zapoznać się z przykładem języka C#, zobacz Przykładowe filtry tematów w witrynie GitHub.

Filtry korelacji

Filtr korelacji przy użyciu identyfikatora CorrelationID

new CorrelationFilter("Contoso");

Filtruje komunikaty z ustawioną wartością CorrelationID Contoso.

Uwaga

Klasa CorrelationRuleFilter na platformie .NET znajduje się w przestrzeni nazw Azure.Messaging.ServiceBus.Administration . Przykładowy kod pokazujący sposób tworzenia filtrów ogólnie przy użyciu platformy .NET można znaleźć w tym kodzie w witrynie GitHub.

Filtr korelacji przy użyciu właściwości systemu i użytkownika

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

Jest to równoważne: sys.ReplyTo = 'johndoe@contoso.com' AND sys.Label = 'Important' AND color = 'Red'

Przykład platformy .NET dotyczący tworzenia filtrów subskrypcji

Oto przykład języka C# platformy .NET, który tworzy następujące jednostki usługi Service Bus:

• Temat usługi Service Bus o nazwie topicfiltersampletopic
• Subskrypcja tematu o nazwie AllOrders z filtrem reguły true, który jest odpowiednikiem filtru reguły SQL z wyrażeniem 1=1.
• Subskrypcja o nazwie z ColorBlueSize10Orders wyrażeniem filtru SQL color='blue' AND quantity=10
• Subskrypcja o nazwie z ColorRed wyrażeniem color='red' filtru SQL i akcją
• Subskrypcja o nazwie HighPriorityRedOrders z wyrażeniem filtru korelacji Subject = "red", CorrelationId = "high"

Aby uzyskać więcej informacji, zobacz komentarze kodu wbudowanego.

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

Przykład platformy .NET do wysyłania komunikatów odbierających

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

Następne kroki

Zobacz następujące przykłady:

• Zarządzanie regułami
• .NET — filtry tematów
• Szablon usługi Azure Resource Manager

Aby zapoznać się z funkcjami usługi Azure Service Bus, wypróbuj przykłady w wybranym języku.

• Przykłady biblioteki klienta usługi Azure Service Bus dla platformy .NET (najnowsza wersja)
• Przykłady biblioteki klienta usługi Azure Service Bus dla języka Java (najnowsza wersja)
• Przykłady biblioteki klienta usługi Azure Service Bus dla języka Python
• Przykłady biblioteki klienta usługi Azure Service Bus dla języka JavaScript
• Przykłady biblioteki klienta usługi Azure Service Bus dla języka TypeScript