Dela via

Ämnesfilter och åtgärder

  • Artikel

Prenumeranter kan definiera vilka meddelanden som de vill ta emot från ett ämne. Dessa meddelanden anges i form av en eller flera namngivna prenumerationsregler. Varje regel består av ett filtervillkor som väljer specifika meddelanden och som kan innehålla en åtgärd som kommenterar det valda meddelandet.

Alla regler utan åtgärder kombineras med ett OR villkor och resulterar i ett enda meddelande i prenumerationen även om du har flera matchande regler.

Varje regel med en åtgärd skapar en kopia av meddelandet. Det här meddelandet har en egenskap som heter RuleName där värdet är namnet på matchningsregeln. Åtgärden kan lägga till eller uppdatera egenskaper eller ta bort egenskaper från det ursprungliga meddelandet för att skapa ett meddelande i prenumerationen.

Tänk dig följande scenario där en prenumeration har fem regler: två regler med åtgärder och de andra tre utan åtgärder. I det här exemplet får du tre meddelanden i prenumerationen om du skickar ett meddelande som matchar alla fem reglerna. Det är två meddelanden för två regler med åtgärder och ett meddelande för tre regler utan åtgärder.

Varje nyligen skapad ämnesprenumeration har en första standardprenumerationsregel. Om du inte uttryckligen anger ett filtervillkor för regeln är det tillämpade filtret det sanna filtret som gör att alla meddelanden kan väljas i prenumerationen. Standardregeln har ingen associerad anteckningsåtgärd.

Kommentar

Den här artikeln gäller för scenarier som inte är JMS. I JMS-scenarier använder du meddelandeväljare.

Filter

Service Bus har stöd för tre typer av filter:

  • SQL-filter
  • Booleska filter
  • Korrelationsfilter

Följande avsnitt innehåller information om dessa filter.

SQL-filter

Ett SqlFilter innehåller ett SQL-liknande villkorsuttryck som utvärderas i asynkron meddelandekö mot de ankommande meddelandenas användardefinierade egenskaper och systemegenskaper. Alla systemegenskaper måste föregås av sys. i villkorsuttrycket. Underuppsättningen SQL-language för filtervillkor testar förekomsten av egenskaper (EXISTS), null-värden (IS NULL), logiskaAND//NOTOR , relationsoperatorer, enkel numerisk aritmetik och enkel textmönstermatchning med .LIKE

Här är ett .NET-exempel för att definiera ett SQL-filter:

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

Booleska filter

TrueFilter och FalseFilter gör antingen att alla ankommande meddelanden (sant) eller inget av de ankommande meddelandena (falskt) väljs för prenumerationen. Dessa två filter härleds från SQL-filtret.

Här är ett .NET-exempel för att definiera ett booleskt filter:

// 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

Ett CorrelationFilter innehåller en uppsättning villkor som matchas mot en eller flera av ett ankommande meddelandes användar- och systemegenskaper. En vanlig användning är att matcha mot egenskapen CorrelationId , men programmet kan också välja att matcha mot följande egenskaper:

  • ContentType
  • Label
  • MessageId
  • ReplyTo
  • ReplyToSessionId
  • SessionId
  • To
  • alla användardefinierade egenskaper.

Det finns en matchning när ett ankommande meddelandes värde för en egenskap är lika med det värde som anges i korrelationsfiltret. För stränguttryck är jämförelsen skiftlägeskänslig. Om du anger flera matchningsegenskaper kombinerar filtret dem som ett logiskt AND-villkor, vilket innebär att alla villkor måste matchas för att filtret ska matcha.

Här är ett .NET-exempel för att definiera ett korrelationsfilter:

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

Använd konstruktorn CorrelationRuleFilter som tar ett String argument för att skapa ett korrelationsfilter med ett korrelations-ID.

När du använder CorrelationRuleFilter standardkonstruktorn kan du tilldela systemegenskaper (ContentType, , Label, ReplyToMessageId, ReplyToSessionId, SessionId, ), Tooch användardefinierade egenskaper för filtrering. Om du vill ange användardefinierade egenskaper för korrelationsfilter använder du egenskapen Properties av typen IDictionary <string, object>. Nycklar för den här ordlistan är de användardefinierade egenskaperna för att söka efter meddelanden. Värden som är associerade med nycklar är de värden som ska korreleras på. Här är ett exempel.

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

Kommentar

  • Alla filter utvärderar meddelandeegenskaper. Filter kan inte utvärdera meddelandetexten.
  • Komplexa filterregler kräver bearbetningskapacitet. I synnerhet orsakar användningen av SQL-filterregler lägre övergripande meddelandedataflöde på prenumerations-, ämnes- och namnområdesnivå. När det är möjligt bör program välja korrelationsfilter framför SQL-liknande filter eftersom de är mycket effektivare vid bearbetning och har mindre inverkan på dataflödet.

Åtgärder

Med SQL-filtervillkor kan du definiera en åtgärd som kan kommentera meddelandet genom att lägga till, ta bort eller ersätta egenskaper och deras värden. Åtgärden använder ett SQL-liknande uttryck som löst lutar sig mot instruktionssyntaxenSQL UPDATE. Åtgärden utförs på meddelandet efter att det har matchats och innan meddelandet har valts i prenumerationen. Ändringarna av meddelandeegenskaperna är privata för meddelandet som kopieras till prenumerationen.

Här är ett .NET-exempel som skapar en SQL-regel med en åtgärd för att uppdatera kvantiteten när färgen är Röd.

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

Viktigt!

När du uppdaterar systemegenskaper via regelåtgärder bör du tänka på att det kan ändra det förväntade beteendet. Vissa egenskaper utvärderas bara när ett meddelande tas emot i en kö eller ett ämne. När du uppdaterar dessa egenskaper i en regelåtgärd och sedan levererar dem i en prenumeration ignoreras de därför. Men när du vidarebefordrar automatiskt till en annan kö eller ett annat ämne utvärderas de på nytt.

  • ScheduledEnqueueTime: När du anger eller uppdaterar den här egenskapen ignoreras den i prenumerationen.
  • MessageID med deduplicering: Ingen deduplicering utförs i prenumerationen när MessageID uppdateras och resulterar i en dubblett.
  • SessionID med partitionering: I det här scenariot är sessions-ID:t partitionsnyckeln för partitionerade entiteter och används för att bestämma vilken partition meddelandet skickas till. Om du ändrar sessionID i en regelåtgärd ändras partitionsnyckeln när ett meddelande har landat i en partition. Det innebär att konsumenten kanske inte får några av dessa meddelanden i sessionen. Även om konsumenten får meddelandet verkar det som om de kommer från fel partition på grund av den ändrade partitionsnyckeln.

Användningsmönster

  • Sändningsmönster

    Det enklaste användningsscenariot för ett ämne är att varje prenumeration får en kopia av varje meddelande som skickas till ett ämne, vilket möjliggör ett sändningsmönster.

  • Partitioneringsmönster

    Partitionering använder filter för att distribuera meddelanden över flera befintliga ämnesprenumerationer på ett förutsägbart och ömsesidigt uteslutande sätt. Partitioneringsmönstret används när ett system skalas ut för att hantera många olika kontexter i funktionellt identiska fack som var och en innehåller en delmängd av de övergripande data. till exempel kundprofilinformation. Med partitionering skickar en utgivare meddelandet till ett ämne utan att det krävs någon kunskap om partitioneringsmodellen. Meddelandet flyttas sedan till rätt prenumeration som det sedan kan hämtas från av partitionens meddelandehanterare.

  • Routningsmönster

    Routning använder filter för att distribuera meddelanden mellan ämnesprenumerationer på ett förutsägbart sätt, men inte nödvändigtvis exklusivt. Tillsammans med funktionen för automatisk vidarebefordring kan ämnesfilter användas för att skapa komplexa routningsdiagram i ett Service Bus-namnområde för meddelandedistribution i en Azure-region. Med Azure Functions eller Azure Logic Apps som en brygga mellan Azure Service Bus-namnområden kan du skapa komplexa globala topologier med direkt integrering i verksamhetsspecifika program.

Kommentar

Eftersom Azure Portal nu stöder Service Bus Explorer-funktioner kan prenumerationsfilter skapas eller redigeras från portalen.

Nästa steg

Fler exempel finns i Service Bus-filterexempel.