Nastavení filtrů předplatného (Azure Service Bus)

Článek
07/19/2024

Tento článek obsahuje několik příkladů nastavení filtrů pro odběry témat služby Service Bus. Koncepční informace o filtrech najdete v tématu Filtry.

Použití webu Azure Portal

Pokud chcete nastavit filtry předplatného na webu Azure Portal, použijte část Filtry na stránce Předplatné služby Service Bus.

Použití Azure CLI

az servicebus topic subscription rule create Použijte k vytvoření pravidla nebo filtrování předplatného.

Použití Azure Powershell

Set-AzServiceBusRule Použijte k vytvoření pravidla nebo filtrování předplatného.

Poznámka:

Pravidlo předplatného se skládá z filtrů a akcí. Akce můžete zadat pomocí rozhraní příkazového řádku a PowerShellu, ale ne pomocí webu Azure Portal.

Filtrování vlastností systému

Chcete-li odkazovat na systémovou vlastnost ve filtru, použijte následující formát: sys.<system-property-name>.

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

Poznámka:

Seznam systémových vlastností naleznete v tématu Zprávy, datové části a serializace.
Ve filtrech použijte názvy systémových vlastností z Azure.Messaging.ServiceBus.ServiceBusMessage .
Subject z Azure.Messaging.ServiceBus.ServiceBusMessage se mapuje na Label zastaralé zprávy Microsoft.Azure.ServiceBus.Message.

Filtrování vlastností zprávy

Tady jsou příklady použití vlastností aplikace nebo uživatele ve filtru. K vlastnostem aplikace nastaveným pomocí Azure.Messaging.ServiceBus.ServiceBusMessage.ApplicationProperties) (nejnovější) nebo uživatelských vlastností nastavených microsoft.Azure.ServiceBus.ServiceBusMessage (zastaralé) můžete získat přístup pomocí syntaxe: user.property-name nebo jen property-name.

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

30. září 2026 vyřadíme knihovny sady SDK služby Azure Service Bus pro WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus a com.microsoft.azure.servicebus, které nevyhovují pokynům sady Azure SDK. Také ukončíme podporu protokolu SBMP, takže tento protokol už nebudete moct používat po 30. září 2026. Před tímto datem migrujte na nejnovější knihovny sady Azure SDK, které nabízejí důležité aktualizace zabezpečení a vylepšené funkce.

I když starší knihovny je možné používat i po 30. září 2026, nebudou už od Microsoftu dostávat oficiální podporu a aktualizace. Další informace najdete v oznámení o vyřazení podpory.

Filtrování vlastností zprávy se speciálními znaky

Pokud název vlastnosti zprávy obsahuje speciální znaky, použijte dvojité uvozovky (") k uzavření názvu vlastnosti. Pokud je "http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName"například název vlastnosti, použijte ve filtru následující syntaxi.

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

Filtrování vlastností zpráv pomocí číselných hodnot

Následující příklady ukazují, jak můžete použít vlastnosti s číselnými hodnotami ve filtrech.

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

Filtry založené na parametrech

Tady je několik příkladů použití filtrů založených na parametrech. V těchto příkladech DataTimeMp je vlastnost zprávy typu DateTime a @dtParam je parametr předaný filtru jako DateTime objekt.

DateTimeMp < @dtParam
DateTimeMp > @dtParam

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

Použití IN a 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')

Ukázku jazyka C# najdete v ukázce filtrů témat na GitHubu.

Korelační filtry

Filtr korelace pomocí ID korelace

new CorrelationFilter("Contoso");

Filtruje zprávy s nastaveným CorrelationID parametrem Contoso.

Poznámka:

Třída CorrelationRuleFilter v .NET je v oboru názvů Azure.Messaging.ServiceBus.Administration . Ukázkový kód, který ukazuje, jak vytvořit filtry obecně pomocí .NET, najdete v tomto kódu na GitHubu.

Korelační filtr s využitím systémových a uživatelských vlastností

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

Je to ekvivalentní: sys.ReplyTo = 'johndoe@contoso.com' AND sys.Label = 'Important' AND color = 'Red'

Příklad .NET pro vytváření filtrů předplatného

Tady je příklad .NET C#, který vytvoří následující entity služby Service Bus:

Téma služby Service Bus s názvem topicfiltersampletopic
Odběr tématu pojmenovaného AllOrders pomocí filtru true rule, který je ekvivalentní filtru pravidla SQL s výrazem 1=1.
Předplatné pojmenované ColorBlueSize10Orders pomocí výrazu filtru SQL color='blue' AND quantity=10
Předplatné s názvem ColorRed výrazem color='red' filtru SQL a akcí
Předplatné pojmenované HighPriorityRedOrders pomocí výrazu filtru korelace Subject = "red", CorrelationId = "high"

Další informace najdete v komentářích vloženého kódu.

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

Příklad .NET pro odesílání přijatých zpráv

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

Další kroky

Projděte si následující ukázky:

Pokud chcete prozkoumat funkce služby Azure Service Bus, vyzkoušejte ukázky v jazyce podle vašeho výběru.

Sdílet prostřednictvím

Nastavení filtrů předplatného (Azure Service Bus)

Použití webu Azure Portal

Použití Azure CLI

Použití Azure Powershell

Filtrování vlastností systému

Filtrování vlastností zprávy

Filtrování vlastností zprávy se speciálními znaky

Filtrování vlastností zpráv pomocí číselných hodnot

Filtry založené na parametrech

Použití IN a NOT IN

Korelační filtry

Filtr korelace pomocí ID korelace

Korelační filtr s využitím systémových a uživatelských vlastností

Příklad .NET pro vytváření filtrů předplatného

Příklad .NET pro odesílání přijatých zpráv

Další kroky

Váš názor

Další materiály