Partilhar via

Filtros de tópico e ações

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 da linguagem SQL para condições de filtro testa a existência de propriedades (EXISTS), valores nulos (IS NULL), operadores lógicos, operadores relacionaisNOT/AND/OR, aritmética numérica simples, e correspondência de padrão 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 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 é comparar com a propriedade CorrelationId, mas a aplicação também pode optar por comparar com as 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 CorrelationRuleFilter construtor padrão, pode atribuir propriedades do ContentType, Label, MessageId, ReplyTo, ReplyToSessionId, SessionId, To sistema e propriedades definidas pelo utilizador 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, 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, as entrega em uma assinatura, elas são ignoradas. Embora sejam reavaliados ao serem encaminhados automaticamente para outra fila ou tópico.

  • 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 ele vem 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 a funcionalidade de encaminhamento automático, os filtros de tópicos podem ser usados para criar esquemas de encaminhamento complexos num namespace do Service Bus para a distribuição de mensagens numa 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.

  • Last updated on