Интерфейс OData: параметры запроса

Про параметры $count, $inlinecount, $orderby, $expand: описание и примеры использования.

Интерфейс OData в 1С: Управление торговлей 10.3 предоставляет мощные возможности для интеграции с внешними системами и автоматизации процессов. Понимание и правильное использование параметров запроса OData позволяет эффективно извлекать и обрабатывать данные, соответствующие бизнес-требованиям.

Интерфейс OData: параметры запроса

$count— получение количества записей

Параметр $count используется для получения количества записей, которые соответствуют условиям запроса, без получения самих данных. Это полезно, когда нужно узнать количество объектов в базе данных, которые соответствуют определённым фильтрам, но не обязательно загружать их все.

Пример:

// возвращает количество элементов справочника Товары,
					// для которых справедливо условие: значение реквизита Цена больше 500
				https://host/base/standard.odata/Catalog_Товары/$count?$filter=Цена gt 500

В этом примере запрос вернёт только количество товаров, у которых цена больше 500. Не будут загружены данные о самих товарах, только число, которое указывает, сколько таких товаров в базе.

• $count=true — в ответе будет возвращено количество записей, которые соответствуют фильтру.

Результат запроса может выглядеть как:

Это означает, что в базе 15 товаров, которые соответствуют условию фильтра.

$inlinecount

— альтернативный способ подсчёта записей

Параметр $inlinecount в OData был ранее используем для получения количества записей в ответе на запрос. В более новых версиях OData и в 1С он может быть заменён на $count. Тем не менее, для совместимости с более старыми версиями OData иногда всё ещё можно встретить использование $inlinecount.

Ранее параметр $inlinecount позволял включить количество записей непосредственно в основной ответ, который также содержал саму информацию о данных.

Пример:

http://host/base/zone/odata/standard.odata/Catalog_Товары?$inlinecount=allpages0

Пример результата запроса, с параметром $inlinecount=allpages:

Формат atom-xml:

<?xml version="1.0" encoding="UTF 8"?>
					<feed xmlns=http://www.w3.org/2005/Atom xmlns:at=http://purl.org/atompub/tombstones/1.0 xmlns:d=http://schemas.microsoft.com/ado/2007/08/dataservices xmlns:m=http://schemas.microsoft.com/ado/2007/08/dataservices/metadata xml:base="http://host/ODataTests/odata/standard.odata/">
					<entry>
					…
					</entry>
					…
					<entry>
					…
					</entry>
					<m:count>19</m:count>
					</feed>
				

$orderby — сортировка данных

Параметр $orderby позволяет сортировать результат запроса по указанным полям. Вы можете задать одно или несколько полей для сортировки, а также указать порядок сортировки (по возрастанию или убыванию).

• asc — сортировка по возрастанию (по умолчанию).

• desc — сортировка по убыванию.

Пример:

http://host/base/zone/odata/standard.odata/Catalog_Товары?$orderby=Название asc, Производитель desc

Допускается упорядочивание по свойствам дочерних реквизитов. В этом случае полное имя реквизита, по которому выполняется упорядочивание, формируется с использованием разделителя «/».

Пример:

http://host/base/zone/odata/standard.odata/Document_Расход?$orderby=Контрагент/ИНН asc

В этом примере упорядочивание будет произведено по возрастанию (asc) значения реквизита ИНН у сущности, на которую ссылается реквизит Контрагент документа Расход.

$expand — расширение связанных сущностей

Параметр $expand используется для получения данных из связанных сущностей. Это позволяет запросить не только данные о текущей сущности, но и связанные объекты, например, информацию о поставщиках для каждого товара, если она есть в базе.

Валовая прибыль предприятия от комиссионных продаж для КА

от 0 руб.

Тестировать бесплатно

Это особенно полезно для работы с связанными данными в системе, когда необходимо получить информацию из нескольких таблиц за один запрос.

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Сертификат

Для каждого элемента из справочника Клиенты, в результат запроса должен быть помещен объект, на который ссылается реквизит Сертификат.

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Договор/Document_ДоговорНайма/Заявление

Для каждого элемента из справочника Клиенты, в результат запроса должен быть добавлен объект, на который ссылается реквизит составного типа Договор (если он содержит какое-либо ссылочное значение). Если реквизит Договор хранит ссылку на объект типа ДокументСсылка.ДоговорНайма, то объект, на который ссылается Договор.Заявление так же должен быть добавлен в результате запроса.

Значение * в конце пути параметра $expand означает необходимость раскрыть все навигационные ссылки внутри сущности. Однако, нельзя раскрывать навигационные поля у составного реквизита без явного указания типа ссылки.

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Договор/Document_ДоговорНайма/*

В данном примере Договор — это составной реквизит. Данный вариант указания * не поддерживается.

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=*

Для каждого элемента из справочника Клиенты, в результат запроса должны быть добавлены объекты, на которые ссылаются все навигационные ссылки объекта Клиента.

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Договор/*

Для каждого элемента из справочника Клиенты, в результат запроса должны быть добавлены объекты, на которые ссылаются все навигационные ссылки внутри объекта Договор и сам объект Договор. При этом реквизит Договор является реквизитом ссылочного типа.

Ограничения параметра $expand:

• Не поддерживается расширение реквизитов табличных частей.
• Не поддерживается расширение при запросе одиночных сущностей (сущность, строки табличной части, запись регистра).
• Расширение ссылочных и составных типов виртуальных таблиц не соответствует протоколу OData версии 3.

Запрос, в котором будет выполняться расширение измерения виртуальной таблицы будет выглядеть следующим образом:

https://host/base/zone/odata/standard.odata/AccountingRegister_РегистрБухгалтерии/Balance?$expand=Организация

В результате исполнения этого запроса будет получен следующий результат:

<d:Организация_Key>УникальныйИдентификатор</d:Организация_Key>
					<d:Организация>
					…ДанныеОбъекта…
					</d:Организация>

При расширении составного типа поведение аналогично, за исключением того, что данные объекта будут представлены в элементе с суффиксом _Expanded.

• Сущность — в качестве сущности может выступать один из 4 групп объектов системы «1С:Предприятие»: объектные типы, наборы записей регистров, записи регистров и строки табличных частей объектных типов. Записи регистров и строки табличных объектных