Интерфейс OData: правила формирования условия отбора
Общая информация
В данном разделе приводится информация по различным способам формирования отбора получаемых данных, используемых в стандартном интерфейсе OData системы «1С:Предприятие».
Описание возможностей отбора в протоколе OData можно получить в документации по протоколу (на английском языке):
- http://www.odata.org/documentation/odata-version-3-0/odata-version-3-0-core-protocol/ раздел 10.2.3.1;
- http://www.odata.org/documentation/odata-version-3-0/odata-version-3-0-core-protocol/ раздел 5.1.2.
$filter
При получении данных можно фильтровать данные. Для этого предназначен специальный язык, который позволяет описывать условия, каким должны соответствовать данные, которые возвращает стандартный интерфейс OData. Описание отбора начинается с ключевого слова $filter, после которого следует собственно условие. Поддерживаются следующие операции:
- Логические операции:
| Описание | Имя | Пример |
|---|---|---|
|
Равно |
eq |
/Catalog_Города?$filter=Description eq ‘Главный’ |
|
Не равно |
ne |
/Catalog_Города?$filter=Description ne ‘Пермь’ |
|
Больше |
gt |
/Catalog_Товары?$filter=Цена gt 10 |
|
Больше или равно |
ge |
/Catalog_Товары?$filter=Цена ge 10 |
|
Меньше |
lt |
/Catalog_Товары?$filter=Цена lt 10 |
|
Меньше или равно |
le |
/Catalog_Товары?$filter=Цена le 10 |
|
Логическое Или |
or |
/Catalog_Товары?$filter=Цена lt 10 or Цена gt 100 |
|
Логическое И |
and |
/Catalog_Товары?$filter=Цена gt 10 and Цена lt 100 |
|
Отрицание |
not |
/Catalog_Товары?$filter=not (Цена eq 10) |
- Арифметические операции:
| Описание | Имя | Пример |
|---|---|---|
|
Сложение |
add |
/Catalog_Товары?$filter=Цена add 5 gt 10 |
|
Вычитание |
sub |
/Catalog_Товары?$filter=Цена sub 5 gt 10 |
|
Умножение |
mul |
/Catalog_Товары?$filter=Цена mul 5 gt 1000 |
|
Деление |
div |
/Catalog_Товары?$filter=Цена div 4 gt 2 |
- Группирующие операторы:
| Описание | Имя | Пример |
|---|---|---|
|
Приоритет операции |
() |
/Catalog_Товары?$filter=(Цена add 5) gt 10 |
Пример отбора:
https:/host/base/zone/odata/standard.odata/Catalog_Товары?$filter=Имя eq 'Молоко' and Цена lt 2500
При формировании условия отбора следует учитывать приоритет операций. В следующей таблице представлен список операций языка выражений отбора в порядке уменьшения приоритета. Операции с одинаковым приоритетом вычисляются слева направо:
| Оператор | Описание |
|---|---|
|
( ) |
Повышение приоритета операции |
|
/ |
Навигация |
|
– |
Арифметическое отрицание |
|
Not |
Логическое отрицание |
|
Mul |
Умножение |
|
Div |
Деление |
|
Add |
Сложение |
|
Sub |
Вычитание |
|
Gt |
Больше |
|
Ge |
Больше или равно |
|
Lt |
Меньше |
|
Le |
Меньше или равно |
|
Eq |
Равно |
|
Ne |
Не равно |
|
And |
Логическое «И» |
|
Or |
Логическое «ИЛИ» |
При формировании условий запроса (параметр filter) или формировании реквизита, по которому выполняется упорядочивание (параметр orderby) могут применяться следующие функции:
- Строковые функции:
| Функция | Описание | Пример |
|---|---|---|
|
substringof(Str1, Str2) |
Возвращает true в том случае, если Str1 является подстрокой Str2. |
/Catalog_Товары?$filter=substringof(‘Красный Октябрь’, Производитель) eq true |
|
endswith(Str1, Str2) |
Возвращает true в том случае, если Str1 заканчивается на Str2. |
/Catalog_Товары?$filter=endswith(Производитель, ‘ООО’) eq true |
|
startswith(Str1, Str2) |
Возвращает true в том случае, если Str1 начинается на Str2. |
/Catalog_Товары?$filter=startswith(Производитель, ‘ООО’) eq true |
|
substring(Str, Int1) |
Возвращает подстроку из Str1. В варианте с двумя параметрами возвращается строка с позиции Int и до конца строки. |
/Catalog_Поставщики?$filter=substring(ИНН, 1, 2) eq ’77’ |
|
substring(Str, Int1, Int2) |
В варианте с тремя параметрами возвращается подстрока, начиная с позиции Int1 и длиной Int2. |
/Catalog_Поставщики?$filter=substring(ИНН, 1, 2) eq ’77’ |
|
concat(Str1, Str2) |
Возвращает строку, являющуюся результатом конкатенации Str1 и Str2. |
/Catalog_Поставщик?$filter=concat(concat(Город, ‘, ‘), Страна) eq ‘Москва, Россия’ |
|
like(Str, Template) |
Возвращает true, если значение Str1 удовлетворяет шаблону Template. Синтаксис шаблона аналогичен функции ПОДОБНО() языка запросов (см. здесь). |
/Catalog_Товары?$filter= like(Наименование, ‘[^к]%’) |
- Функции работы с датами:
| Функция | Описание | Пример |
|---|---|---|
|
year(DateTime) |
Возвращает год из значения типа Edm.DateTime или Edm.DateTimeOffset. |
/Catalog_Товары?$filter=year(Произведен) eq 2013 |
|
quarter(DateTime) |
Номер квартала года, в котором находится указанное значение типа Edm.DateTime. |
/Catalog_Товары?$filter=quarter(ДатаПроизводства) eq 1 |
|
month(DateTime) |
Возвращает месяц из значения типа Edm.DateTime или Edm.DateTimeOffset. |
/Catalog_Товары?$filter=month(Произведен) eq 12 |
|
day(DateTime) |
Возвращает день из значения типа Edm.DateTime или Edm.DateTimeOffset. |
/Catalog_Товары?$filter=day(Произведен) eq 1 |
|
hour(DateTime) |
Возвращает значение часов из значения типа Edm.DateTime или Edm.DateTimeOffset. |
/Catalog_Товары?$filter=hour(Произведен) eq 23 |
|
minute(DateTime) |
Возвращает значение минут из значения типа Edm.DateTime или Edm.DateTimeOffset. |
/Catalog_Товары?$filter=minute(Произведен) eq 59 |
|
second(DateTime) |
Возвращает значение секунд из значения типа Edm.DateTime или Edm.DateTimeOffset. |
/Catalog_Товары?$filter=second(Произведен) eq 59 |
|
datedifference(DateTime1, DateTime2, Type) |
Возвращает разность дат DateTime2 и DateTime1 в единицах, указанных параметром Type:
|
/Catalog_Товары?$filter=datedifference(Произведен, ГоденДо, ‘day’) gt 10 |
|
dateadd(DateTime1, Type, Int1) |
Возвращает дату, полученную добавлением к значению DateTime1 значения Int1, выраженное в единицах Type:
|
/Catalog_Товары?$filter=dateadd(Произведен, ‘month’, 1) eq ГоденДо |
|
dayofweek(DateTime) |
Возвращает день недели по значению типа Edm.DateTime. |
/Catalog_Товары?$filter=dayofweek(ДатаПроизводства) eq 7 |
|
dayofyear(DateTime) |
Возвращает день года по значению Edm.DateTime. |
/Catalog_Товары?$filter=dayofyear(ДатаПроизводства) eq 1 |
- Прочие функции:
| Функция | Описание | Пример |
|---|---|---|
|
round(Number) |
Возвращает параметр, округленный до ближайшего целого числа. |
/Catalog_Товары?$filter=round(Вес) gt 31 |
|
isof(expr, type) |
Возвращает true в том случае, когда объект, на который указывает параметр expr, имеет тип, на который ссылается type. В качестве типа значения принимается строка, обозначающая имя данного типа, например: String, Number, Boolean, Date, Catalog_Товары и т. д. |
/Catalog_Товары?$filter=isof(Цена, ‘Number’) |
|
cast(expr, type) |
Возвращает объект, на который указывает параметр expr, приведенный к типу, указанному параметром type. В качестве типа значения принимается строка, обозначающая имя данного типа, например: String, Number, Boolean, Date, Catalog_Товары и т. д. |
/Catalog_Товары?$filter= cast(РеквизитСоставной, ‘Number’) le 12 |
ПРИМЕЧАНИЕ. Не поддерживаются операции сравнения с реквизитом типа ХранилищеЗначения.
Имеется возможность выполнять отбор сущностей при помощи проверки на равенство поля составного типа и ссылки. Для этого следует использовать функцию cast().
Пример:
$filter=ДокументПрихода eq cast(guid'0d4a79cb 9843 4147 bcd9 80ac3ca2b9c7', 'Document_ПриходнаяНакладная')
В данном примере у используемой сущности имеется реквизит составного типа ДокументПрихода. Запрос будет отбирать все записи сущности, у которой данный реквизит заполнен ссылкой на документ ПриходнаяНакладная с указанным уникальным идентификатором (0d4a79cb-9843-4147-bcd9-80ac3ca2b9c7).
Если требуется выполнить отбор по реквизиту типа УникальныйИдентификатор, то это выполняется с помощью простой операции сравнения:
$filter=ИмяРеквизита eq guid'0d4a79cb 9843 4147 bcd9 80ac3ca2b9c7'
Для отбора по типу какого-либо реквизита составного типа следует использовать функцию isof():
$filter=isof(ДокументыПрихода, 'Document_ПриходнаяНакладная')
Следующее выражение всегда вернет пустой результат запроса, вне зависимости от физического наличия используемого уникального идентифкатора в соответствующей колонке сущности:
$filter=ДокументыПрихода eq guid'0d4a79cb 9843 4147 bcd9 80ac3ca2b9c7'
При необходимости выполнить отбор по элементу коллекции, необходимо использовать лямбда-функции. В качестве аргументов лямбда-функции выступает имя лямбда-переменной, за которой следует символ двоеточия и логическое выражение, которое использует лямбда-переменную для указания на свойства элемента коллекции. Система поддерживает использование следующих лямбда-функций:
- any – применяет логическое выражение к каждому элементу коллекции и возвращает значение true, если хоть один элемент коллекции удовлетворяет этому условию. Лямбда-функция any без аргументов возвращает true, если коллекция не пуста.
https://host/base/zone/odata/standard.odata/Document_Продажи?$filter=Товары/any(d: d/Цена gt 10000)
В приведенном примере формируется список документов Продажи, у которых есть табличная часть Товары, в которой есть реквизит Цена. При этом Цена должна быть больше, чем 10000. В результирующий список попадут документы, в состав которых входит хотя бы одна строка, удовлетворяющая условию.
- all – применяет логическое выражение к каждому элементу коллекции и возвращает значение true, если все элементы коллекции ему удовлетворяет.
https://host/base/zone/odata/standard.odata/Document_Продажи?$filter=Товары/all(d: d/Цена lt 10000)
В приведенном примере формируется список документов Продажи, у которых есть табличная часть Товары, в которой есть реквизит Цена. При этом Цена должна быть меньше, чем 10 000. В результирующий список попадут документы, в составе которых все строки удовлетворяют заданному условию.
При необходимости указать условие на значение реквизита другого реквизита составного типа, содержащего ссылочные значения, таким образом, чтобы проверялось одновременно и значение проверяемого реквизита и тип составного реквизита, требуется использовать функцию cast().
Например, имеется документ МаршрутныйЛист, который содержит реквизит составного типа ОснованиеОтгрузки. Данный реквизит может принимать значения типа ДокументСсылка.Накладная и ДокументСсылка.ВнутреннееПеремещение. При этом у документа Накладная существует реквизит МестоОтгрузки, который может принимать значения типа СправочникСсылка.Склад и СправочникСсылка.АдресаОтгрузки.
В том случае, если необходимо отобрать документы МаршрутныйЛист с условием по названию склада, указанного в накладной (т.е. по реквизиту Название объекта типа СправочникСсылка.Склад, записанного в реквизит МестоОтгрузки документа Накладная), то условие должно выглядеть следующим образом:
cast(cast(ОснованиеОтгрузки, 'Document_Накладная')/МестоОтгрузки, 'Catalog_Склад')/Название eq 'Основной в Москве'
Не поддерживаются следующие стандартные функции: lenght, indexof, replace, tolower, toupper, trim, years, days, hours, seconds, floor, ceiling;
$top
Имеется возможность ограничить количество записей, возвращаемых при обращении к ресурсу. Для этого используется параметр $top.
Пример:
http://host/odata/standard.odata/Catalog_Товары?$filter=Цена lt 1000&$top=10
allowedOnly
Если при выполнении запроса необходимо получить только те объекты данных, которые не попадают под ограничения доступа к данным, то в URL получения данных необходимо добавить параметр allowedOnly.
Пример:
https://host/base/zone/odata/standard.odata/Catalog_Товары?$allowedOnly=true
Если параметр не указан или указан со значением false, то во время исполнения запроса к данным может возникнуть ошибка с кодом 401 (если результат выполнения запроса содержит данные, доступ к которым запрещен). Ошибка может не произойти в том случае, если были указаны дополнительные условия, которые ограничили выборку только разрешенными данными.
Например, для справочника Данные настроено ограничение доступа к данным, которое не позволяет получить элементы справочника, у которых реквизит ЗначениеСекретности равно 1, но позволяет получить элементы справочника, у которых реквизит ЗначениеСекретности равно 2. В этом случае следующий запрос не приведет к возникновению ошибки, т. к. явно накладывается условие, которое оставляет в выборе только разрешенные данные:
https://host/base/zone/odata/standard.odata/Catalog_Данные?allowedOnly=false&$filter=ЗначениеСекретности eq 2
Параметр allowedOnly можно использовать только для GET-запросов к наборам сущностей.
$skip
Позволяет исключить из результата запроса первые несколько записей. Если параметры $top и $skip указываются одновременно, то параметр $skip будет применен раньше, чем параметр $top. Приоритет применения параметров не зависит от порядка их указания в теле запроса.
Пример:
https://host/base/zone/odata/standard.odata/Catalog_Товары?$skip=2
