Establecimiento de filtros de suscripciones (Azure Service Bus)
En este artículo se proporcionan algunos ejemplos sobre cómo establecer filtros en las suscripciones a temas de Service Bus. Para obtener información conceptual acerca de los filtros, consulte Filtros.
Usar Azure Portal
Para establecer filtros de suscripción en Azure Portal, use la sección Filtros de la página Suscripción de Service Bus.
Uso de CLI de Azure
Use el az servicebus topic subscription rule create para crear una regla o filtrar en una suscripción.
Uso de Azure PowerShell
Use el Set-AzServiceBusRule para crear una regla o filtrar en una suscripción.
Nota:
Una regla de suscripción consta de filtros y acciones. Puede especificar acciones mediante la CLI y PowerShell, pero no mediante Azure Portal.
Filtrado por propiedades del sistema
Para hacer referencia a una propiedad del sistema en un filtro, utilice el siguiente formato: sys.<system-property-name>.
sys.label LIKE '%bus%'
sys.messageid = 'xxxx'
sys.correlationid like 'abc-%'
Nota
- Para obtener una lista de las propiedades del sistema, consulte Mensajes, cargas y serialización.
- Usa nombres de propiedad del sistema de Azure.Messaging.ServiceBus.ServiceBusMessage en los filtros.
Subjectde Azure.Messaging.ServiceBus.ServiceBusMessage se asigna aLabelen el Microsoft.Azure.ServiceBus.Message obsoleto.
Filtrado por propiedades de mensaje
Estos son ejemplos de cómo usar las propiedades de la aplicación o el usuario en un filtro. Puede acceder a las propiedades de la aplicación establecidas mediante Azure.Messaging.ServiceBus.ServiceBusMessage.ApplicationProperties) (más reciente) o a las propiedades del usuario establecidas mediante Microsoft.Azure.ServiceBus.ServiceBusMessage (en desuso) utilizando la sintaxis: user.property-name o simplemente property-name.
MessageProperty = 'A'
user.SuperHero like 'SuperMan%'
El 30 de septiembre de 2026, retiraremos del SDK de Azure Service Bus las bibliotecas WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus y com.microsoft.azure.servicebus, que no se ajusten a las directrices del SDK de Azure. También retiraremos el soporte del protocolo SBMP, por lo que ya no podrás usar este protocolo después del 30 de septiembre de 2026. Migre a las bibliotecas más recientes del SDK de Azure, que ofrecen actualizaciones de seguridad críticas y funcionalidades mejoradas, antes de esa fecha.
Aunque las bibliotecas anteriores todavía se pueden usar después del 30 de septiembre de 2026, ya no recibirán soporte técnico oficial ni actualizaciones de Microsoft. Para obtener más información, consulte el anuncio de retirada de soporte técnico.
Filtrado por propiedades del mensaje con caracteres especiales
Si el nombre de la propiedad del mensaje tiene caracteres especiales, use comillas dobles (") para incluir el nombre de la propiedad. Por ejemplo, si el nombre de la propiedad es "http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName", use la sintaxis siguiente en el filtro.
"http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName" = 'account'
Filtrado por propiedades del mensaje con valores numéricos
En los siguientes ejemplos se muestra cómo se pueden usar las propiedades con valores numéricos en los filtros.
MessageProperty = 1
MessageProperty > 1
MessageProperty > 2.08
MessageProperty = 1 AND MessageProperty2 = 3
MessageProperty = 1 OR MessageProperty2 = 3
Filtros basados en parámetros
Estos son algunos ejemplos de cómo usar filtros basados en parámetros. En estos ejemplos, DataTimeMp es una propiedad del mensaje de tipo DateTime y @dtParam es un parámetro que se pasa al filtro como un objeto DateTime.
DateTimeMp < @dtParam
DateTimeMp > @dtParam
(DateTimeMp2-DateTimeMp1) <= @timespan //@timespan is a parameter of type TimeSpan
DateTimeMp2-DateTimeMp1 <= @timespan
Usar IN y 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')
Para ver un ejemplo de C#, consulte el ejemplo de filtros de temas en GitHub.
Filtros de correlación
Filtro de correlación con CorrelationID
new CorrelationFilter("Contoso");
Filtra los mensajes con CorrelationID establecido en Contoso.
Nota
La clase CorrelationRuleFilter de .NET se encuentra en el espacio de nombres Azure.Messaging.ServiceBus.Administration. Para obtener código de ejemplo que muestra cómo crear filtros en general mediante .NET, vea este código en GitHub.
Filtro de correlación con propiedades del sistema y del usuario
var filter = new CorrelationRuleFilter();
filter.Label = "Important";
filter.ReplyTo = "johndoe@contoso.com";
filter.Properties["color"] = "Red";
Es equivalente a: sys.ReplyTo = 'johndoe@contoso.com' AND sys.Label = 'Important' AND color = 'Red'.
Ejemplo de .NET para crear filtros de suscripción
Este es un ejemplo de C# de .NET que crea las siguientes entidades de Service Bus:
- Tema de Service Bus denominado
topicfiltersampletopic - Suscripción al tema denominado
AllOrderscon un filtro True Rule, que es equivalente a un filtro de regla de SQL con la expresión1=1. - Suscripción denominada
ColorBlueSize10Orderscon una expresión de filtro de SQLcolor='blue' AND quantity=10 - Suscripción denominada
ColorRedcon una expresión de filtro de SQLcolor='red'y una acción - Suscripción denominada
HighPriorityRedOrderscon una expresión de filtro de correlaciónSubject = "red", CorrelationId = "high"
Para obtener más información, vea los comentarios de código insertados.
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());
}
}
}
}
Ejemplo de .NET para enviar y recibir mensajes
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;
}
}
}
Pasos siguientes
Consulte los ejemplos siguientes:
Para explorar las características de Azure Service Bus, pruebe los ejemplos en el idioma que prefiera.
- Ejemplos de la biblioteca cliente de Azure Service Bus para .NET (versión más reciente)
- Ejemplos de la biblioteca cliente de Azure Service Bus para Java (versión más reciente)
- Ejemplos de la biblioteca cliente de Azure Service Bus para Python
- Ejemplos de la biblioteca cliente de Azure Service Bus para JavaScript
- Ejemplos de la biblioteca cliente de Azure Service Bus para TypeScript