Definir filtros de assinatura (Barramento de Serviço do Azure)
Este artigo fornece alguns exemplos sobre como definir filtros nas assinaturas para os tópicos do Barramento de Serviço. Para obter informações conceituais sobre os filtros, confira Filtros.
Usar o portal do Azure
Para definir filtros de assinatura no portal do Azure, use a seção Filtros da página Assinatura do Barramento de Serviços.
Usar a CLI do Azure
Use az servicebus topic subscription rule create para criar uma regra ou filtro em uma assinatura.
Usar PowerShell do Azure
Use Set-AzServiceBusRule para criar uma regra ou filtro em uma assinatura.
Observação
Uma regra de assinatura consiste em filtros e ações. Você pode especificar ações usando a CLI e o PowerShell, mas não usando o portal do Microsoft Azure.
Filtrar por propriedades do sistema
Para fazer referência a uma propriedade do sistema em um filtro, use o seguinte formato: sys.<system-property-name>.
sys.label LIKE '%bus%'
sys.messageid = 'xxxx'
sys.correlationid like 'abc-%'
Observação
- Para obter uma lista de propriedades do sistema, confira Mensagens, cargas e serialização.
- Use nomes de propriedade do sistema de Azure.Messaging.ServiceBus.ServiceBusMessage em seus filtros.
Subjectde Azure.Messaging.ServiceBus.ServiceBusMessage mapeia paraLabelno Microsoft.Azure.ServiceBus.Message preterido.
Filtrar por propriedades da mensagem
Aqui estão alguns exemplos de como usar as propriedades do aplicativo ou do usuário em um filtro. Você pode acessar as propriedades do aplicativo definidas usando Azure.Messaging.ServiceBus.ServiceBusMessage.ApplicationProperties) (mais recente) ou as propriedades do usuário definidas por Microsoft.Azure.ServiceBus.ServiceBusMessage (preterido) usando a sintaxe: user.property-name ou apenas property-name.
MessageProperty = 'A'
user.SuperHero like 'SuperMan%'
Em 30 de setembro de 2026, desativaremos as bibliotecas do SDK do Barramento de Serviço do Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, que não estão em conformidade com as diretrizes do SDK do Azure. Também encerraremos o suporte ao protocolo SBMP, portanto, ele não poderá mais ser usado após 30 de setembro de 2026. Antes dessa data, migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e funcionalidades aprimoradas.
Embora as bibliotecas mais antigas ainda poderão ser usadas após 30 de setembro de 2026, elas não receberão mais suporte e atualizações oficiais da Microsoft. Para obter mais informações, confira o anúncio de desativação do suporte.
Filtrar por propriedades da mensagem com caracteres especiais
Se o nome da propriedade da mensagem tiver caracteres especiais, envolva-o em aspas duplas ("). Por exemplo, se o nome da propriedade for "http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName", use a sintaxe a seguir no filtro.
"http://schemas.microsoft.com/xrm/2011/Claims/EntityLogicalName" = 'account'
Filtrar por propriedades da mensagem com valores numéricos
Os exemplos a seguir mostram como você pode usar propriedades com valores numéricos em filtros.
MessageProperty = 1
MessageProperty > 1
MessageProperty > 2.08
MessageProperty = 1 AND MessageProperty2 = 3
MessageProperty = 1 OR MessageProperty2 = 3
Filtros baseados em parâmetros
Aqui estão alguns exemplos de como usar filtros baseados em parâmetros. Nesses exemplos, DataTimeMp é uma propriedade de mensagem do tipo DateTime e @dtParam é um parâmetro passado para o filtro como um objeto DateTime.
DateTimeMp < @dtParam
DateTimeMp > @dtParam
(DateTimeMp2-DateTimeMp1) <= @timespan //@timespan is a parameter of type TimeSpan
DateTimeMp2-DateTimeMp1 <= @timespan
Usando 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')
Para ver um exemplo em C#, confira o Exemplo de filtros de tópico no GitHub.
Filtros de correlação
Filtro de correlação usando CorrelationID
new CorrelationFilter("Contoso");
Ele filtra mensagens com CorrelationID definido como Contoso.
Observação
A classe CorrelationRuleFilter no .NET está no namespace Azure.Messaging.ServiceBus.Administration . Para obter um exemplo de código que mostra como criar filtros em geral usando o .NET, consulte este código em GitHub.
Filtro de correlação usando propriedades do sistema e do usuário
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'
Exemplo do .NET para criar filtros de assinatura
Aqui está um exemplo do .NET C# que cria as seguintes entidades de Barramento de Serviço:
- Tópico do Barramento de Serviço denominado
topicfiltersampletopic - Assinatura do tópico nomeado
AllOrderscom um filtro True Rule, que é equivalente a um filtro de regra SQL com a expressão1=1. - Assinatura nomeada
ColorBlueSize10Orderscom uma expressão de filtro SQLcolor='blue' AND quantity=10 - Assinatura nomeada
ColorRedcom uma expressão de filtro SQLcolor='red'e uma ação - Assinatura nomeada
HighPriorityRedOrderscom uma expressão de filtro de correlaçãoSubject = "red", CorrelationId = "high"
Para obter mais informações, consulte os comentários de código em linha.
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());
}
}
}
}
Exemplo do .NET para enviar e receber mensagens
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;
}
}
}
Próximas etapas
Confira as seguintes amostras:
Para explorar os recursos do Barramento de Serviço do Azure, experimente os exemplos no idioma de sua escolha.
- Exemplos da biblioteca de clientes do Barramento de Serviço do Azure para .NET (mais recentes)
- Amostras da biblioteca de clientes do Barramento de Serviço do Azure para Java (mais recentes)
- Exemplos da biblioteca de clientes do Barramento de Serviço do Azure para Python
- Exemplos da biblioteca de clientes do Barramento de Serviço do Azure para JavaScript
- Exemplos da biblioteca de clientes do Barramento de Serviço do Azure para TypeScript