Compartilhar via

Ações e filtros de tópico

  • Artigo

Os assinantes podem definir quais mensagens desejam receber de um tópico. Essas mensagens são especificadas na forma de uma ou mais regras de assinatura nomeadas. Cada regra consiste em uma condição de filtro que seleciona mensagens específicas e como opção contém uma ação que anota a mensagem selecionada.

Todas as regras sem ações são combinadas usando uma condição OR e resultam em uma única mensagem na assinatura mesmo que você tenha várias regras de correspondência.

Cada regra com uma ação produz uma cópia da mensagem. Essa mensagem terá uma propriedade chamada RuleName onde o valor é o nome da regra de correspondência. A ação pode adicionar ou atualizar propriedades ou excluir propriedades da mensagem original para produzir uma mensagem na assinatura.

Considere o cenário a seguir em que uma assinatura tem cinco regras: duas regras com ações e as outras três sem ações. Neste exemplo, se você enviar uma mensagem que corresponda a todas as cinco regras, receberá três mensagens na assinatura. Essas são duas mensagens para duas regras com ações e uma mensagem para três regras sem ações.

Cada assinatura de tópico recém-criada tem uma regra de assinatura padrão inicial. Se você não especificar explicitamente uma condição de filtro para a regra, o filtro aplicado é o filtro true que permite que todas as mensagens sejam selecionadas na assinatura. A regra padrão não tem nenhuma ação de anotação associada.

Observação

Este artigo se aplica a cenários não JMS. Para cenários JMS, use seletores de mensagem.

Filtros

O Barramento de Serviço dá suporte a três tipos de filtros:

  • Filtros SQL
  • Filtros boolianos
  • Filtros de correlação

As seções a seguir fornecem detalhes sobre esses filtros.

Filtros SQL

Um SqlFilter contém uma expressão condicional do tipo SQL que é avaliada no agente em relação às propriedades definidas pelo usuário e às propriedades do sistema das mensagens que chegam. Todas as propriedades de sistema devem ser prefixadas com sys. na expressão condicional. O subconjunto da linguagem SQL para condições de filtro testa a existência de propriedades (EXISTS), valores nulos (IS NULL), lógicos NOT/AND/OR, operadores relacionais, aritmética numérica simples e padrões correspondentes de texto simples com LIKE.

Aqui está um exemplo .NET para definir um filtro SQL:

adminClient = new ServiceBusAdministrationClient(connectionString);    

// Create a SQL filter with color set to blue and quantity to 10
await adminClient.CreateSubscriptionAsync(
		new CreateSubscriptionOptions(topicName, "ColorBlueSize10Orders"), 
		new CreateRuleOptions("BlueSize10Orders", new SqlRuleFilter("color='blue' AND quantity=10")));

// Create a SQL filter with color set to red
// Action is defined to set the quantity to half if the color is red
await adminClient.CreateRuleAsync(topicName, "ColorRed", new CreateRuleOptions 
{ 
	Name = "RedOrdersWithAction",
	Filter = new SqlRuleFilter("user.color='red'"),
	Action = new SqlRuleAction("SET quantity = quantity / 2;")
}

Filtros boolianos

O TrueFilter e o FalseFilter fazem com que todas as mensagens que chegam (true) ou nenhuma das mensagens que chegam (false) sejam selecionadas para a assinatura. Esses dois filtros derivam do filtro SQL.

Aqui está um exemplo .NET para definir um filtro booleano:

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

Filtros de correlação

Um CorrelationFilter contém um conjunto de condições que são comparadas com uma ou mais propriedades do sistema e do usuário de uma mensagem recebida. Um uso comum é fazer a correspondência com a propriedade CorrelationId, mas o aplicativo também pode optar por corresponder às seguintes propriedades:

  • ContentType
  • Label
  • MessageId
  • ReplyTo
  • ReplyToSessionId
  • SessionId
  • To
  • qualquer propriedade definida pelo usuário.

Uma correspondência existe quando o valor de uma propriedade de uma mensagem recebida é igual ao valor especificado no filtro de correlação. Para expressões de cadeia de caracteres, a comparação diferencia maiúsculas de minúsculas. Se você especificar várias propriedades de correspondência, o filtro as combinará como uma condição lógica AND, e isso significa que para o filtro corresponder todas as condições deverão corresponder.

Aqui está um exemplo .NET para definir um filtro de correlação:

// Create a correlation filter with color set to Red and priority set to High
await adminClient.CreateSubscriptionAsync(
		new CreateSubscriptionOptions(topicName, "HighPriorityRedOrders"), 
		new CreateRuleOptions("HighPriorityRedOrdersRule", new CorrelationRuleFilter() {Subject = "red", CorrelationId = "high"} ));

Use o construtor CorrelationRuleFilter que aceita um String argumento para criar um filtro de correlação com uma ID de correlação.

Ao usar o construtor CorrelationRuleFilter padrão, você pode atribuir propriedades do sistema (ContentType, Label, MessageId, ReplyTo, ReplyToSessionId, SessionId, To) e propriedades definidas pelo usuário para filtragem. Para especificar propriedades definidas pelo usuário para filtro de correlação, use a propriedade Properties do tipo IDictionary <string, object>. As chaves para esse dicionário são as propriedades definidas pelo usuário a serem pesquisadas nas mensagens. Os valores associados às chaves são os valores a serem correlacionados. Veja este exemplo.

var filter = new CorrelationFilter();
filter.Label = "abc";
filter.ReplyTo = "xdeu@hotmail.com";
filter.Properties["prop1"] = "abc";
filter.Properties["prop2"] = "xyz";

Observação

  • Todos os filtros avaliam as propriedades da mensagem. Os filtros não podem avaliar o corpo da mensagem.
  • Regras de filtro complexas requerem capacidade de processamento. Em particular, o uso de regras de filtro SQL resulta em uma taxa de transferência de mensagem geral menor no nível da assinatura, do tópico e do namespace. Sempre que possível, os aplicativos devem escolher os filtros de correlação em detrimento dos filtros do tipo SQL, pois eles são muito mais eficientes no processamento e, portanto, têm menos impacto na taxa de transferência.

Ações

Com condições de filtro SQL, você pode definir uma ação que pode anotar a mensagem adicionando, removendo ou substituindo propriedades e seus valores. A ação usa uma expressão do tipo SQL que se baseia livremente na sintaxe da instrução SQL UPDATE. A ação é executada na mensagem depois de ter sido correspondida e antes de a mensagem ser selecionada na assinatura. As alterações nas propriedades de mensagem são particulares para a mensagem copiada para a assinatura.

Aqui está um exemplo .NET que cria uma regra SQL com uma ação para atualizar a quantidade quando a cor for vermelha.

adminClient = new ServiceBusAdministrationClient(connectionString);    

// Create a SQL filter with color set to red
// Action is defined to set the quantity to half if the color is red
await adminClient.CreateRuleAsync(topicName, "ColorRed", new CreateRuleOptions 
{ 
	Name = "RedOrdersWithAction",
	Filter = new SqlRuleFilter("user.color='red'"),
	Action = new SqlRuleAction("SET quantity = quantity / 2;")
}

Importante

Ao atualizar as propriedades do sistema por meio de ações de regra, observe que ela pode alterar o comportamento esperado. Algumas propriedades só são avaliadas quando uma mensagem é recebida em uma fila ou em um tópico. Portanto, quando você atualiza essas propriedades em uma ação de regra e as entrega em uma assinatura, elas são ignoradas. No entanto, ao encaminhar automaticamente para outra fila ou tópico, elas são reavaliadas.

  • ScheduledEnqueueTime: quando você define ou atualiza essa propriedade, ela é ignorada na assinatura.
  • MessageID com eliminação de duplicação: nenhuma eliminação de duplicação é executada na assinatura quando a MessageID é atualizada e resulta em uma duplicata.
  • SessionID com particionamento: nesse cenário, a ID da sessão é a chave de partição para entidades particionadas e é usada para decidir a partição para a qual a mensagem é enviada. A alteração da sessionID em uma ação de regra significa que a chave de partição é alterada depois que uma mensagem é colocada em uma partição. Como resultado, o consumidor pode não receber algumas dessas mensagens na sessão. Mesmo que o consumidor receba a mensagem, ela aparece como se estivesse vindo da partição errada devido à chave de partição alterada.

Padrões de uso

  • Transmissão padrão

    O cenário de uso mais simples para um tópico é que cada assinatura obtém uma cópia de cada mensagem enviada para um tópico, o que permite um padrão de difusão.

  • Particionamento padrão

    O particionamento usa filtros para distribuir mensagens através de várias assinaturas de tópicos existentes de maneira previsível e mutuamente exclusiva. O padrão de particionamento é usado quando um sistema é escalado horizontalmente para lidar com muitos contextos diferentes em compartimentos funcionalmente idênticos que mantêm um subconjunto dos dados dos gerais. Por exemplo, informações de perfil do cliente. Com o particionamento, um editor envia a mensagem em um tópico sem a necessidade de qualquer conhecimento do modelo de particionamento. Depois, a mensagem é movida para a assinatura correta da qual ela pode ser recuperada pelo manipulador de mensagens da partição.

  • Roteamento padrão

    O roteamento usa filtros para distribuir mensagens através de assinaturas de tópicos de maneira previsível, mas não necessariamente exclusiva. Em conjunto com o recurso de encaminhamento automático, os filtros de tópico podem ser usados para criar grafos de roteamento complexos dentro de um namespace do Barramento de Serviço para a distribuição de mensagens dentro de uma região do Azure. Com o Azure Functions ou os Aplicativos Lógicos do Azure atuando como uma ponte entre os namespaces do Barramento de Serviço do Azure, você pode criar tecnologias globais complexas com integração direta em aplicativos de linhas de negócios.

Observação

Como o portal do Azure agora dá suporte à funcionalidade do Service Bus Explorer, os filtros de assinatura podem ser criados ou editados no portal.

Próximas etapas

Para obter mais exemplos, confira Exemplos de filtro do Barramento de Serviço.