При работе с протоколом OData используется специальная терминология.
Интерфейс OData общие принципы работы
При работе с протоколом OData используется специальная терминология.
При применении протокола используются следующие термины:
- Сущность – нечто, обладающее идентичностью. Сущность также обладает набором свойств. Некоторые свойства описывают ее идентичность, комбинация которых определяет ключ сущности. По этому ключу можно получить конкретную сущность.
- Набор сущностей – коллекция сущностей определенного типа.
- Составной тип – набор свойств, не обладающий идентичностью.
- Функция – набор некоторых операций, выполняемых на стороне сервера, возвращающий данные (не обязательно сущность или набор сущностей) и не приводящий к наблюдаемым побочным эффектам (изменениям данных). Функция обязательно связана с сущностью или набором сущностей.
- Действие – функция, которая может изменять данные.
- Сущность – в качестве сущности может выступать один из 4 групп объектов системы «1С:Предприятие»: объектные типы, наборы записей регистров, записи регистров и строки табличных частей объектных типов. Записи регистров и строки табличных объектных типов (как отдельные сущности) доступны только на чтение.
- Реквизиты объектов «1С:Предприятия» представляются как свойства сущностей. В некоторых случаях (например, реквизит объекта конфигурации составного типа) реквизит может быть представлен несколькими свойствами, одно из которых будет навигационным. Такое свойство содержит в качестве значения ссылку (URL) на сущность, описывающую объект «1С:Предприятия». Свойство, описывающее тип такого реквизита, называется диспетчеризационным. Название такого свойства завершается суффиксом _Type. Более подробное описание диспетчеризационного свойства приведено далее.
- Если реквизит объекта имеет ссылочный тип, то объект, на который ссылается такой реквизит, будет называться связанной сущностью.
ВАЖНО
Обращение к стандартному интерфейсу OData выполняется с помощью HTTP-запроса, выполнено по определенному URL. URL формируется специальным образом и состоит из следующих частей:
- 1. Адрес информационной базы;
- 2. Признак обращения к стандартному интерфейсу OData;
- 3. Имя ресурса, к которому выполняется обращение;
- 4. Параметры запроса обращения к ресурсу.
Само обращение выполняется с помощью HTTP-запроса определенного вида. При более подробном описании работы со стандартным интерфейсом OData вид запроса будет указываться отдельно.
Рассмотрим части URL более подробно:
Адрес информационной базы
Это обычный URL, по которому выполняется доступ, например, к информационной базе с помощью веб-клиента. Например, https://bp.42clouds.com/bp_base1/12345/.
Признак обращения к стандартному интерфейсу OData
В качестве такого признака выступает последовательность /odata/standard.odata.
Имя ресурса, к которому выполняется обращение
Особым образом сформированный идентификатор ресурса (возможно, с параметром) или предопределенные ресурсы. Например, $metadata, Catalog_Контрагент(guid’value’).
Параметры обращения к ресурсу
В качестве параметров обращения выступают параметры в виде, принятом для HTTP-запросов: ?ключ=значение&ключ2=значение2.
При обращении к ресурсу могут использоваться специальные ключевые слова, имеющие специальное назначение:
- $format – указывает, в каком формате необходимо получить данные. Если ключевое слово не указано, данные получаются в формате atom-xml.
- $format=atom – возвращает данные в формате atom-xml.
- $format=json – возвращает данные в формате json. Для указания того, что данные должны возвращаться в формате json, можно указать MIME-тип application/json в заголовке Accept HTTP-запроса на получение данных.
- $metadata – указывает, что требуется получить описание стандартного интерфейса OData.
- $filter – описывает отбор, применяемый при получении данных.
- $select – описывает перечень свойств сущности, которые получаются при обращении к стандартному интерфейсу OData.
После того, как сформирован URL необходимого ресурса, следует выполнить HTTP-запрос нужного вида. В зависимости от того, какая операция выполняется, используется соответствующий HTTP-метод:
- Получение данных – метод GET ;
- Создание объекта – метод POST ;
- Обновление данных:
- метод PATCH – в этом случае можно указывать только те свойств, которые необходимо обновить;
- метод PUT – в этом случае необходимо указывать все свойства сущности;
- Удаление данных – метод DELETE .
В результате выполнения запроса клиентское приложение получает ответ сервера, который кроме кода состояния может содержать различные данные, предоставленные сервером, в виде XML-документа.
При обращении к стандартному интерфейсу OData следует учитывать, что для указания значений некоторых типов необходимо соблюдать специальную нотацию:
- Тип УникальныйИдентификатор (тип Edm.Guid) указывается как guid’value’. Например: guid’8d04ce3c-6360-11e9-dd92-fa163e8ba11d’.
- Тип Дата (тип Edm.DateTime) указывается как datetime’yyyy-mm-ddThh:mm:ss’. Например: datetime’1945-05-09T06:00:00’.