Реализовано в версии 8.3.8.1652.
В REST интерфейсе прикладных решений, о котором мы рассказывали раньше, мы реализовали не все, а только основные возможности протокола OData. Они позволяют получать доступ к внутренним объектам 1С:Предприятия с помощью URL-запросов. Однако опыт использования REST интерфейса показал, что для быстрой и гибкой интеграции этих возможностей не всегда хватает.
Поэтому мы расширили поддержку стандартных возможностей протокола OData, а также реализовали некоторые функции, которых нет в протоколе, но они используются 1С:Предприятием. Кроме этого мы добавили пару возможностей, которые, судя по вашим сообщениям, являются наиболее востребованными. Это отбор по полям составного типа, и отбор по реквизитам табличных частей.
Ранее в REST интерфейсе уже была возможность отбирать по значениям ссылочных полей. Например, в следующем примере будут получены записи регистра, относящиеся к валюте с уникальным идентификатором 7f4b5034-0331-11e3-b914-5404a6a68c42.
GET /OData_Test_Infobase/odata/standard.odata/InformationRegister_КурсыВалют?$filter=Валюта eq guid'7f4b5034-0331-11e3-b914-5404a6a68c42'
Однако если поле, по которому осуществляется отбор (Валюта), имело составной тип, то такое условие уже не работало. И возможности отбирать по таким полям не существовало.
Теперь мы такую возможность добавили. Например, регистр сведений Характеристики содержит измерение Объект. Это измерение имеет составной тип, включающий ссылку на справочник Товары. Тогда следующий пример вернёт только те записи регистра, которые относятся к товару, имеющему guid равный 0d4a79cb-9843-4147-bcd9-80ac3ca2b9c7.
GET /OData_Test_Infobase/odata/standard.odata/InformationRegister_Характеристики?$filter=Объект eq cast(guid'0d4a79cb-9843-4147-bcd9-80ac3ca2b9c7', 'Catalog_Товары')
В этом примере используется новая функция cast, о которой мы расскажем далее.
В REST интерфейсе был реализован ограниченный набор опций: $format, $metada, $filter и $select. Теперь мы добавили к ним ещё несколько полезных опций, которые должны облегчить решение задач интеграции.
$orderby
Указывает порядок, в котором будут получены записи. Следующий пример возвращает список товаров в порядке возрастания наименования.
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Товары?$orderby=Наименование asc
$skip
Отбрасывает первую часть результата запроса. Следующий пример возвращает список товаров, начиная с третьей позиции.
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Товары?$orderby=Наименование asc&$skip=2
Эту опцию, совместно с опцией $top, вы можете использовать для постраничного вывода результатов. Следующий пример возвращает список товаров с 3 по 13 позиции.
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Товары?$orderby=Наименование asc&$skip=2?$top=11
$inlinecount
Дополняет результат запроса количеством записей, полученных запросом. Следующий пример возвращает список товаров и их количество.
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Товары?$inlinecount=allpages
Результат такого запроса в формате JSON будет выглядеть следующим образом:
{
"odata.metadata": "http://localhost/OData_Test_Infobase/odata/standard.odata/$metadata#Catalog_Товары ",
"odata.count": "19",
"value": [{...}, ..., {...}]
}
$count
Возвращает только количество элементов, содержащихся в результате запроса. Следующий пример возвращает количество товаров.
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Товары?$count
При отборе и при сортировке результатов вы можете использовать теперь новые функции, предусмотренные стандартом OData. Но кроме этого мы добавили ещё несколько удобных функций, стандартом не предусмотренных, но давно используемых в 1С:Предприятии.
substring
Возвращает подстроку от значения поля. Подстрока начинается с указанной позиции, и имеет указанную длину. Например, если в информационной базе артикул товара формируется по принципу <буквы>-<цифры>, то следующий запрос возвращает те товары, у которых буквенная часть артикула содержит два символа (ОБ-00055, ПС-0002 и т.д.).
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Товары?$filter=substring(Артикул, 2, 1) eq '-'
substringof
Определяет, содержится ли указанная подстрока в значении поля. Следующий запрос возвращает те товары, у которых в артикуле содержится подстрока ПРД.
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Товары?$filter=substringof('ПРД', Артикул)
startswith, endswith
Определяет, начинается ли (заканчивается ли) значение поля с указанной подстроки. Следующий пример возвращает товары, артикул которых начинается с VEKO.
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Товары?$filter=startswith(Артикул, 'VEKO')
concat
Объединяет две строки в одну. Следующий пример возвращает контрагентов, для связи с которыми используется телефонный номер +7(999)456-87-68.
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Контрагенты?$filter=substringof('+7(999)456-87-68', concat(Телефон, Факс))
year, month, day, hour, minute, second
Возвращает год (номер месяца, день, количество часов, минут, секунд) от значения поля. Следующий пример возвращает все документы оплаты за 2015 год.
GET /OData_Test_Infobase/odata/standard.odata/Document_Оплата?$filter=year(Дата) eq 2015
isof
Определяет, имеет ли значение поля указанный тип. Например, в справочнике Товары указано, что поле Артикул используется только для элементов. Тогда следующий пример вернёт только элементы справочника, без групп. Потому что для групп значение этого поля имеет тип NULL.
GET /OData_Test_Infobase/odata/standard.odata/Catalog_Товары?$filter=isof(Артикул, 'String')
cast
Приводит значение к указанному типу. Может использоваться при отборе по полям составного типа. В следующем примере эта функция создаёт значение ссылки на справочник Товары, которая имеет указанный уникальный идентификатор.
GET /OData_Test_Infobase/odata/standard.odata/InformationRegister_Характеристики?$filter=Объект eq cast(guid'0d4a79cb-9843-4147-bcd9-80ac3ca2b9c7', 'Catalog_Товары')
round
Округляет значение до ближайшего целого числа.
Для того чтобы реализовать возможность отбора по реквизитам табличных частей, мы добавили два новых оператора: any и all. Они применяют логическое выражение к каждой строке табличной части и возвращают значение Истина, если хотя бы для одной строки (any) (для всех строк (all)) это логическое выражение верно. Следующий пример возвращает все документы продажи, в которых есть товары с ценой больше 10000.
GET /OData_Test_Infobase/odata/standard.odata/Document_РасходТовара?$filter=Товары/any(d: d/Цена gt 10000)
Небольшое пояснение по синтаксису. Оператор any предваряется именем табличной части (Товары), и отделяется от неё слешем. В скобках указывается имя переменной (d), которая будет использована в логическом выражении, и которая указывает на табличную часть. После имени переменной следует двоеточие. Затем указывается логическое выражение (d/Цена gt 10000), которое должно проверяться.
