Azure Web PubSub filter パラメーターは、接続にメッセージを送信するための包含条件または除外条件を定義します。 このパラメーターは、 Send to all、 Send to group、および Send to user 操作で使用されます。
この記事には以下のリソースが含まれています。
filterパラメーターの OData 構文の説明と例。- 拡張 Backus-Naur Form (EBNF) 文法の完全な説明。
構文
OData 言語のフィルターはブール式です。 EBNF 記述で示されているように、いくつかの式の種類のいずれかを指定できます。
対話型構文図を使用して、構文文法規則を調べることができます。
この記事の「正式な文法」セクションでは、完全な EBNF について説明します。
識別子
フィルター構文を使用すると、識別子の条件に一致する接続へのメッセージの送信を制御できます。 Azure Web PubSub では、次の識別子がサポートされています。
| 識別子 | 説明 | Note | 例 |
|---|---|---|---|
userId |
接続のユーザー ID | 大文字と小文字は区別されません。 文字列操作で使用できます。 | userId eq 'user1' |
connectionId |
接続の接続 ID | 大文字と小文字は区別されません。 文字列操作で使用できます。 | connectionId ne '123' |
groups |
接続が現在存在するグループのコレクション | 大文字と小文字は区別されません。 コレクション操作で使用できます。 | 'group1' in groups |
識別子は、接続のプロパティ値を参照します。 Azure Web PubSub では、接続モデルのプロパティ名と一致する 3 つの識別子がサポートされています。 さらに、文字列操作で識別子 userId と connectionId がサポートされ、収集操作で groups 識別子がサポートされます。
たとえば、user1 のユーザー ID を使用した接続を除外するには、フィルターを userId eq 'user1' として指定します。 フィルターを使用したその他のサンプルについては、次のセクションを参照してください。
ブール式
フィルターの式はブール式です。 Azure Web PubSub は、true と評価されたフィルター式を使用してメッセージを接続に送信します。
ブール式の種類は次のとおりです。
and、or、およびnotの演算子を使用することにより、他のブール式を結合する論理式。eq、ne、gt、lt、ge、およびleの演算子を使用することにより、フィールドまたは範囲変数と定数値とを比較する比較式。- ブール型リテラル:
trueおよびfalse。 これらの定数は、プログラムによってフィルターを生成する場合に便利な場合があります。 それ以外の場合は、実際には使用される傾向はありません。 - かっこで囲まれたブール式。 かっこを使用することは、フィルター内で操作の順序を明示的に決定するのに役立ちます。 OData 演算子の既定の優先順位の詳細については、「演算子の優先順位」セクションを参照してください。
サポート対象の操作
フィルター構文では次の操作がサポートされます。
| Operator | Description | 例 |
|---|---|---|
| 論理演算子 | ||
and |
論理積 | length(userId) le 10 and length(userId) gt 3 |
or |
論理和 | length(userId) gt 10 or length(userId) le 3 |
not |
論理否定 | not endswith(userId, 'milk') |
| 比較演算子 | ||
eq |
等しい | |
ne |
Not equal | |
gt |
より大きい | length(userId) gt 10 |
ge |
以上 | length(userId) ge 10 |
lt |
より小さい | length(userId) lt 3 |
le |
以下 | |
| In 演算子 | ||
in |
右側のオペランドは、かっこで囲まれた、プリミティブ値のコンマ区切りのリスト、またはコレクションに解決される単一の式のいずれかでなければなりません | userId ne 'user1' |
| グループ化演算子 | ||
() |
式の評価順序を制御する | userId eq 'user1' or (not (startswith(userId,'user2')) |
| 文字列関数 | ||
string tolower(string p) |
文字列値の小文字を取得する | tolower(userId) eq 'user1' は、ユーザー USER1 の接続を一致させることができます |
string toupper(string p) |
文字列値の大文字を取得する | toupper(userId) eq 'USER1' は、ユーザー user1 の接続を一致させることができます |
string trim(string p) |
文字列値をトリミングする | trim(userId) eq 'user1' は、ユーザー user1 の接続を一致させることができます |
string substring(string p, int startIndex, int length)= |
文字列の部分文字列 | substring(userId,5,2) eq 'ab' は、ユーザー user-ab-de の接続を一致させることができます |
bool endswith(string p0, string p1) |
p0 が p1 で終わっているかどうかを確認する |
endswith(userId,'de') は、ユーザー user-ab-de の接続を一致させることができます |
bool startswith(string p0, string p1) |
p0 が p1 で開始しているかどうかを確認する |
startswith(userId,'user') は、ユーザー user-ab-de の接続を一致させることができます |
int indexof(string p0, string p1) |
p0 内の p1 のインデックスを取得するか、 p0 に p1 が含まれていない場合は -1 を返します |
indexof(userId,'-ab-') ge 0 は、ユーザー user-ab-de の接続を一致させることができます |
int length(string p) |
入力文字列の長さを取得する | length(userId) gt 1 は、ユーザー user-ab-de の接続を一致させることができます |
| コレクション関数 | ||
int length(collection p) |
コレクションの長さを取得する | length(groups) gt 1 は 2 つのグループ内の接続を一致させることができる |
演算子の優先順位
サブ式をかっこで囲まずにフィルター式を記述した場合、Azure Web PubSub サービスでは一連の演算子の優先順位規則に従って式が評価されます。 これらの規則は、どの演算子を使用してサブ式が結合されているかに基づいています。 次の表に、優先順位の最も高いものから最も低いものへの順に演算子のグループを一覧表示します。
| グループ | 演算子 |
|---|---|
| 論理演算子 | not |
| 比較演算子 | |
| 論理演算子 | and |
| 論理演算子 | or |
上記の表で上位にある演算子は、他の演算子よりもオペランドに "より緊密にバインドされます"。 たとえば、 and は or よりも優先順位が高く、比較演算子の優先順位はどちらかより高くなります。 それゆえ、次の 2 つの式は等価です。
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))
not 演算子はすべてで最高の優先順位になります。 比較演算子よりもさらに高くなります。 次のようなフィルターを記述する場合:
not length(userId) gt 5
次のようなエラー メッセージが表示されます。
Invalid syntax for 'not length(userId)': Type 'null', expect 'bool'. (Parameter 'filter')
このエラーが発生するのは、演算子が length(userId) 式にのみ関連付けられていて、比較式全体には関連付けられていないためです。 length(userId) 式は、 userId が null であるときに null 型です。 修正するには、not のオペランドをかっこで囲みます。
not (length(userId) gt 5)
フィルター サイズの制限
Azure Web PubSub サービスに送信できるフィルター式のサイズと複雑性には制限があります。 この上限はおおよそ、フィルター式の句の数に基づきます。 目安として、100 以上の句がある場合、上限を超える危険性があります。 制限を超えないようにするには、無制限のサイズのフィルターが生成されないようにアプリケーションを設計します。
例
次の複数のグループに送信します。
filter='group1' in groups or 'group2' in groups or 'group3' in groups
次の特定のグループ内の複数のユーザーに送信します。
filter=userId in ('user1', 'user2', 'user3') and 'group1' in groups
特定の接続 ID ではなく、次のユーザーに送信します。
filter=userId eq 'user1' and connectionId ne '123'
次の特定のグループに含まれていないユーザーに送信します。
filter=userId eq 'user1' and (not ('group1' in groups))
ユーザー ID に次の ' が含まれている場合は、' をエスケープします。
filter=userId eq 'user''1'
正式な文法
次の拡張 Backus-Naur Form 文法では、Azure Web PubSub サービスがサポートする OData 言語のサブセットについて説明できます。 この文法では、最も複雑な式から始め、よりプリミティブな式に分解することで、ルールの一覧を "トップダウン" します。 上部にあるのは、Web PubSub サービス Send* REST API の特定のパラメーター filter に対応する $filter の文法規則です。
/* 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 ')'
次のステップ
これらのリソースを使用して、独自のアプリケーションの構築を開始します。