Partager via

Actions et filtres de rubrique

  • Article

Les abonnés peuvent définir les messages qu’ils veulent recevoir d’une rubrique. Ces messages sont spécifiés sous la forme d’une ou de plusieurs règles d’abonnement nommées. Chaque règle se compose d’une condition de filtre qui sélectionne des messages spécifiques et contient éventuellement une action qui annote le message sélectionné.

Toutes les règles sans action sont combinées à l’aide d’une condition OR et donnent lieu à un message unique sur l’abonnement, même si vous avez plusieurs règles correspondantes.

Chaque règle avec une action génère une copie du message. Ce message aura une propriété appelée RuleName, où la valeur est le nom de la règle correspondante. L’action peut ajouter ou mettre à jour des propriétés, ou supprimer des propriétés du message d’origine pour produire un message sur l’abonnement.

Considérez le scénario suivant dans lequel un abonnement a cinq règles : deux règles avec des actions et les trois autres sans actions. Dans cet exemple, si vous envoyez un message qui correspond aux cinq règles, vous recevez trois messages sur l’abonnement. Cela fait deux messages pour deux règles avec actions et un message pour trois règles sans actions.

Chaque nouvel abonnement à une rubrique est associé à une règle d’abonnement par défaut initiale. Si vous ne spécifiez pas explicitement une condition de filtre pour la règle, le filtre true est appliqué et sélectionne tous les messages dans l’abonnement. La règle par défaut n’est associée à aucune action d’annotation.

Remarque

Cet article s’applique aux scénarios autres que JMS. Pour les scénarios JMS, utilisez des sélecteurs de messages.

Filtres

Service Bus prend en charge trois types de filtre :

  • Filtres SQL
  • Filtres booléens
  • Filtres de corrélation

Les sections suivantes fournissent d’autres détails sur ces filtres.

Filtres SQL

Un SqlFilter contient une expression conditionnelle de type SQL qui est évaluée dans le répartiteur par rapport aux propriétés définies par l’utilisateur et aux propriétés système des messages entrants. Toutes les propriétés système doivent avoir le préfixe sys. dans l’expression conditionnelle. Le sous-ensemble du langage SQL pour les conditions de filtre recherche l’existence des propriétés (EXISTS), des valeurs Nul (IS NULL), d’opérateurs logiques NOT/AND/OR, d’une arithmétique numérique simple et de critères spéciaux de texte simples avec LIKE.

Voici un exemple .NET pour définir un filtre 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;")
}

Filtres booléens

Les filtres TrueFilter et FalseFilter entraînent la sélection de tous les messages entrants (true) ou d’aucun des messages entrants (false) de l’abonnement. Ces deux filtres sont dérivés du filtre SQL.

Voici un exemple .NET pour définir un filtre booléen :

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

Filtres de corrélation

Un filtreCorrelationFilter contient un ensemble de conditions qui sont mises en correspondance par rapport à une ou plusieurs propriétés utilisateur et système d’un message entrant. En général, la mise en correspondance s’effectue par rapport à la propriété CorrelationId, mais l’application peut également choisir de le faire par rapport aux propriétés suivantes :

  • ContentType
  • Label
  • MessageId
  • ReplyTo
  • ReplyToSessionId
  • SessionId
  • To
  • et à des propriétés définies par l’utilisateur.

Il y a correspondance quand la valeur d’une propriété d’un message entrant est identique à la valeur spécifiée dans le filtre de corrélation. Pour les expressions de chaîne, la comparaison respecte la casse. Si vous spécifiez plusieurs propriétés de correspondance, le filtre les combine en une condition AND logique, ce qui implique que toutes les conditions du filtre doivent être remplies pour qu’il y ait correspondance.

Voici un exemple .NET pour définir un filtre de corrélation :

// 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"} ));

Utilisez le constructeur CorrelationRuleFilter qui utilise un Stringargument pour créer un filtre de corrélation avec un ID de corrélation.

Lorsque vous utilisez le constructeur CorrelationRuleFilter par défaut, vous pouvez affecter des propriétés système (ContentType, Label, MessageId, ReplyTo, ReplyToSessionId, SessionId, To) et des propriétés définies par l’utilisateur pour le filtrage. Utilisez la propriété Properties de type IDictionary <string, object> afin de spécifier des propriétés définies par l’utilisateur pour le filtre de corrélation. Les clés de ce dictionnaire sont les propriétés définies par l’utilisateur pour rechercher des messages. Les valeurs associées aux clés sont les valeurs sur lesquelles mettre en corrélation. Voici un exemple.

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

Notes

  • Tous les filtres évaluent les propriétés des messages. Ils ne peuvent pas évaluer le corps des messages.
  • Les règles de filtre complexes nécessitent une plus grande capacité de traitement. En particulier, l’utilisation de règles de filtre SQL diminue le débit global des messages dans les abonnements, rubriques et espaces de noms. Dans la mesure du possible, les applications doivent utiliser des filtres de corrélation plutôt que des filtres de type SQL, car les filtres de corrélation étant beaucoup plus performants, ils ont moins d’impact sur le débit.

Actions

Avec les conditions de filtre SQL, vous pouvez définir une action qui annote le message en ajoutant, en supprimant ou en remplaçant des propriétés et leurs valeurs. L’action utilise une expression de type SQL dont la syntaxe s’appuie librement sur celle de l’instruction SQL UPDATE. L’action est effectuée sur le message après la mise en correspondance du message et avant la sélection du message dans l’abonnement. Les modifications apportées aux propriétés du message s’appliquent uniquement au message copié dans l’abonnement.

Voici un exemple .NET qui crée une règle SQL avec une action pour mettre à jour la quantité lorsque la couleur est Rouge.

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;")
}

Important

Lorsque vous mettez à jour les propriétés système par le biais d’actions de règle, notez qu’elle peut modifier le comportement attendu. Certaines propriétés sont évaluées uniquement lorsqu’un message est reçu dans une file d’attente ou une rubrique. Par conséquent, lorsque vous mettez à jour ces propriétés dans une action de règle et que vous les fournissez dans un abonnement, elles sont ignorées. Bien que, lors du transfert automatique vers une autre file d’attente ou rubrique, ils sont réévalués.

  • ScheduledEnqueueTime : lorsque vous définissez ou mettez à jour cette propriété, elle est ignorée sur l’abonnement.
  • MessageID avec déduplication : aucune déduplication n’est effectuée dans l’abonnement lorsque le MessageID est mis à jour et génère un doublon.
  • ID de session avec partitionnement : dans ce scénario, l’ID de session est la clé de partition pour les entités partitionnés et est utilisé pour décider de la partition à laquelle le message est envoyé. La modification de l’ID de session dans une action de règle signifie que la clé de partition est modifiée une fois qu’un message a atterri dans une partition. Par conséquent, le consommateur peut ne pas recevoir certains de ces messages dans la session. Même si le consommateur reçoit le message, il apparaît comme s’il provient de la mauvaise partition en raison de la clé de partition modifiée.

Modèles d’usage

  • Modèle de diffusion

    Le scénario d’usage le plus simple pour une rubrique est que chaque abonnement récupère une copie de chaque message envoyé dans une rubrique, pour obtenir un modèle de diffusion.

  • Modèle de partitionnement

    Le partitionnement utilise des filtres pour distribuer les messages aux différents abonnements à une rubrique existants de manière prévisible et en mode mutuellement exclusif. Le modèle de partitionnement est utilisé quand la taille des instances d’un système est augmentée pour traiter de nombreux contextes différents dans des compartiments fonctionnellement identiques qui contiennent chacun une partie de l’ensemble des données, par exemple, les informations de profil d’un client. Avec le partitionnement, un éditeur envoie le message dans une rubrique sans avoir besoin de connaître le modèle de partitionnement. Le message est ensuite déplacé vers l’abonnement approprié, à partir duquel il peut ensuite être récupéré par le gestionnaire de messages de la partition.

  • Modèle de routage

    Le routage utilise des filtres pour distribuer les messages aux abonnements à la rubrique de manière prévisible, mais pas nécessairement en mode mutuellement exclusif. Utilisés conjointement avec la fonctionnalité de transfert automatique, les filtres de rubrique permettent de créer des graphiques de routage complexes dans un espace de noms Service Bus pour la distribution de messages dans une région Azure. Avec Azure Functions ou Azure Logic Apps servant de pont entre les espaces de noms Azure Service Bus, vous pouvez créer des topologies globales complexes avec une intégration directe dans les applications métier.

Notes

Le portail Azure prenant désormais en charge la fonctionnalité Service Bus Explorer, des filtres d’abonnement peuvent être créés ou modifiés à partir du portail.

Étapes suivantes

Pour obtenir d’autres exemples, consultez Exemples de filtres Service Bus.