С помощью стандартного интерфейса OData можно получать как списки сущностей, так и сами сущности. Эти способы получения данных отличаются URL, по которому происходит обращение к данным.
Интерфейс OData: способы получения данных
С помощью стандартного интерфейса OData можно получать как списки сущностей, так и сами сущности. Эти способы получения данных отличаются URL, по которому происходит обращение к данным.
Для получения списка сущностей URL выглядит следующим образом: https://host/base/zone/odata/standard.odata/Catalog_Товары. Это URL набора сущностей. Для получения сущности URL будет выглядеть следующим образом: https://host/base/zone/odata/standard.odata/Catalog_Товары(guid’value’). В общем виде такой адрес будет называться канонический URL экземпляра сущности. Разница заключается в том, что в первом случае получается вся таблица справочника товаров, а вот втором выбирается один объект, который описывается набором ключевых значений (в примере ключевое значение единственное – ссылка на объект). В конкретном случае набор ключевых полей, описывающих сущность, зависит от получаемой сущности. Если ключевых полей более одного, то они должны быть указаны все. Ключевые значения указываются парами Имя=Значение, разделенными запятыми. Если ключевое значение одно – имя ключа можно не указывать. Например, для получения значения курса валюты на конкретную дату необходимо выполнить GET-запрос со следующим URL:
https://host/base/zone/odata/standard.odata/InformationRegister_КурсыВалют(Period=datetime'2008 02 05T00:00:00', Валюта_Key=guid'9d5c4222 8c4c 11db a9b0 00055d49b45e')
При получении данных существует возможность указать, какие свойства сущности (или набора сущностей) необходимо получить с помощью стандартного интерфейса OData. Для этого существует ключевое слово $select, которое имеет несколько вариантов использования:
- Признак получения всех свойств.
В этом случае следует указать выражение вида $select=* или совсем не указывать выражение $select.
- Перечень конкретных свойств, которые необходимо получить.
В этом случае необходимо указать в выражении оператора $select перечень (через запятую) всех необходимых полей. При этом следует указывать суффиксы свойств, если это необходимо. Например, для получения значения ссылки на справочник и свойств Код и Артикул, для справочника Товары, необходимо использовать следующий URL:
https://host/base/zone/odata/standard.odata/Catalog_Товары?$select=Ref_Key, Код, Артикул
Для получения этих же полей для конкретного экземпляра сущности (с известным идентификатором) будет использоваться следующий URL:
https://host/base/zone/odata/standard.odata/Catalog_Товары(guid'value')?$select=Ref_Key, Код, Артикул
- Признак получения всех свойств, кроме табличных частей.
Для этого в выражении оператора $select необходимо указать значение **. При использовании следующего URL будут получены все документы РасходТовара со всеми реквизитами, кроме табличных частей:
https://host/base/zone/odata/standard.odata/Document_РасходТовара?$select=**
- Указание списка для получения связанных сущностей.
Допускается совместное использование параметров запроса $select и $expand. В этом случае с помощью параметра $expand указываются те свойства получаемой сущности, которые следует поместить в результат запроса. Конкретные значения получаемых (или разворачиваемых) свойств указывается с помощью параметра $select. Описание работа с параметром $expand более подробно см. здесь. В параметре $select, при использовании совместно с параметром $expand, поддерживается использование символов * и **. Указание символа * означает, что необходимо развернуть все реквизиты получаемого объекта. Указание символа ** означает, что необходимо развернуть все реквизиты получаемого объекта, кроме табличных частей.
https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Сертификат&$select=Сертификат/Дата https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Договор/Document_ДоговорНайма/Заявление&$select=Договор/Document_ДоговорНайма/Заявление/** https://host/base/zone/odata/standard.odata/InformationRegister_КурсыВалют?$expand=Валюта&$select=Период,Валюта/Код,Курс https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Сертификат&$select=Сертификат/*
ВАЖНО
Если в параметре $select одновременно указаны поля вида Объект/*, Объект/**, Объект/ИмяРеквизита, то они обрабатываются в следующем порядке:
- 1. Если указан символ *, то включаются все реквизиты;
- 2. Иначе, если указан символ **, то включаются все реквизиты, кроме табличных частей, иные указания игнорируются. Таким образом, если указано выражение вида $select=Объект/**, Объект/ТабличнаяЧасть, то табличная часть включена не будет.
- 3. Иначе, включаются все указанные реквизиты.
Имеется возможность получать данные, доступные «через точку». В этом случае к адресу, описывающему конкретную сущность, прибавляются имена свойств, идущие «через точку», но разделенные символом «/». При этом для стандартных реквизитов следует использовать только английские имена реквизитов. Например, для получения свойства Наименование реквизита Валюта документа РасходТовара, необходимо использовать GET-запрос со следующим URL: https://host/base/zone/odata/standard.odata/Document_РасходТовара(guid’value’)/Валюта/Description.