Рубрики
Без рубрики

Руководство по протоколу OData

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

Автор оригинала: Philippe Sevestre.

1. Введение

В этом учебнике мы изумим OData , стандартный протокол, который позволяет легко получить доступ к наборам данных с помощью API RESTFul.

2. Что такое OData?

OData является стандартом OASIS и ISO/IEC для доступа к данным с помощью API RESTful. Таким образом, он позволяет потребителю обнаружить и перемещаться по наборам данных с помощью стандартных вызовов HTTP.

Например, мы можем получить доступ к одному из общедоступные услуги OData с простым локон одной линии :

curl -s https://services.odata.org/V2/Northwind/Northwind.svc/Regions


    Regions
    https://services.odata.org/V2/Northwind/Northwind.svc/Regions
... rest of xml response omitted

На момент написания этой статьи протокол OData находится на 4-й версии – 4.01, если быть более точным. OData V4 достигла стандартного уровня OASIS в 2014 году, но имеет более долгую историю. Мы можем проследить его корни в проекте Microsoft под названием Astoria, который был переименован в ADO.Net в 2007 году . оригинальный блог запись объявление об этом проекте по-прежнему доступно в блоге OData корпорации Майкрософт.

Наличие стандартного протокола для доступа к набору данных приносит некоторые преимущества по отношению к стандартным API, таким как JDBC или ODBC. Как потребитель уровня конечных пользователей, мы можем использовать популярные инструменты, такие как Excel для получения данных от любого совместимого поставщика. Программированию также способствует большое количество доступных клиентских библиотек REST.

Как поставщики, принятие OData также имеет преимущества: как только мы создали совместимый сервис, мы можем сосредоточиться на предоставлении ценных наборов данных, которые конечные пользователи могут потреблять с помощью инструментов по своему выбору. Поскольку это протокол на основе HTTP, мы также можем использовать такие аспекты, как механизмы безопасности, мониторинг и лесозаготовки.

Эти характеристики сделали OData популярным выбором государственных учреждений при внедрении служб общественных данных, так как мы можем проверить взглянув на этот каталог .

3. Концепции OData

В основе протокола OData находится концепция модели данных сущности – или EDM для краткости. EDM описывает данные, выставленные поставщиком OData через метаданный документ, содержащий ряд мета-сущностей:

  • Тип сущности и ее свойства (например, Лицо , Клиентская , Заказ и т.д.) и ключи
  • Отношения между сущностями
  • Сложные типы, используемые для описания структурированных типов, встроенных в сущности (скажем, тип адреса, который является частью Клиентская тип)
  • Наборы сущностей, которые объединяют сущности данного типа

Спецификация предписывает, что этот документ метаданных должен быть доступен в стандартном месте $metadata на корневом URL-адресе, используемом для доступа к службе. Например, если у нас есть услуга OData, доступная на http://example.org/odata.svc/ , то его метаданные документ будет доступен по http://example.org/odata.svc/$metadata .

Возвращенный документ содержит кучу XML, описывающих схемы, поддерживаемые этим сервером:



    
    ... schema elements omitted

Давайте разорвем этот документ на его основные разделы.

Элемент верхнего уровня, <:Edmx> может иметь только одного ребенка, <:DataServices> элемент . Важно заметить здесь пространство имен URI, поскольку это позволяет нам определить, какую версию OData использует сервер. В этом случае пространство имен указывает на то, что у нас есть сервер OData V2, который использует идентификаторы Майкрософт.

Службы данных элемент может иметь один или несколько Схема элементы, каждый из которых описывает доступный набор данных. Так как полное описание доступных элементов в Схема выходит за рамки этой статьи, мы сосредоточимся на наиболее важных из них: EntityTypes, Ассоциации, и ЛицаСети .

3.1. Элемент EntityType

Этот элемент определяет доступные свойства данной сущности, включая ее основной ключ. Он также может содержать информацию о взаимоотношениях с другими типами схем и, глядя на пример – Кармейкер – Мы сможем увидеть, что он не сильно отличается от описаний, найденных в других технологиях ORM, таких как JPA:

Вот, наш Кармейкер имеет только два свойства – Id и Название – и ассоциация с другим EntityType . Ключевые ub-элемент определяет основной ключ сущности, чтобы быть его Id собственности, и каждый Недвижимость элемент содержит данные об свойстве сущности, такие как его имя, тип или недействительность.

НавигацияПропертия это особый вид свойства, описывая «точку доступа» к связанной сущности.

3.2. Элемент ассоциации

Ассоциация элемент описывает связь между двумя сущностями, которая включает в себя множественность на каждом конце и факультативно ограничение целостности референта:

Вот, Ассоциация элемент определяет отношения «один к многим» между Кармодель и Кармейкер организаций, где первая выступает в качестве зависимой стороны.

3.3. Элемент EntitySet

Окончательная схема концепции мы будем изучать это EntitySet элемент, представляющий собой набор сущностей данного типа. Хотя это легко думать, что они аналогичны таблице – и во многих случаях, они просто, что – лучшая аналогия является то, что зрения. Причина этого в том, что мы можем иметь несколько EntitySet элементы для одного и того же EntityType , каждый из которых представляет различные подмножества имеющихся данных.

EntityContainer элемент, который является элементом схемы верхнего уровня, группы всех доступных EntitySet секунда:

В нашем простом примере у нас есть только два EntitySet s, но мы могли бы также добавить дополнительные представления, такие как ИностранныеcarMakers или ИсторическиеCarMakers .

4. URL-адреса и методы OData

Для доступа к данным, выставленным службой OData, мы используем обычные глаголы HTTP:

  • GET возвращает одну или несколько сущностей
  • POST добавляет новую сущность к существующему Набор сущностей
  • PUT заменяет данное лицо
  • PATCH заменяет определенные свойства данной сущности
  • DELETE удаляет данное лицо

Все эти операции требуют ресурсного пути для принятий деятельности. Путь ресурсов может определить набор сущностей, сущность или даже свойство внутри сущности.

Давайте рассмотрим пример URL, используемый для доступа к нашей предыдущей службе OData:

http://example.org/odata/CarMakers

Первая часть этого URL, начиная с протокола до odata/ сегмент пути, известен как корневой URL-адрес службы и одинаков для всех ресурсных путей этой службы. Так как корень службы всегда одинаков, мы заменим его в следующих образцах URL эллипсисом (“…”) .

Автопроизводители , в данном случае, относится к одному из заявленных ЛицаСети метаданных службы. Мы можем использовать обычный браузер для доступа к этому URL, который затем должен вернуть документ, содержащий все существующие сущности этого типа:



    http://localhost:8080/odata/CarMakers
    CarMakers
    2019-04-06T17:51:33.588-03:00
    
        
    
    
    
      http://localhost:8080/odata/CarMakers(1L)
      CarMakers
      2019-04-06T17:51:33.589-03:00
      
      
      
        
            
                1
                Special Motors
            
        
      
  ... other entries omitted

Возвращенный документ содержит входные элемент для каждого Кармейкер пример.

Давайте подробнее рассмотрим, какая информация у нас есть:

  • id : ссылка на эту конкретную сущность
  • название/автор/обновленная : метаданные об этой записи
  • ссылка элементы: Ссылки, используемые для указывать на ресурс, используемый для редактирования сущности ( rel'”edit” ) или связанных с ними сущностей. В этом случае у нас есть ссылка, которая ведет нас к набору Кармодель сущностей, связанных с этим конкретным Кармейкер .
  • содержание : стоимость имущества Кармодель сущность

Важным моментом, который следует заметить здесь, является использование пары значений ключей для идентификации конкретной сущности в наборе сущностей. В нашем примере ключ числов, поэтому такой ресурсный путь, как CarMaker (1L) относится к сущности с первичным ключевым значением, равным 1 – ” L ” здесь просто обозначает долго значение и может быть опущено.

5. Параметры запроса

Мы можем передать параметры запроса на URL-адрес ресурса, чтобы изменить ряд аспектов возвращенных данных, например ограничить размер возвращенного набора или его заказ. Спецификация OData определяет богатый набор опций, но здесь мы сосредоточимся на наиболее распространенных.

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

5.1. $top и $skip

Мы можем перемещаться по большому набору данных с помощью $top $skip параметры запроса:

.../CarMakers?$top=10&$skip=10

$top сообщает службе, что мы хотим только первые 10 записей Автопроизводители набор сущностей. $skip, который применяется до $top, говорит серверу пропустить первые 10 записей.

Обычно полезно знать размер данного Набор объектов и для этого мы можем использовать $count суб-ресурс:

.../CarMakers/$count

Этот ресурс производит текст/обычная документ, содержащий размер соответствующего набора. Здесь мы должны обратить внимание на конкретную версию OData, поддерживаемую поставщиком. В то время как OData V2 $count как суб-ресурс из коллекции, V4 позволяет использовать его в качестве параметра запроса. В этом случае $count является Boolean, поэтому мы должны изменить URL соответственно:

.../CarMakers?$count=true

5.2. $filter

Мы используем $filter опция запроса ограничить возвращенные объекты из данного Набор объектов тем, кто соответствует данным критериям. Значение для $filter является логическим выражением, которое поддерживает основных операторов, группировку и ряд полезных функций. Например, давайте построим запрос, который возвращает все Кармейкер случаи, когда его Название атрибут начинается с буквы ‘B’:

.../CarMakers?$filter=startswith(Name,'B')

Теперь давайте объединим несколько логических операторов для поиска Кармоделс конкретного Год и Создатель :

.../CarModels?$filter=Year eq 2008 and CarMakerDetails/Name eq 'BWM'

Здесь мы использовали оператора по обеспечению равенства eq указывать значения свойств. Мы также можем увидеть, как использовать свойства из связанной сущности в выражении.

5.3. $expand

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

Используя наш выборочных доменов, давайте построим URL-адрес, который возвращает данные из данной модели и его создатель, таким образом избегая дополнительной поездки туда и обратно на сервер:

.../CarModels(1L)?$expand=CarMakerDetails

Возвращенный документ теперь включает в себя Кармейкер данные как часть связанной сущности:



    http://example.org/odata/CarModels(1L)
    CarModels
    2019-04-07T11:33:38.467-03:00
    
    
    
        
            
                http://example.org/odata/CarMakers(1L)
                CarMakers
                2019-04-07T11:33:38.492-03:00
                
                
                
                
                    
                        1
                        Special Motors
                    
                
            
        
    
    
        
            1
            1
            Muze
            SM001
            2018

5.4. $select

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

Давайте использовать эту опцию в запросе, который возвращает только Название и Ску свойства:

.../CarModels(1L)?$select=Name,Sku

Полученный документ теперь имеет только запрошенные свойства:

... xml omitted
    
        
            Muze
            SM001
        
    
... xml omitted

Мы также видим, что даже связанные сущности были опущены. Для того, чтобы включить их, мы должны включить название отношения в $select выбор.

5.5. $orderBy

$orderBy опция работает в значительной степени, как его аналог S’L. Мы используем его для порядок, в котором мы хотим, чтобы сервер вернул данный набор сущностей. В более простой форме его значением является лишь список имен свойств выбранной организации, дополнительно информирующий направление заказа:

.../CarModels?$orderBy=Name asc,Sku desc

Этот запрос приведет к списку Кармоделс приказал их имена и SKUs, в восходящих и нисходящих направлениях, соответственно.

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

5.6. $format

Эта опция определяет формат представления данных, который должен использовать сервер, который имеет приоритет над любым заголовком http-переговоров по контенту, например Примите . Его значение должно быть полным MIME-Type или формат-специфической короткой формой.

Например, мы можем использовать Json в качестве аббревиатуры для приложение/json :

.../CarModels?$format=json

Этот URL-адрес поручает нашему сервису возвращать данные в формате JSON, а не XML, как мы видели раньше. Когда эта опция не присутствует, сервер будет использовать значение Примите заголовок, если присутствует. Когда ни один из них не доступен, сервер может свободно выбирать любое представительство – обычно XML или JSON.

Что касается JSON в частности, это принципиально схематично. Тем не менее, OData 4.01 определяет схема JSON для конечных точек метаданных тоже. Это означает, что теперь мы можем писать клиентам, которые могут полностью избавиться от обработки XML, если они захотят сделать это.

6. Заключение

В этом кратком введении к OData, мы рассмотрели его основные семантики и как выполнять простую навигацию набора данных. Наша последующая статья будет продолжаться там, где мы уехали и идти прямо в библиотеку Olingo. Затем мы увидим, как реализовать примеры служб с помощью этой библиотеки.

Примеры кода, как всегда, доступны более чем на GitHub.