Filtri e azioni per gli argomenti

I sottoscrittori possono definire i messaggi che vogliono ricevere da un argomento. Per specificare tali messaggi, viene usata una o più regole di sottoscrizione denominate. Ogni regola è costituita da una condizione di filtro che seleziona determinati messaggi e, facoltativamente, contiene un'azione che annota il messaggio selezionato.

Tutte le regole senza azioni vengono combinate usando una OR condizione e generano un singolo messaggio nella sottoscrizione anche se sono presenti più regole corrispondenti.

Ogni regola con un'azione produce una copia del messaggio. Questo messaggio avrà una proprietà denominata RuleName dove il valore è il nome della regola corrispondente. L'azione può aggiungere o aggiornare proprietà o eliminare proprietà dal messaggio originale per generare un messaggio nella sottoscrizione.

Si consideri lo scenario seguente in cui una sottoscrizione ha cinque regole: due regole con azioni e le altre tre senza azioni. In questo esempio, se si invia un messaggio che corrisponde a tutte e cinque le regole, si ricevono tre messaggi nella sottoscrizione. Si tratta di due messaggi per due regole con azioni e un messaggio per tre regole senza azioni.

Ogni nuova sottoscrizione di argomento creata ha una regola di sottoscrizione predefinita iniziale. Se non si specifica in modo esplicito una condizione di filtro per la regola, viene applicato il filtro true, che consente la selezione di tutti i messaggi nella sottoscrizione. Alla regola predefinita non è associata alcuna azione di annotazione.

Nota

Questo articolo si applica agli scenari non JMS. Per gli scenari JMS, usare selettori di messaggi.

Filtri

bus di servizio supporta tre tipi di filtri:

• Filtri SQL
• Filtri booleani
• Filtri di correlazione

Le sezioni seguenti forniscono informazioni dettagliate su questi filtri.

Filtri SQL

Un oggetto SqlFilter contiene un'espressione condizionale simile a SQL valutata nel broker rispetto alle proprietà definite dall'utente e alle proprietà di sistema dei messaggi in arrivo. Nell'espressione condizionale, tutte le proprietà di sistema devono essere precedute dal prefisso sys.. Sottoinsieme di linguaggio SQL per i test delle condizioni di filtro per l'esistenza di proprietà (EXISTS), valori Null (IS NULL), operatori relazionali logiciAND//NOTOR, aritmetici semplici e criteri di testo semplici corrispondenti a .LIKE

Di seguito è riportato un esempio .NET per la definizione di un 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;")
}

Filtri booleani

TrueFilter e FalseFilter determinano la selezione di tutti i messaggi in arrivo (true) o nessuno dei messaggi in arrivo (false) per la sottoscrizione. Questi due filtri derivano dal filtro SQL.

Ecco un esempio .NET per la definizione di un 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()));	

Filtri di correlazione

CorrelationFilter contiene un set di condizioni corrispondenti a una o più proprietà utente e di sistema di un messaggio in arrivo. Un uso comune consiste nel trovare una corrispondenza con la proprietà CorrelationId , ma l'applicazione può anche scegliere di corrispondere alle proprietà seguenti:

• ContentType
• Label
• MessageId
• ReplyTo
• ReplyToSessionId
• SessionId
• To
• qualsiasi proprietà definita dall'utente.

Esiste una corrispondenza quando il valore di una proprietà di un messaggio in arrivo è uguale al valore specificato nel filtro di correlazione. Per le espressioni stringa, nel confronto viene fatta distinzione tra maiuscole e minuscole. Se si specificano più proprietà di corrispondenza, il filtro le combina come condizione AND logica, vale a dire che il filtro corrisponda, tutte le condizioni devono corrispondere.

Ecco un esempio .NET per la definizione di un filtro di correlazione:

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

Usare il CorrelationRuleFilter costruttore che accetta un String argomento per creare un filtro di correlazione con un ID di correlazione.

Quando si usa il costruttore predefinito, è possibile assegnare proprietà di sistema (ContentType, , MessageIdToReplyToSessionIdLabelReplyToSessionId) e proprietà definite dall'utente per il filtro.CorrelationRuleFilter Per specificare le proprietà definite dall'utente per il filtro di correlazione, utilizzare la proprietà Properties di tipo IDictionary <string, object>. Le chiavi per questo dizionario sono le proprietà definite dall'utente da cercare nei messaggi. I valori associati alle chiavi sono i valori su cui correlare. Ecco un esempio.

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

Nota

• Tutti i filtri valutano le proprietà del messaggio. I filtri non possono valutare il corpo del messaggio.
• Regole di filtro complesse richiedono capacità di elaborazione. In particolare, l'uso di regole di filtro SQL causa una minore velocità effettiva complessiva dei messaggi a livello di sottoscrizione, argomento e spazio dei nomi. Quando possibile, le applicazioni devono scegliere filtri di correlazione su filtri simili a SQL perché sono molto più efficienti nell'elaborazione e hanno un impatto minore sulla velocità effettiva.

Azioni

Con le condizioni di filtro SQL, è possibile definire un'azione per annotare il messaggio aggiungendo, rimuovendo o sostituendo le proprietà e i relativi valori. L'azione usa un'espressione simile a SQL che si appoggia in modo libero sulla sintassi dell'istruzioneSQL UPDATE. L'azione viene eseguita sul messaggio dopo che è stata trovata una corrispondenza e prima che il messaggio venga selezionato nella sottoscrizione. Le modifiche alle proprietà del messaggio sono private e limitate al messaggio copiato nella sottoscrizione.

Ecco un esempio .NET che crea una regola SQL con un'azione per aggiornare la quantità quando il colore è Rosso.

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 si aggiornano le proprietà di sistema tramite azioni regola, si noti che potrebbe modificare il comportamento previsto. Alcune proprietà vengono valutate solo quando un messaggio viene ricevuto in una coda o in un argomento. Pertanto, quando si aggiornano queste proprietà in un'azione della regola e quindi le si recapitano in una sottoscrizione, vengono ignorate. Anche se, durante l'inoltro automatico a un'altra coda o argomento, vengono rivalutati.

• ScheduledEnqueueTime: quando si imposta o si aggiorna questa proprietà, questa proprietà viene ignorata nella sottoscrizione.
• MessageID con deduplicazione: non viene eseguita alcuna deduplicazione nella sottoscrizione quando MessageID viene aggiornato e restituisce un duplicato.
• SessionID con partizionamento: in questo scenario, l'ID sessione è la chiave di partizione per le entità partizionate e viene usato per decidere la partizione a cui viene inviato il messaggio. La modifica dell'ID sessione in un'azione regola indica che la chiave di partizione viene modificata dopo che un messaggio è stato inserito in una partizione. Di conseguenza, il consumer potrebbe non ricevere alcuni di questi messaggi nella sessione. Anche se il consumer riceve il messaggio, viene visualizzato come se provenissero dalla partizione errata a causa della chiave di partizione modificata.

Modelli di utilizzo

• Modello di trasmissione

  Nello scenario di utilizzo più semplice per un argomento, ogni sottoscrizione riceve una copia di ogni messaggio inviato all'argomento e si ha così un modello di trasmissione.

• Modello di partizionamento

  Il partizionamento usa filtri per distribuire i messaggi tra diverse sottoscrizioni di argomenti esistenti in modo prevedibile ed escludono a vicenda. Il modello di partizionamento viene usato quando si aumenta il numero di istanze di un sistema per gestire più contesti diversi in raggruppamenti identici a livello funzionale, ognuno contenente un subset dei dati complessivi, ad esempio le informazioni sui profili dei clienti. Con il partizionamento, un'entità di pubblicazione invia il messaggio a un argomento senza richiedere la conoscenza del modello di partizionamento. Il messaggio viene quindi spostato nella sottoscrizione corretta, da cui potrà quindi essere recuperato dal gestore di messaggi della partizione.

• Modello di routing

  Il routing usa filtri per distribuire i messaggi tra sottoscrizioni di argomenti in modo prevedibile, ma non necessariamente esclusivo. In combinazione con la funzionalità di inoltro automatico, i filtri per gli argomenti consentono di creare grafici di routing complessi all'interno di uno spazio dei nomi del bus di servizio per la distribuzione dei messaggi in un'area di Azure. Usando Funzioni di Azure o App per la logica di Azure come collegamento tra gli spazi dei nomi del bus di servizio di Azure, è possibile creare topologie globali complesse con integrazione diretta nelle applicazioni line-of-business.

Nota

Poiché il portale di Azure supporta ora la funzionalità bus di servizio Explorer, è possibile creare o modificare i filtri delle sottoscrizioni dal portale.

Passaggi successivi

Per altri esempi, vedere bus di servizio esempi di filtro.