← Cloudflare Ruleset Engine / ruleset-engine / rules-language

Операторы и символы группировки

Cloudflare Rules language поддерживает операторы сравнения и логические операторы:

• Операторы сравнения определяют, каким образом значения, заданные в выражении, должны соотноситься с фактическим значением HTTP-запроса, чтобы выражение вернуло true.
• Логические операторы объединяют два выражения в составное выражение и используют порядок приоритета операций, чтобы определить, как вычисляется выражение.

Grouping symbols позволяют упорядочивать выражения, задавать приоритет вычислений и вкладывать выражения друг в друга.

Операторы сравнения возвращают true когда значение из HTTP-запроса совпадает со значением, заданным в выражении.

Ниже приведена общая схема использования операторов сравнения:

<field> <comparison_operator> <value>

Rules language поддерживает следующие операторы сравнения:

¹ Все строковые операторы чувствительны к регистру, если явно не указано, что они нечувствительны к регистру, как, например, wildcard оператор.
² Доступ к matches оператор требует план Cloudflare Business или Enterprise.
³ В настоящее время не все продукты Cloudflare поддерживают списки в выражениях. Подробнее о списках см. в Встроенные списки и Lists.

В зависимости от конкретного поля и типа правила Cloudflare dashboard может показывать следующие дополнительные операторы:

• starts with (что соответствует starts_with() функция): Возвращает true когда строка начинается с заданной подстроки, а false в противном случае.

• заканчивается на (что соответствует ends_with() функция): Возвращает true когда строка заканчивается заданной подстрокой, а false в противном случае.

• входит в список (что соответствует <FIELD> in $<LIST_NAME>): Возвращает true когда значение поля присутствует в указанном список, а также false в противном случае. Дополнительную информацию см. в Использование списков в выражениях.

• не входит в список (что соответствует not <FIELD> in $<LIST_NAME>): Возвращает true когда значение поля отсутствует в указанном список, а также false в противном случае. Дополнительную информацию см. в Использование списков в выражениях.

Сравнение строк в выражениях правил учитывает регистр. Чтобы учесть возможные варианты написания строк в выражении, вы можете использовать lower() функцию и сравните результат со строкой в нижнем регистре, как в следующем примере:

lower(http.request.uri.path) contains "/wp-login.php"

Сопоставление с подстановочными знаками поддерживается только с wildcard и strict wildcard операторы и сопоставление с регулярным выражением поддерживается только с matches оператор.

wildcard оператор выполняет сравнение без учёта регистра между значением поля и строковым литералом, содержащим ноль или более * метасимволов. Каждый * метасимвол обозначает ноль или более символов. strict wildcard оператор выполняет аналогичное сравнение, но с учётом регистра.

При использовании wildcard/strict wildcard оператор, всё значение поля должно совпадать со строковым литералом с подстановочными знаками (литералом после оператора).

# The following expression:
http.request.full_uri wildcard "http*://example.com/a/*"

# Would match the following URIs:
# - https://example.com/a/           (the '*' matches zero characters)
# - http://example.com/a/
# - https://example.com/a/page.html
# - https://example.com/a/sub/folder/?name=value

# Would NOT match the following URIs:
# - https://example.com/ab/
# - https://example.com/b/page.html
# - https://sub.example.com/a/

# The following expression:
http.request.full_uri wildcard "*.example.com/*/page.html"

# Would match the following URIs:
# - http://sub.example.com/folder/page.html
# - https://admin.example.com/team/page.html
# - https://admin.example.com/team/subteam/page.html

# Would NOT match the following URIs:
# - https://example.com/ab/page.html                   ('*.example.com' matches only subdomains)
# - https://sub.example.com/folder2/page.html?s=value  (http.request.full_uri includes the query string and its full value does not match)
# - https://sub.example.com/a/                         ('page.html' is missing)

# The following expression:
http.request.full_uri wildcard "*.example.com/*" or http.request.full_uri wildcard "http*://example.com/*"

# Would match the following URIs:
# - https://example.com/folder/list.htm
# - https://admin.example.com/folder/team/app1/
# - https://admin.example.com/folder/team/app1/?s=foobar

Алгоритм сопоставления, используемый wildcard оператор не учитывает регистр. Чтобы выполнить подстановочное сравнение с учётом регистра, используйте strict wildcard оператор.

Чтобы ввести литерал * символ в строковом литерале с подстановочными знаками нужно экранировать с помощью \*. Кроме того, необходимо также экранировать \ с помощью \\. Два неэкранированных * символов подряд (**) в строковом литерале с подстановочными знаками считаются недопустимыми и не могут использоваться. Если необходимо экранирование символов, рекомендуется использовать синтаксис необработанных строк чтобы задать строковый литерал с подстановочными знаками.

Клиентам на тарифах Business и Enterprise доступен matches оператор. Сравнение по регулярным выражениям выполняется с использованием движка регулярных выражений Rust.

Если вы используете регулярное выражение, вы можете протестировать его с помощью такого инструмента, как Regular Expressions 101 ↗ или Rustexp ↗.

Дополнительные сведения о регулярных выражениях см. в Строковые значения и регулярные выражения.

Логические операторы объединяют два или более выражений в одно составное выражение. Составное выражение имеет следующий общий синтаксис:

<expression> <logical_operator> <expression>

У каждого логического оператора есть порядок приоритета. Порядок приоритета (наряду с символы группировки) определяют порядок, в котором Cloudflare вычисляет логические операторы в выражении. not оператор стоит первым по приоритету.

При написании составных выражений важно учитывать приоритет логических операторов, чтобы выражение вычислялось так, как вы ожидаете.

Например, рассмотрим следующее обобщённое выражение, использующее and и or операторов:

Expression1 and Expression2 or Expression3

Если бы у этих операторов не было порядка приоритета, было бы непонятно, какая из двух интерпретаций верна:

1. Совпадение, если верны и выражение 1, и выражение 2 или когда выражение 3 истинно.
2. Совпадение, если верно выражение 1 и либо Expression 2, либо Expression 3 принимает значение true.

Поскольку логический and оператор имеет приоритет над логическим or, and оператор должен вычисляться первым. Правильна интерпретация 1.

Чтобы избежать неоднозначности при работе с логическими операторами, используйте группирующие символы, чтобы порядок вычисления был явным.

Rules language поддерживает скобки ((,)) в качестве группирующих символов. Группирующие символы позволяют структурировать выражения, задавать приоритет операций и вкладывать выражения друг в друга.

Только Expression Editor и Cloudflare API поддерживают группирующие символы. Expression Builder не поддерживает.

Используйте круглые скобки, чтобы явно сгруппировать выражения, которые должны вычисляться вместе. В этом примере скобки не влияют на результат вычисления выражения, но однозначно показывают, какие логические операторы нужно вычислить первыми.

(Expression1 and Expression2) or Expression3

Группирующие символы делают выражение более явным, поэтому при их использовании в составных выражениях вероятность ошибок снижается.

Группирующие символы представляют собой мощное средство, которое задаёт приоритет для сгруппированных элементов составного выражения. В этом примере скобки заставляют логический or оператор вычислялся раньше логического and:

Expression1 and (Expression2 or Expression3)

Без скобок логический and оператор имел бы более высокий приоритет.

Вы можете вкладывать выражения, сгруппированные скобками, в другие группы и получать точные и сложные конструкции. Например, ниже показано правило, блокирующее доступ к домену:

(
 (http.host eq "api.example.com" and http.request.uri.path eq "/api/v2/auth") or
 (http.host matches "^(www|store|blog)\.example\.com" and http.request.uri.path contains "wp-login.php") or
 ip.src.country in {"CN" "TH" "US" "ID" "KR" "MY" "IT" "SG" "GB"} or ip.src.asnum in {12345 54321 11111}
) and not ip.src in {11.22.33.0/24}

Обратите внимание: при определении приоритета логических операторов скобки внутри строк в кавычках не учитываются. Такой случай показан в следующем регулярном выражении, взятом из примера выше:

"^(www|store|blog)\.example\.com"