Протокол 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. Значение может быть статическое значение или выражение, которое может содержать путь к одному или нескольким свойствам аннотированного объекта. Термины аннотации определены в метаданных и имеют имя и тип. Набор связанных терминов в общем пространстве имен содержит словарь.

Service Model

Сервисы OData определяются с использованием общей модели данных. Сервис декларирует свою конкретную модель данных в машиночитаемой форме, позволяя различным клиентам взаимодействовать с собой четко определенным образом.

Служба OData предоставляет два четко определенных ресурса, которые описывают ее модель данных: сервисный документ и метаданные.

В сервисном документе перечислены наборы сущностей, функции и синглтоны, которые можно запрашивать. Клиенты могут использовать служебный документ для навигации по модели на основе hypermedia-driven fashion.

Метаданные описывают типы, наборы, функции и действия, понятные OData служба. Клиенты могут использовать документ метаданных, чтобы понять, как запрашивать и взаимодействовать с объектами в сервис. В дополнение к этим двум «фиксированным» ресурсам служба OData состоит из динамических ресурсов. URL для многие из этих ресурсов могут быть вычислены на основе информации в документе метаданных. См. Запрос данных и изменение данных для получения подробной информации.

OData services are defined using a common data model. The service advertises its concrete data model in a machine-readable form, allowing generic clients to interact with the service in a well-defined way. An OData service exposes two well-defined resources that describe its data model; a service document and a metadata document. The service document lists entity sets, functions, and singletons that can be retrieved. Clients can use the service document to navigate the model in a hypermedia-driven fashion. The metadata document describes the types, sets, functions and actions understood by the OData service. Clients can use the metadata document to understand how to query and interact with entities in the service. In addition to these two “fixed” resources, an OData service consists of dynamic resources. The URLs for many of these resources can be computed from the information in the metadata document. See Requesting Data and Data Modification for details.