Partilhar via

Filtros de tópico e ações

  • Artigo

Os subscritores podem definir as mensagens que pretendem receber de um tópico. Estas mensagens são especificadas na forma de uma ou mais regras de subscrição denominadas. Cada regra consiste em uma condição de filtro que seleciona mensagens específicas e , opcionalmente , contém uma ação que anota a mensagem selecionada.

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

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

Considere o seguinte cenário 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. 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 será o filtro verdadeiro que permite que todas as mensagens sejam selecionadas na assinatura. A regra padrão não tem nenhuma ação de anotação associada.

Nota

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

Filtros

O Service Bus suporta três tipos de filtros:

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

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

Filtros SQL

Um SqlFilter contém uma expressão condicional semelhante a SQL que é avaliada no broker em relação às propriedades definidas pelo usuário e às propriedades do sistema das mensagens que chegam. Todas as propriedades do sistema devem ser prefixadas com sys. na expressão condicional. O subconjunto de linguagem SQL para condições de filtro testa a existência de propriedades (EXISTS), valores nulos (IS NULL), operadores lógicosAND//NOTOR, relacionais, aritmética numérica simples e padrão de texto simples combinando 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 booleanos

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 do .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 das propriedades do usuário e do sistema de uma mensagem que chega. Um uso comum é corresponder à propriedade CorrelationId , mas o aplicativo também pode optar por corresponder às seguintes propriedades:

  • ContentType
  • Label
  • MessageId
  • ReplyTo
  • ReplyToSessionId
  • SessionId
  • To
  • quaisquer propriedades definidas pelo usuário.

Existe uma correspondência quando o valor de uma mensagem que chega para uma propriedade é 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 E, ou seja, para que o filtro corresponda, todas as condições deverão corresponder.

Aqui está um exemplo do .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 CorrelationRuleFilter construtor que usa um String argumento para criar um filtro de correlação com uma ID de correlação.

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

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

Nota

  • Todos os filtros avaliam as propriedades da mensagem. Os filtros não podem avaliar o corpo da mensagem.
  • Regras de filtro complexas exigem capacidade de processamento. Em particular, o uso de regras de filtro SQL causa menor taxa de transferência geral de mensagens no nível de assinatura, tópico e namespace. Sempre que possível, os aplicativos devem escolher filtros de correlação em vez de filtros semelhantes ao SQL porque eles são muito mais eficientes no processamento e têm menos impacto na taxa de transferência.

Ações

Com as 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 semelhante a SQL que se apoia vagamente na sintaxe da SQL UPDATE instrução. A ação é executada na mensagem depois de ter sido correspondida e antes de a mensagem ser selecionada na subscrição. As alterações nas propriedades da mensagem são privadas 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 é Vermelho.

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

Quando você atualiza as propriedades do sistema por meio de ações de regra, observe que isso 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, em seguida, entregá-las em uma assinatura, elas são ignoradas. Embora, ao encaminhar automaticamente para outra fila ou tópico, eles sejam reavaliados.

  • ScheduledEnqueueTime: Quando você define ou atualiza essa propriedade, ela é ignorada na assinatura.
  • MessageID com desduplicação: Nenhuma desduplicação é executada na assinatura quando o MessageID é atualizado e resulta em uma duplicata.
  • SessionID com particionamento: Neste cenário, o ID de sessão é a chave de partição para entidades particionadas e é usado para decidir a partição para a qual a mensagem é enviada. Alterar o sessionID em uma ação de regra significa que a chave de partição é alterada depois que uma mensagem chega a uma partição. Como resultado, o consumidor pode não receber algumas dessas mensagens na sessão. Mesmo que o consumidor receba a mensagem, parece que eles estão vindo da partição errada devido à chave de partição alterada.

Padrões de utilização

  • Padrão de transmissão

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

  • Padrão de particionamento

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

  • Padrão de roteamento

    O roteamento usa filtros para distribuir mensagens entre assinaturas de tópicos de forma 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 gráficos de roteamento complexos em um namespace do Service Bus para distribuição de mensagens em uma região do Azure. Com o Azure Functions ou os Aplicativos Lógicos do Azure atuando como uma ponte entre namespaces do Barramento de Serviço do Azure, você pode criar topologias globais complexas com integração direta em aplicativos de linha de negócios.

Nota

Como o portal do Azure agora oferece suporte à funcionalidade do Service Bus Explorer, os filtros de assinatura podem ser criados ou editados a partir do portal.

Próximos passos

Para obter mais exemplos, consulte Exemplos de filtro do Service Bus.