Протокол OData v 4.01 (экстракт)
Обзор
Протокол OData - это протокол прикладного уровня для взаимодействия с данными через интерфейсы RESTful. Протокол поддерживает описание моделей данных, изменение и получение данных в соответствии с моделью.
Предоставляет:
- Метаданные: машиночитаемое описание модели данных, предоставляемой конкретным сервисом.
- Данные: наборы объектов данных и связи между ними.
- Запрос: обращение к сервису с набором фильтров или других преобразований для данных, с последующим возвращением результата.
- Редактирование: создание, обновление и удаление данных.
- Операции: вызов пользовательской логики
- Словари: добавление пользовательской семантики.
Протокол OData отличается от других подходов на основе веб-служб REST тем, что он обеспечивает единообразный способ описания как данных, так и модели данных. Это улучшает семантическую совместимость между системами и позволяет строить экосистемы.
С этой целью протокол OData следует следующим принципам разработки:
- Предпочтительны механизмы, которые работают с различными источниками данных. В частности, не предполагается реляционная модель данных.
- Расширяемость. Сервисы должны поддерживать расширение функциональности без изменения клиентов, не подозревающих об этих расширениях.
- Следование принципам REST.
- OData следует строить постепенно. Очень простой, совместимый сервис должен быть простым в построении, а дополнительная работа необходима только для поддержки дополнительных возможностей.
- Будь проще. Решайте общие задача и предусматривайте расширяемость, где это необходимо.
Data Model
Этот раздел предоставляет высокоуровневое описание Entity Data Model (EDM - абстрактную модель данных, используемую для описания данных, предоставляемых сервисами OData. Метаданные OData являются представлением модели данных сервиса(ов), предоставляемых клиенту.
Центральными понятиями в EDM являются сущности (entities), отношения (relationships), наборы сущностей (entity sets), действия(actions) и функции(functions).
Сущность (проще объект) - это экземпляры типов объектов (например, Клиент, Сотрудник и т.д.).
Типы сущностей называются структурированными типами с ключом. Они определяют именованные свойства и отношения этой сущности. Типы сущностей могут быть получены одним наследованием от других типов сущностей. Ключ типа сущности формируется из подмножества примитивных свойств (например, CustomerId, OrderId, LineId и т. Д.) типа объекта. (По человечески: сущность - это набор полей или структура. Некоторые поля могут быть помечены как ключевые, ключ формируется комбинацией ключевых полей. Прим. ключевые поля всегда должны присутствовать в запросах).
Комплексные типы - это структурированные типы без ключей, состоящие из набора свойств. На их экземпляры нельзя ссылаться вне их содержащей сущности. Комплексные типы обычно используется в качестве значений свойств в сущности или в качестве параметров операций. Свойства, объявленные как часть определения структурированного типа, являются объявленными (прим. статическими) свойствами. Экземпляры структурированных типов могут содержать дополнительные необъявленные динамические свойства. Динамическое свойство не может иметь то же имя, что и объявленное свойство. Сущности или комплексные типы, которые позволяют клиентам сохранять дополнительные необъявленные свойства называются открытыми типами.
Отношения от одного объекта к другому представлены как свойства навигации. Свойства навигации обычно определяются как часть типа объекта, но могут также появляться в экземплярах объекта как необъявленные свойства динамической навигации. Каждое отношение имеет кардинальность.
Перечисляемые типы - это именованные примитивные типы, значения которых являются именованными целочистенными константами с целым числом.
Определения типов - это именованные примитивные типы с фиксированными значениями фасетов, таких как максимальная длина или точность. Определения типов могут использоваться вместо примитивных типизированных свойств, например, в описании свойства.
Наборы сущностей - это именованные наборы сущностей (например, Клиенты - это набор сущностей, содержащий сущность Клиент). Ключ объекта однозначно идентифицирует объект в наборе объектов. Если несколько наборов сущностей используют один и тот же тип объекта, одна и та же комбинация значений ключей может появляться в нескольких наборах объектов и идентифицирует различные объекты, по одному на набор объектов, где появляется эта комбинация ключей. Каждая из этих сущностей имеет различный идентификатор объекта. Наборы сущностей обеспечивают точки входа в модель данных.
Функции - это операции, которые делают не имеют побочных эффектов и могут поддерживать дальнейшую композицию, например, с помощью дополнительных операций фильтрации, функции или действия. Такие операции позволяют выполнять пользовательскую логику для частей модели данных.
Действия - это операции, которые допускают побочные эффекты, такие как изменение данных и не может быть в дальнейшем составлен во избежание недетерминированного поведения.
Действия и функции либо связаны с типом, что позволяет им вызываться как членам экземпляра этого типа, либо не связаны, в этом случае они называются статическими операциями. Action imports and function imports позволяют вызывать несвязанные действия и функции из корня сервиса.
Синглтоны - это именованные сущности, к которым можно обращаться как к прямым потомкам контейнера сущностей. Синглтон также может быть членом набора сущностей.
Ресурс OData - это любой объект модели, к которому можно обратиться (набор сущностей, сущность, свойство или операция). Обратитесь к [OData-CSDLJSON] или [OData-CSDLXML] для получения дополнительной информации о данных объекта OData модель.
Аннотации
Элементы модели и экземпляра могут быть декорированы аннотациями. Аннотации могут использоваться для указания отдельного факта об элементе, например, доступен ли он только для чтения, или определить общую концепцию, такую как человек или фильм.
Применяемые аннотации состоят из term (имя применяемое к пространству имен аннотации), target (элемент модели или экземпляра, к которому применяется термин) и value. Значение может быть статическое значение или выражение, которое может содержать путь к одному или нескольким свойствам аннотированного объекта. Термины аннотации определены в метаданных и имеют имя и тип. Набор связанных терминов в общем пространстве имен содержит словарь.
