Themenfilter und -aktionen

Abonnenten können definieren, welche Nachrichten von einem Thema empfangen werden sollen. Diese Nachrichten werden in Form von benannten Abonnementregeln angegeben. Jede Regel besteht aus einer Filterbedingung, mit der bestimmte Nachrichten ausgewählt werden, und kann optional eine Aktion enthalten, mit der die ausgewählte Nachricht kommentiert wird.

Alle Regeln ohne Aktionen werden mit einer OR-Bedingung kombiniert und führen zu einer einzelnen Nachricht für das Abonnement. Dies gilt auch, wenn Sie mehrere Abgleichsregeln verwenden.

Jede Regel mit einer Aktion führt zu einer Kopie der Nachricht. Diese Nachricht verfügt über eine Eigenschaft mit dem Namen RuleName. Hierbei ist der Wert der Name der Abgleichsregel. Mit der Aktion können Eigenschaften hinzugefügt oder aktualisiert oder aus der ursprünglichen Nachricht gelöscht werden, um eine Nachricht für das Abonnement zu erzeugen.

Betrachten Sie das folgende Szenario, in dem ein Abonnement fünf Regeln aufweist: zwei Regeln mit Aktionen und die anderen drei ohne Aktionen. Wenn Sie bei diesem Beispiel eine Nachricht senden, die mit allen fünf Regeln übereinstimmt, erhalten Sie unter dem Abonnement drei Nachrichten. Zwei Nachrichten für zwei Regeln mit Aktionen und eine Meldung für drei Regeln ohne Aktionen.

Jedes neu erstellte Themenabonnement weist eine anfängliche Standardabonnementregel auf. Wenn Sie nicht explizit eine Filterbedingung für die Regel angeben, wird der Filter true angewendet, mit dem alle Nachrichten in das Abonnement gewählt werden können. Der Standardregel ist keine Anmerkungsaktion zugeordnet.

Hinweis

Dieser Artikel bezieht sich auf Nicht-JMS-Szenarien. Verwenden Sie für JMS-Szenarien Nachrichtenselektoren.

Filter

Service Bus unterstützt drei Arten von Filtern:

• SQL-Filter
• Boolesche Filter
• Korrelationsfilter

Details zu diesen Filtern finden Sie in den folgenden Abschnitten.

SQL-Filter

Ein SqlFilter enthält einen SQL-ähnlichen bedingten Ausdruck, der im Broker gegen die benutzerdefinierten Eigenschaften und Systemeigenschaften des eingehenden Nachrichten ausgewertet wird. Allen Systemeigenschaften muss das Präfix sys. im bedingten Ausdruck vorangestellt werden. Die SQL-Sprachteilmenge für Filterbedingungen testet auf das Vorhandensein von Eigenschaften (EXISTS), Nullwerten (IS NULL), logischen NOT/AND/OR, relationalen Operatoren, einfacher numerischer Arithmetik und einfachem Textmusterabgleich mit LIKE.

Hier ist ein .NET-Beispiel zum Definieren eines SQL-Filters:

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

Boolesche Filter

Die TrueFilter und FalseFilter sorgen dafür, dass entweder alle eingehenden Nachrichten (WAHR) oder keine der eingehenden Nachrichten (FALSCH) für das Abonnement ausgewählt werden. Diese beiden Filter werden vom SQL-Filter abgeleitet.

Hier ist ein .NET-Beispiel zum Definieren eines booleschen Filters:

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

Korrelationsfilter

Ein CorrelationFilter enthält eine Reihe von Bedingungen, die gegen eine oder mehrere Benutzer- und Systemeigenschaften einer eingehenden Nachricht abgeglichen werden. Er wird häufig zum Vergleichen der Eigenschaft CorrelationId verwendet. Die Anwendung kann aber auch die folgenden Eigenschaften vergleichen:

• ContentType
• Label
• MessageId
• ReplyTo
• ReplyToSessionId
• SessionId
• To
• beliebige benutzerdefinierte Eigenschaften.

Eine Übereinstimmung liegt vor, wenn der Wert einer Eigenschaft einer eingehenden Nachricht gleich dem im Korrelationsfilter angegebenen Wert ist. Für Zeichenfolgenausdrücke wird beim Vergleich die Groß-/Kleinschreibung beachtet. Wenn Sie mehrere Übereinstimmungseigenschaften angeben, kombiniert der Filter sie in einer logischen AND-Bedingung, d. h., der Filter stimmt dann überein, wenn alle Bedingungen erfüllt sind.

Hier ist ein .NET-Beispiel zum Definieren eines Korrelationsfilters:

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

Verwenden Sie den CorrelationRuleFilter-Konstruktor, der ein String-Argument akzeptiert, um einen Korrelationsfilter mit einer Korrelations-ID zu erstellen.

Wenn Sie den CorrelationRuleFilter-Standardkonstruktor verwenden, können Sie Systemeigenschaften (ContentType, Label, MessageId, ReplyTo, ReplyToSessionId, SessionId, To) und benutzerdefinierte Eigenschaften zum Filtern zuweisen. Verwenden Sie die Eigenschaft Properties vom Typ IDictionary <string, object>, um benutzerdefinierte Eigenschaften für den Korrelationsfilter anzugeben. Schlüssel für dieses Wörterbuch sind die benutzerdefinierten Eigenschaften zum Nachschlagen von Nachrichten. Die mit den Schlüsseln verbundenen Werte sind die Werte, die korreliert werden müssen. Hier sehen Sie ein Beispiel.

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

Hinweis

• Alle Filter werten Nachrichteneigenschaften aus. Der Nachrichtentext kann von Filtern nicht ausgewertet werden.
• Komplexe Filterregeln erfordern Verarbeitungskapazitäten. Insbesondere bewirkt die Verwendung von SQL-Filterregeln einen geringeren Gesamtnachrichtendurchsatz auf Ebene des Abonnements, des Themas und des Namespace. Nach Möglichkeit sollten Anwendungen eher Korrelationsfilter als SQL-ähnliche Filter verwenden, weil sie erheblich effizienter verarbeitet werden und geringere Auswirkungen auf den Durchsatz haben.

Aktionen

Mit SQL-Filterbedingungen können Sie eine Aktion definieren, die die Nachricht durch Hinzufügen, Entfernen oder Ersetzen von Eigenschaften und deren Werten kommentieren kann. Die Aktion verwendet einen SQL-ähnlichen Ausdruck, der sich lose an die Syntax der SQL UPDATE-Anweisung anlehnt. Die Aktion wird für die Nachricht angewendet, nachdem eine Übereinstimmung dafür gefunden wurde und bevor die Nachricht für das Abonnement ausgewählt wird. Die Änderungen an den Nachrichteneigenschaften sind innerhalb der in das Abonnement kopierten Nachricht privat.

Hier ist ein .NET-Beispiel, das eine SQL-Regel mit einer Aktion zum Aktualisieren der Quantität erstellt, wenn die Farbe Rot ist.

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

Wichtig

Wenn Sie Systemeigenschaften über Regelaktionen aktualisieren, beachten Sie, dass dies das erwartete Verhalten ändern kann. Einige Eigenschaften werden nur ausgewertet, wenn eine Nachricht in einer Warteschlange oder einem Thema eingeht. Wenn Sie diese Eigenschaften daher in einer Regelaktion aktualisieren und sie dann in einem Abonnement bereitstellen, werden sie ignoriert. Bei der automatischen Weiterleitung an eine andere Warteschlange oder ein anderes Thema werden sie jedoch neu bewertet.

• ScheduledEnqueueTime: Wenn Sie diese Eigenschaft festlegen oder aktualisieren, wird sie im Abonnement ignoriert.
• MessageID mit Deduplizierung: Es wird keine Deduplizierung im Abonnement durchgeführt, wenn die MessageID aktualisiert wird und zu einem Duplikat führt.
• SessionID mit Partitionierung:In diesem Szenario ist die Sitzungs-ID der Partitionsschlüssel für partitionierte Entitäten und wird verwendet, um zu entscheiden, an welche Partition die Nachricht gesendet wird. Wenn Sie die sessionID in einer Regelaktion ändern, bedeutet dies, dass der Partitionsschlüssel geändert wird, nachdem eine Nachricht in einer Partition gelandet ist. Daher kann es sein, dass der Verbraucher einige dieser Nachrichten in der Sitzung nicht erhält. Selbst wenn der Verbraucher die Nachricht erhält, scheint es, als käme sie aufgrund des geänderten Partitionsschlüssels von der falschen Partition.

Verwendungsmuster

• Übertragungsmuster

  Das einfachste Verwendungsszenario für ein Thema ist, dass jedes Abonnement eine Kopie aller an ein Thema gesendeten Nachrichten erhält, sodass ein Broadcastmuster ermöglicht wird.

• Partitionierungsmuster

  Die Partitionierung verwendet Filter, um Nachrichten auf mehrere vorhandene Themenabonnements in einer vorhersehbaren und sich gegenseitig ausschließenden Weise zu verteilen. Das Partitionierungsmuster wird verwendet, wenn ein System viele unterschiedliche Kontexte in funktionell identischen Abteilungen bearbeitet, wobei in jeder Abteilung eine Teilmenge der gesamten Daten vorhanden ist, z.B. Kundenprofilinformationen. Mit Partitionierung übermittelt ein Herausgeber die Nachricht an ein Thema, ohne dass Kenntnisse des Partitionierungsmodells erforderlich sind. Die Nachricht wird dann in das richtige Abonnement verschoben, aus dem es anschließend vom Meldungshandler der Partition abgerufen werden kann.

• Routingmuster

  Das Routing verwendet Filter, um Nachrichten auf vorhersehbare Weise auf Themenabonnements zu verteilen, aber nicht unbedingt exklusiv. In Verbindung mit dem Feature für die automatische Weiterleitung können mit Themenfiltern komplexer Weiterleitungsgraphen innerhalb eines Service Bus-Namespace erstellt werden, über die die Nachrichtenverteilung in einer Azure-Region erfolgt. Mit Azure Functions oder Azure Logic Apps als Brücke zwischen Azure Service Bus-Namespaces können Sie komplexe globale Topologien mit direkter Integration in Branchenanwendungen erstellen.

Hinweis

Da das Azure-Portal jetzt die Service Bus Explorer-Funktionen unterstützt, können Abonnementfilter über das Portal erstellt oder bearbeitet werden.

Nächste Schritte

Weiter Beispiele finden Sie unter Service Bus-Filterbeispiele.