В этом руководстве описывается синтаксис фильтра списка и способы фильтрации различных типов ресурсов.
Некоторые методы API могут принимать фильтр для ограничения ресурсов, возвращаемых в ответе.
Краткое содержание
В этом разделе представлен краткий обзор синтаксической структуры фильтра списка.
Фильтр — это строка, содержащая
expression
.expression
представляет собой булевую комбинацию сравнений:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
comparison
сопоставляет поле ресурса со значением. Вы можете использовать все распространенные операторы сравнения.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
Оператор
has
, двоеточие (:
), можно использовать для строк и повторяющихся полей. Подробности смотрите в разделе Оператор Has .В фильтрах можно использовать следующие типы значений:
- Числа
- Струны
- Выражения в скобках
value = number| string | "*" | "(" expression ")"
Строки могут представлять следующее:
- Произвольный текст
- логические значения
- Перечисляемые значения
- Временные метки
Логические выражения
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
Операции производятся в следующем порядке:
-
NOT
-
OR
-
AND
Например, следующие выражения эквивалентны:
a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)
Вы можете опустить оператор AND
между сравнениями. Например, следующие фильтры одинаковы:
c=d AND e=f
c=d e=f
Вы можете использовать дефис ( -
) в качестве альтернативы NOT
. Между дефисом ( -
) и следующим сравнением не может быть пробела. Например, следующие фильтры одинаковы:
NOT e=f
-e=f
Сравнения
В этом разделе описываются сравнения "name OP value"
например:
comparison = name OP value
где
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
Левая часть сравнения — это путь к полю ресурса API. Имя состоит из серии идентификаторов ресурсов, соединенных точкой ( .
). За каждым идентификатором поля следует следующий уровень имен для этого поля. Например, рассмотрим ресурс, имеющий item
сложного поля, который имеет другой tool
сложного поля с полем с именем shape
. В фильтре для этого ресурса вы должны ссылаться на форму с именем item.tool.shape
.
Правая часть обычно представляет собой скалярное значение, которое преобразуется в тип поля и сравнивается с ним. Дополнительные сведения см. в разделе «Типы литералов значений» .
Правая часть сравнения также может быть выражена как заключенная в круглые скобки булева комбинация литеральных значений и/или логических выражений, содержащая только литеральные значения (с предшествующим NOT
или без него). Левое имя и оператор сравнения применяются к каждому значению. Например, следующие фильтры одинаковы:
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
Вот еще один, более сложный пример двух эквивалентных фильтров:
deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))
(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")
Типы литералов значений
Правое значение оператора сравнения можно разделить на числовые и строковые литералы.
Число
В этом разделе описывается представление числовых литералов.
Тип | Определение | Примеры |
---|---|---|
Двойной | Любое число, содержащее десятичную точку со знаком («-») или без него, считается двойным. |
|
Целое число | Любое число, не имеющее десятичной точки, со знаком («-») или без него, рассматривается как целое число. |
|
Нить
В этом разделе описаны типы, которые можно записать в виде строкового литерала в синтаксисе фильтра.
Тип | Определение | Примеры |
---|---|---|
логическое значение | TRUE или FALSE в любом регистре букв. |
|
Перечисление | Имя литерала перечисляемого типа. Перечисления чувствительны к регистру. | FINALIZED — это не то же самое, что Finalized |
Нить | Любая строка, содержащая текст в кодировке UTF-8 или 7-битный текст ASCII. Встроенные кавычки необходимо отделять обратной косой чертой. Строки без кавычек с пробелами обрабатываются как неявное «И» среди всех слов после разделения строки пробелами. |
|
Временная метка | Строка в стандартном формате ISO8601. | "2014-10-02T15:01:23.045Z" |
Операторы сравнения
Вот операторы сравнения:
- Меньше или равно:
"<="
- Меньше:
"<"
- Больше или равно:
">="
- Больше чем:
">"
- Не равно:
"!="
- Равно:
"="
- Имеет:
":"
Эти операторы применяются к типам значений Double, Integer, Boolean, Enum и Timestamp.
Имеет оператор
Вы можете использовать оператор HAS
( :
) для специальных операций над следующими полями:
- Подстроки
- Когда оператор
HAS
используется для сравнения значений строкового столбца со строкой, этот оператор действует как операция над строкой. Например,name:"abcd"
возвращает все экземпляры, гдеname
— это строка, содержащая"abcd"
. - Проверка существования
- Когда вы используете оператор
HAS
со специальным символом*
, операторHAS
проверяет наличие ненулевых значений. Например,name:*
возвращает все экземпляры, гдеname
не равно NULL, отсутствует или не определено. - Когда вы используете оператор
HAS
с нестроковыми значениями, он ведет себя так же, как операторEQUALS
(=
). Например,isCompleted:true
ведет себя так же, какisCompleted = true
. - Повторяющиеся поля
Вы можете использовать оператор
HAS
(:
) для фильтрации повторяющегося поля ресурса API, если выполняются следующие условия:- На пути идентификатора поля имеется только один повторяющийся компонент.
- Последний идентификатор пути к полю имеет скалярный тип.
Фильтрация по вложенным повторяющимся полям не поддерживается.
Вот пример:
item
имеет полеcolors
, которое содержит строковые значения, такие как"red"
,"blue"
и"yellow"
.-
item.colors:("red")
возвращает все элементы, имеющие значение"red"
в полеcolors
. -
item.colors:("red" "yellow")
возвращает все элементы, у которых в полеcolors
есть как"red"
так и"yellow"
. -
item.colors:("red" OR "yellow")
возвращает все элементы, у которых в полеcolors
указано"red"
или"yellow"
.
item
также имеет повторяющееся полеtools
, которое представляет собой сложный объект со скалярнойshape
поля, значения которого могут быть"square"
или"round"
.-
item.tools.shape:("square")
возвращает все элементы, имеющие инструменты"square"
формы. -
item.tools.shape:("square" "round")
возвращает все элементы, у которых есть инструмент как"square"
так и"round"
формы. -
item.tools.shape:("square" OR "round")
возвращает все элементы, у которых есть инструмент"square"
или"round"
формы.
-
Незаполненные вложенные поля
Вложенные поля — это подполя полей корневого уровня, например shape
в item.tools.shape
— это вложенное поле items.tools
.
Поля корневого уровня по умолчанию имеют значение false. По умолчанию вложенные поля не заполняются.
Объекты с незаполненными вложенными полями не возвращаются отрицательными фильтрами ( !=
).
Вот пример:
item.tools
имеет перечисление size
, значение которого может быть установлено как "SMALL"
, "MEDIUM"
или "LARGE"
.
Если у вас есть следующие предметы:
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
},
{
"name": "item3"
}
Вызов items.list
с отрицательным фильтром "tools.size != SMALL"
возвращает следующее:
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
Поскольку item.tools.size
не был установлен для item3
, отрицательный фильтр не возвращает объект item3
.
Примеры
Пример | Описание |
---|---|
externalDealId = "123456789" | externalDealId со строковым значением «123456789». |
advertiserId:93641 | advertiserId , имеющий целочисленное значение 93641. |
isSetupComplete = true | isSetupComplete имеет значение TRUE. |
updateTime > "2018-02-14T11:09:19.378Z" | updateTime позднее 14.02.2018 11:09:19.378 UTC |
displayName = "proposal" AND proposalRevision = 3 | Строка displayName имеет идентичное значение «предложения», И предложениеRevision равно 3. |
displayName = "proposal" OR proposalRevision = 3 | displayName имеет строковое значение «предложение» ИЛИ предложениеRevision равно 3. |
NOT displayName = "proposal" | displayName не равно «предложению». |
proposalState = (PROPOSED OR BUYER_ACCEPTED) | proposalState имеет значение перечисления, равное PROPOSED ИЛИ BUYER_ACCEPTED. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) | proposalState имеет значение перечисления, равное PROPOSED AND BUYER_ACCEPTED. |
dealName = Test Deal | INVALID выражение |
dealName = "Test Deal" | dealName равно «Тестовая сделка». |
dealName = (Test Deal) | dealName равно «Test», а также равно «Deal». |
dealName = ("Test1" OR "Test2") | dealName либо равно «Test1», либо равно «Test2». |
dealName:* | dealName is not null. |
dealName:"test" | dealName содержит подстроку «test». |
dealName:("AB") | dealName содержит подстроку «AB». |
dealName:(AB) | dealName содержит подстроку «A» и подстроку «B». |
dealName:("A" OR "B" AND "C") | dealName содержит подстроку «A» ИЛИ «B», А также содержит подстроку «C». |
dealName:("AB" C) | dealName содержит подстроку «AB», а также подстроку «C». |
dealName:("AB" OR CD) | dealName содержит подстроку «AB» или «C», а также подстроку «D». |
dealName:(NOT "A" B) | dealName не содержит подстроки «A», а также содержит подстроку «B». |
dealName:(NOT "A" OR "B") | dealName не содержит подстроки «A» или содержит подстроку «B». |