Impostare i filtri di sottoscrizione (bus di servizio di Azure)
Questo articolo fornisce alcuni esempi sull'impostazione dei filtri per le sottoscrizioni per gli argomenti del bus di servizio. Per informazioni concettuali sui filtri, vedere Filtri.
Usare il portale di Azure
Per impostare i filtri delle sottoscrizioni nel portale di Azure, usare la sezione Filtri della pagina Sottoscrizione del bus di servizio.
Utilizzare l'interfaccia della riga di comando di Azure
Usare az servicebus topic subscription rule create per creare una regola o filtrare in base a una sottoscrizione.
Usare Azure PowerShell
Usare Set-AzServiceBusRule per creare una regola o filtrare in base a una sottoscrizione.
Nota
Una regola di sottoscrizione è costituita da filtri e azioni. È possibile specificare le azioni usando l'interfaccia della riga di comando e PowerShell, ma non il portale di Azure.
Filtrare per proprietà di sistema
Per fare riferimento a una proprietà di sistema in un filtro, usare il formato seguente: sys.<system-property-name>.
sys.label LIKE '%bus%'
sys.messageid = 'xxxx'
sys.correlationid like 'abc-%'
Nota
- Per un elenco delle proprietà di sistema, vedere Messaggi, payload e serializzazione.
- Usare i nomi delle proprietà di sistema di Azure.Messaging.ServiceBus.ServiceBusMessage nei filtri.
Subjectda Azure.Messaging.ServiceBus.ServiceBusMessage esegue il mapping perLabelnell'oggetto Microsoft.Azure.ServiceBus.Message deprecato.
Filtrare per proprietà dei messaggi
Ecco gli esempi di utilizzo delle proprietà dell'applicazione o dell'utente in un filtro. È possibile accedere al set di proprietà dell'applicazione impostate usando Azure.Messaging.ServiceBus.ServiceBusMessage.ApplicationProperties (versione più recente) o il set proprietà utente impostate da Microsoft.Azure.ServiceBus.ServiceBusMessage (deprecato) usando la sintassi: user.property-name o semplicemente property-name.
MessageProperty = 'A'
user.SuperHero like 'SuperMan%'
Il 30 settembre 2026 verranno ritirate le librerie dell'SDK del bus di servizio di Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, che non sono conformi alle linee guida di Azure SDK. Verrà terminato anche il supporto del protocollo SBMP, quindi non sarà più possibile usare questo protocollo dopo il 30 settembre 2026. Eseguire la migrazione alle librerie più recenti di Azure SDK, che offrono aggiornamenti critici della sicurezza e funzionalità migliorate, prima di tale data.
Anche se le librerie precedenti possono ancora essere usate oltre il 30 settembre 2026, non riceveranno più il supporto e gli aggiornamenti ufficiali da Microsoft. Per altre informazioni, vedere l'annuncio del ritiro del supporto.
Filtrare per proprietà dei messaggi con caratteri speciali
Se il nome della proprietà del messaggio contiene caratteri speciali, usare le virgolette doppie (") per racchiudere il nome della proprietà. Ad esempio, se il nome della proprietà è "http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName", nel filtro usare la sintassi seguente.
"http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName" = 'account'
Filtrare per proprietà dei messaggi con valori numerici
Negli esempi seguenti viene illustrato come usare le proprietà con valori numerici nei filtri.
MessageProperty = 1
MessageProperty > 1
MessageProperty > 2.08
MessageProperty = 1 AND MessageProperty2 = 3
MessageProperty = 1 OR MessageProperty2 = 3
Filtri basati su parametri
Di seguito sono riportati alcuni esempi di uso di filtri basati su parametri. In questi esempi, DataTimeMp è una proprietà del messaggio di tipo DateTime ed @dtParam è un parametro passato al filtro come oggetto DateTime.
DateTimeMp < @dtParam
DateTimeMp > @dtParam
(DateTimeMp2-DateTimeMp1) <= @timespan //@timespan is a parameter of type TimeSpan
DateTimeMp2-DateTimeMp1 <= @timespan
Uso di IN e 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')
Per un campione C#, vedere Campione di filtri di argomento in GitHub.
Filtri di correlazione
Filtro di correlazione usando CorrelationID
new CorrelationFilter("Contoso");
Filtra i messaggi con CorrelationID impostato su Contoso.
Nota
La classe CorrelationRuleFilter in .NET si trova nello spazio dei nomi Azure.Messaging.ServiceBus.Administration. Per il codice di esempio che illustra come creare filtri in generale usando .NET, vedere questo codice in GitHub.
Filtro di correlazione usando le proprietà di sistema e utente
var filter = new CorrelationRuleFilter();
filter.Label = "Important";
filter.ReplyTo = "johndoe@contoso.com";
filter.Properties["color"] = "Red";
È equivalente a: sys.ReplyTo = 'johndoe@contoso.com' AND sys.Label = 'Important' AND color = 'Red'
Esempio .NET per la creazione dei filtri di sottoscrizione
Ecco un esempio di C# .NET che crea le entità del bus di servizio seguenti:
- Argomento del bus di servizio denominato
topicfiltersampletopic - Sottoscrizione all'argomento denominato
AllOrderscon un filtro regola vero, equivalente a un filtro di regola SQL con espressione1=1. - Sottoscrizione denominata
ColorBlueSize10Orderscon un'espressione filtro SQLcolor='blue' AND quantity=10 - Sottoscrizione denominata
ColorRedcon un'espressione filtro SQLcolor='red'e un'azione - Sottoscrizione denominata
HighPriorityRedOrderscon un'espressione filtro di correlazioneSubject = "red", CorrelationId = "high"
Per ulteriori informazioni, vedere i commenti del codice inline.
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());
}
}
}
}
Esempio di .NET per l'invio di messaggi di ricezione
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;
}
}
}
Passaggi successivi
Vedere gli esempi seguenti:
Per esplorare le funzionalità del bus di servizio di Azure, provare gli esempi in un linguaggio a scelta.
- Esempi di libreria client del bus di servizio di Azure per .NET (versione più recente)
- Esempi di libreria client del bus di servizio di Azure per Java (versione più recente)
- Libreria client del bus di servizio di Azure per Python
- Esempi di libreria client del bus di servizio di Azure per JavaScript
- Esempi di libreria client del bus di servizio di Azure per TypeScript