Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Der Azure Web PubSub-Parameter filter definiert Ein- oder Ausschlusskriterien zum Senden von Nachrichten an Verbindungen. Dieser Parameter wird in den Vorgängen "An alle senden", "An Gruppe senden" und "An Benutzer senden" verwendet.
Dieser Artikel enthält die folgenden Ressourcen:
- Eine Beschreibung der OData-Syntax des
filterParameters mit Beispielen. - Eine Beschreibung der vollständigen Erweiterten Backus-Naur-Grammatik (EBNF).
Syntax
Ein Filter in der OData-Sprache ist ein boolescher Ausdruck. Es kann sich um einen von mehreren Ausdruckstypen handeln, wie in der EBNF-Beschreibung dargestellt.
Sie können ein interaktives Syntaxdiagramm verwenden, um die Syntaxgrammatikregeln zu untersuchen.
Der Abschnitt "Formale Grammatik " dieses Artikels enthält den vollständigen EBNF.
Bezeichner
Mithilfe der Filtersyntax können Sie das Senden von Nachrichten an Verbindungen steuern, die den Bezeichnerkriterien entsprechen. Azure Web PubSub unterstützt die folgenden Bezeichner:
| Bezeichner | Beschreibung | Hinweis | Beispiel |
|---|---|---|---|
userId |
Die Benutzer-ID der Verbindung | Diese Klasse berücksichtigt keine Groß-/Kleinschreibung. Sie kann in Zeichenfolgenvorgängen verwendet werden. | userId eq 'user1' |
connectionId |
Die Verbindungs-ID der Verbindung | Diese Klasse berücksichtigt keine Groß-/Kleinschreibung. Sie kann in Zeichenfolgenvorgängen verwendet werden. | connectionId ne '123' |
groups |
Die Sammlung von Gruppen, in denen sich die Verbindung derzeit befindet | Diese Klasse berücksichtigt keine Groß-/Kleinschreibung. Sie kann in Sammlungsvorgängen verwendet werden. | 'group1' in groups |
Bezeichner verweisen auf den Eigenschaftswert einer Verbindung. Azure Web PubSub unterstützt drei Bezeichner, die dem Eigenschaftennamen des Verbindungsmodells entsprechen. Der Dienst unterstützt die und connectionId bezeichner userId in Zeichenfolgenvorgängen und unterstützt den groups Bezeichner in Sammlungsvorgängen.
Um z. B. Verbindungen mit einer Benutzer-ID user1zu filtern, geben Sie den Filter als userId eq 'user1'. Lesen Sie die folgenden Abschnitte, um weitere Beispiele für die Verwendung des Filters zu finden.
Boolesche Ausdrücke
Der Ausdruck für einen Filter ist ein boolescher Ausdruck. Azure Web PubSub sendet Nachrichten an Verbindungen mit Filterausdrücken, die ausgewertet werden true.
Die Typen von booleschen Ausdrücken umfassen Folgendes:
- Logische Ausdrücke, die andere boolesche Ausdrücke mithilfe der Operatoren
and,orundnot. - Vergleichsausdrücke, die Felder oder Bereichsvariablen mit konstanten Werten vergleichen, indem die Operatoren
eq, ,ne,gt,lt, undgele. - Die booleschen Literale
trueundfalse. Diese Konstanten können manchmal hilfreich sein, wenn Sie Filter programmgesteuert generieren. Andernfalls neigen sie nicht dazu, in der Praxis zu verwenden. - Boolesche Ausdrücke in Klammern. Die Verwendung von Klammern hilft ihnen, die Reihenfolge der Vorgänge in einem Filter explizit zu bestimmen. Im Abschnitt "Operatorrangfolge" dieses Artikels wird die Standardrangfolge der OData-Operatoren beschrieben.
Unterstützte Vorgänge
Die Filtersyntax unterstützt die folgenden Vorgänge:
| Operator | Beschreibung | Beispiel |
|---|---|---|
| Logische Operatoren | ||
and |
Logisch und | length(userId) le 10 and length(userId) gt 3 |
or |
Logisch oder | length(userId) gt 10 or length(userId) le 3 |
not |
Logische Negation | not endswith(userId, 'milk') |
| Vergleichsoperatoren | ||
eq |
Gleich | userId eq 'user1', userId eq null |
ne |
Ungleich | userId ne 'user1', userId ne null |
gt |
Größer als | length(userId) gt 10 |
ge |
Größer als oder gleich | length(userId) ge 10 |
lt |
Kleiner als | length(userId) lt 3 |
le |
Kleiner oder gleich | 'group1' in groups, user in ('user1','user2') |
| In-Operator | ||
in |
Der rechte Operand muss entweder eine durch Trennzeichen getrennte Liste von Grundtypen sein, die in Klammern eingeschlossen sind, oder ein einzelner Ausdruck, der in eine Auflistung aufgelöst wird. | userId ne 'user1' |
| Gruppierungsoperator | ||
() |
Steuert die Auswertungsreihenfolge eines Ausdrucks | userId eq 'user1' or (not (startswith(userId,'user2')) |
| Zeichenfolgenfunktionen | ||
string tolower(string p) |
Ruft den Kleinbuchstabe für den Zeichenfolgenwert ab. | tolower(userId) eq 'user1' kann Verbindungen für Benutzer USER1 abgleichen |
string toupper(string p) |
Ruft den Großbuchstaben für den Zeichenfolgenwert ab. | toupper(userId) eq 'USER1' kann Verbindungen für Benutzer user1 abgleichen |
string trim(string p) |
Schneidet den Zeichenfolgenwert ab | trim(userId) eq 'user1' kann Verbindungen für Benutzer user1 abgleichen |
string substring(string p, int startIndex),string substring(string p, int startIndex, int length) |
Teilzeichenfolge der Zeichenfolge | substring(userId,5,2) eq 'ab' kann Verbindungen für Benutzer user-ab-de abgleichen |
bool endswith(string p0, string p1) |
Überprüft, ob p0 enden mit p1 |
endswith(userId,'de') kann Verbindungen für Benutzer user-ab-de abgleichen |
bool startswith(string p0, string p1) |
Überprüft, ob p0 beginnt mit p1 |
startswith(userId,'user') kann Verbindungen für Benutzer user-ab-de abgleichen |
int indexof(string p0, string p1) |
Ruft den Index von p1 in p0, oder gibt zurück -1 , wenn p0 nicht enthalten p1 |
indexof(userId,'-ab-') ge 0 kann Verbindungen für Benutzer user-ab-de abgleichen |
int length(string p) |
Ruft die Länge der Eingabezeichenfolge ab. | length(userId) gt 1 kann Verbindungen für Benutzer user-ab-de abgleichen |
| Sammlungsfunktion | ||
int length(collection p) |
Ruft die Länge der Auflistung ab. | length(groups) gt 1 Kann Verbindungen in zwei Gruppen abgleichen |
Rangfolge der Operatoren
Wenn Sie einen Filterausdruck ohne Klammern um seine Unterausdrücke schreiben, wertet der Azure Web PubSub-Dienst ihn gemäß einer Reihe von Operatorrangfolgeregeln aus. Diese Regeln basieren darauf, welche Operatoren verwendet werden, um Unterausdrücke zu kombinieren. In der folgenden Tabelle sind die Gruppen von Operatoren von der höchsten bis zur niedrigsten Rangfolge aufgelistet:
| Group | Operatoren |
|---|---|
| Logische Operatoren | not |
| Vergleichsoperatoren | eq, , negt, lt, , gele |
| Logische Operatoren | and |
| Logische Operatoren | or |
Ein Operator, der in der vorherigen Tabelle höher ist, wird "enger binden" an seine Operanden als andere Operatoren. Hat z. B and . eine höhere Rangfolge als or, und Vergleichsoperatoren haben eine höhere Rangfolge als eine dieser Operatoren. Die folgenden beiden Ausdrücke sind also gleichwertig:
length(userId) gt 0 and length(userId) lt 3 or length(userId) gt 7 and length(userId) lt 10
((length(userId) gt 0) and (length(userId) lt 3)) or ((length(userId) gt 7) and (length(userId) lt 10))
Der not Operator hat die höchste Priorität aller. Es ist sogar höher als die Vergleichsoperatoren. Wenn Sie einen Filter wie folgt schreiben:
not length(userId) gt 5
Wird die folgende Fehlermeldung angezeigt:
Invalid syntax for 'not length(userId)': Type 'null', expect 'bool'. (Parameter 'filter')
Dieser Fehler tritt auf, da der Operator nur dem length(userId) Ausdruck und nicht dem gesamten Vergleichsausdruck zugeordnet ist. Der length(userId) Ausdruck ist vom Typ null "when userId is null" . Die Lösung besteht darin, den Operanden von not in Klammern zu setzen:
not (length(userId) gt 5)
Einschränkungen der Filtergröße
Es gibt Grenzwerte für die Größe und Komplexität von Filterausdrücken, die Sie an den Azure Web PubSub-Dienst senden können. Die Grenzwerte basieren ungefähr auf der Anzahl von Klauseln in Ihrem Filterausdruck. Eine gute Richtlinie ist, dass Sie, wenn Sie mehr als 100 Klauseln haben, gefahren, den Grenzwert zu überschreiten. Um das Überschreiten des Grenzwerts zu vermeiden, entwerfen Sie Ihre Anwendung so, dass keine Filter von ungebundener Größe generiert werden.
Beispiele
An mehrere Gruppen senden:
filter='group1' in groups or 'group2' in groups or 'group3' in groups
An mehrere Benutzer in einer bestimmten Gruppe senden:
filter=userId in ('user1', 'user2', 'user3') and 'group1' in groups
An einen Benutzer senden, aber keine bestimmte Verbindungs-ID:
filter=userId eq 'user1' and connectionId ne '123'
An einen Benutzer senden, der sich nicht in einer bestimmten Gruppe befindet:
filter=userId eq 'user1' and (not ('group1' in groups))
Escape ' , wenn die Benutzer-ID folgendes enthält ':
filter=userId eq 'user''1'
Formale Grammatik
Die folgende Erweiterte Backus-Naur-Formulargrammatik kann die Teilmenge der OData-Sprache beschreiben, die der Azure Web PubSub-Dienst unterstützt. Diese Grammatik listet regeln "top down" auf, indem sie mit den komplexesten Ausdrücken beginnen und diese dann in primitivere Ausdrücke aufteilen. Oben sehen Sie die Grammatikregel, die $filter dem spezifischen filter Parameter der REST-APIs des Azure Web PubSub-Diensts Send* entspricht.
/* Top-level rule */
filter_expression ::= boolean_expression
/* Identifiers */
string_identifier ::= 'connectionId' | 'userId'
collection_identifier ::= 'groups'
/* Rules for $filter */
boolean_expression ::= logical_expression
| comparison_expression
| in_expression
| boolean_literal
| boolean_function_call
| '(' boolean_expression ')'
logical_expression ::= boolean_expression ('and' | 'or') boolean_expression
| 'not' boolean_expression
comparison_expression ::= primary_expression comparison_operator primary_expression
in_expression ::= primary_expression 'in' ( '(' primary_expression (',' primary_expression)* ')' ) | collection_expression
collection_expression ::= collection_variable
| '(' collection_expression ')'
primary_expression ::= primary_variable
| function_call
| constant
| '(' primary_expression ')'
string_expression ::= string_literal
| 'null'
| string_identifier
| string_function_call
| '(' string_expression ')'
primary_variable ::= string_identifier
collection_variable ::= collection_identifier
comparison_operator ::= 'gt' | 'lt' | 'ge' | 'le' | 'eq' | 'ne'
/* Rules for constants and literals */
constant ::= string_literal
| integer_literal
| boolean_literal
| 'null'
boolean_literal ::= 'true' | 'false'
string_literal ::= "'"([^'] | "''")*"'"
digit ::= [0-9]
sign ::= '+' | '-'
integer_literal ::= sign? digit+
boolean_literal ::= 'true' | 'false'
/* Rules for functions */
function_call ::= indexof_function_call
| length_function_call
| string_function_call
| boolean_function_call
boolean_function_call ::= endsWith_function_call
| startsWith_function_call
| contains_function_call
string_function_call ::= tolower_function_call
| toupper_function_call
| trim_function_call
| substring_function_call
| concat_function_call
/* Rules for string functions */
indexof_function_call ::= "indexof" '(' string_expression ',' string_expression ')'
concat_function_call ::= "concat" '(' string_expression ',' string_expression ')'
contains_function_call ::= "contains" '(' string_expression ',' string_expression ')'
endsWith_function_call ::= "endswith" '(' string_expression ',' string_expression ')'
startsWith_function_call ::= "startswith" '(' string_expression ',' string_expression ')'
substring_function_call ::= "substring" '(' string_expression ',' integer_literal (',' integer_literal)? ')'
tolower_function_call ::= "tolower" '(' string_expression ')'
toupper_function_call ::= "toupper" '(' string_expression ')'
trim_function_call ::= "trim" '(' string_expression ')'
/* Rules for string and collection functions */
length_function_call ::= "length" '(' string_expression | collection_expression ')'
Nächste Schritte
Erstellen Sie mithilfe dieser Ressourcen Ihre eigene Anwendung: