Открытие типов в OData версии 4 с веб-API ASP.NET

  • Статья

от Майкрософт

В OData версии 4 открытый тип — это структурированный тип, содержащий динамические свойства в дополнение к любым свойствам, объявленным в определении типа. Открытые типы позволяют обеспечить гибкость моделей данных. В этом руководстве показано, как использовать открытые типы в веб-API ASP.NET OData.

В этом руководстве предполагается, что вы уже знаете, как создать конечную точку OData в веб-API ASP.NET. В противном случае сначала прочитайте статью Создание конечной точки OData версии 4 .

Версии программного обеспечения, используемые в этом руководстве

  • Веб-API OData 5.3
  • OData v4

Во-первых, некоторые термины OData:

  • Тип сущности: структурированный тип с ключом.
  • Сложный тип: структурированный тип без ключа.
  • Открытый тип: тип с динамическими свойствами. Типы сущностей и сложные типы могут быть открыты.

Значение динамического свойства может быть примитивным, сложным типом или типом перечисления; или коллекция любого из этих типов. Дополнительные сведения об открытых типах см. в спецификации OData версии 4.

Установка веб-библиотек OData

Используйте диспетчер пакетов NuGet для установки последних версий библиотек OData веб-API. В окне Консоль диспетчера пакетов

Install-Package Microsoft.AspNet.OData
Install-Package Microsoft.AspNet.WebApi.OData

Определение типов СРЕДЫ CLR

Начните с определения моделей EDM как типов CLR.

public enum Category
{
    Book,
    Magazine,
    EBook
}

public class Address
{
    public string City { get; set; }
    public string Street { get; set; }
}

public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; }
    public Address Address { get; set; }
}

public class Press
{
    public string Name { get; set; }
    public string Email { get; set; }
    public Category Category { get; set; }
    public IDictionary<string, object> DynamicProperties { get; set; }
}

public class Book
{
    [Key]
    public string ISBN { get; set; }
    public string Title { get; set; }
    public Press Press { get; set; }
    public IDictionary<string, object> Properties { get; set; }
}

При создании модели EDM

  • Category — это тип перечисления.
  • Address — сложный тип. (У него нет ключа, поэтому он не является типом сущности.)
  • Customer — это тип сущности. (У него есть ключ.)
  • Press — это открытый сложный тип.
  • Book — это открытый тип сущности.

Чтобы создать открытый тип, тип CLR должен иметь свойство типа IDictionary<string, object>, которое содержит динамические свойства.

Создание модели EDM

Если вы используете ODataConventionModelBuilder для создания EDM, Press и Book автоматически добавляются как открытые типы в зависимости от наличия IDictionary<string, object> свойства.

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        ODataConventionModelBuilder builder = new ODataConventionModelBuilder();
        builder.EntitySet<Book>("Books");
        builder.EntitySet<Customer>("Customers");
        var model = builder.GetEdmModel();

        config.MapODataServiceRoute(
            routeName: "ODataRoute",
            routePrefix: null,
            model: model);

    }
}

Вы также можете создать EDM явным образом с помощью ODataModelBuilder.

ODataModelBuilder builder = new ODataModelBuilder();

ComplexTypeConfiguration<Press> pressType = builder.ComplexType<Press>();
pressType.Property(c => c.Name);
// ...
pressType.HasDynamicProperties(c => c.DynamicProperties);

EntityTypeConfiguration<Book> bookType = builder.EntityType<Book>();
bookType.HasKey(c => c.ISBN);
bookType.Property(c => c.Title);
// ...
bookType.ComplexProperty(c => c.Press);
bookType.HasDynamicProperties(c => c.Properties);

// ...
builder.EntitySet<Book>("Books");
IEdmModel model = builder.GetEdmModel();

Добавление контроллера OData

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

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;
using System.Web.OData;

namespace MyApp.Controllers
{
    public class BooksController : ODataController
    {
        private IList<Book> _books = new List<Book>
        {
            new Book
            {
                ISBN = "978-0-7356-8383-9",
                Title = "SignalR Programming in Microsoft ASP.NET",
                Press = new Press
                {
                    Name = "Microsoft Press",
                    Category = Category.Book
                }
            },

            new Book
            {
                ISBN = "978-0-7356-7942-9",
                Title = "Microsoft Azure SQL Database Step by Step",
                Press = new Press
                {
                    Name = "Microsoft Press",
                    Category = Category.EBook,
                    DynamicProperties = new Dictionary<string, object>
                    {
                        { "Blog", "https://blogs.msdn.com/b/microsoft_press/" },
                        { "Address", new Address { 
                              City = "Redmond", Street = "One Microsoft Way" }
                        }
                    }
                },
                Properties = new Dictionary<string, object>
                {
                    { "Published", new DateTimeOffset(2014, 7, 3, 0, 0, 0, 0, new TimeSpan(0))},
                    { "Authors", new [] { "Leonard G. Lobel", "Eric D. Boyd" }},
                    { "OtherCategories", new [] {Category.Book, Category.Magazine}}
                }
            }
        };

        [EnableQuery]
        public IQueryable<Book> Get()
        {
            return _books.AsQueryable();
        }

        public IHttpActionResult Get([FromODataUri]string key)
        {
            Book book = _books.FirstOrDefault(e => e.ISBN == key);
            if (book == null)
            {
                return NotFound();
            }

            return Ok(book);
        }

        public IHttpActionResult Post(Book book)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            } 
            // For this sample, we aren't enforcing unique keys.
            _books.Add(book);
            return Created(book);
        }
    }
}

Обратите внимание, что первый Book экземпляр не имеет динамических свойств. Второй Book экземпляр имеет следующие динамические свойства:

  • "Опубликовано": примитивный тип
  • "Авторы": коллекция примитивных типов
  • "OtherCategories": коллекция типов перечисления.

Кроме того, Press свойство этого Book экземпляра имеет следующие динамические свойства:

  • "Блог": примитивный тип
  • "Address": сложный тип

Запрос метаданных

Чтобы получить документ метаданных OData, отправьте запрос GET по адресу ~/$metadata. Текст ответа должен выглядеть примерно так:

<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
  <edmx:DataServices>
    <Schema Namespace="MyApp.Models" xmlns="http://docs.oasis-open.org/odata/ns/edm">
      <EntityType Name="Book" OpenType="true">
        <Key>
          <PropertyRef Name="ISBN" />
        </Key>
        <Property Name="ISBN" Type="Edm.String" Nullable="false" />
        <Property Name="Title" Type="Edm.String" />
        <Property Name="Press" Type="MyApp.Models.Press" />
      </EntityType>
      <EntityType Name="Customer">
        <Key>
          <PropertyRef Name="Id" />
        </Key>
        <Property Name="Id" Type="Edm.Int32" Nullable="false" />
        <Property Name="Name" Type="Edm.String" />
        <Property Name="Address" Type="MyApp.Models.Address" />
      </EntityType>
      <ComplexType Name="Press" OpenType="true">
        <Property Name="Name" Type="Edm.String" />
        <Property Name="Category" Type="MyApp.Models.Category" Nullable="false" />
      </ComplexType>
      <ComplexType Name="Address">
        <Property Name="City" Type="Edm.String" />
        <Property Name="Street" Type="Edm.String" />
      </ComplexType>
      <EnumType Name="Category">
        <Member Name="Book" Value="0" />
        <Member Name="Magazine" Value="1" />
        <Member Name="EBook" Value="2" />
      </EnumType>
    </Schema>
    <Schema Namespace="Default" xmlns="http://docs.oasis-open.org/odata/ns/edm">
      <EntityContainer Name="Container">
        <EntitySet Name="Books" EntityType="MyApp.Models.Book" />
        <EntitySet Name="Customers" EntityType="MyApp.Models.Customer" />
      </EntityContainer>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>

В документе метаданных видно, что:

  • Book Для типов и Press значение атрибута OpenType равно true. Customer Типы и Address не имеют этого атрибута.
  • Тип Book сущности имеет три объявленных свойства: ISBN, Title и Press. Метаданные OData не включают Book.Properties свойство из класса CLR.
  • Аналогичным образом сложный Press тип имеет только два объявленных свойства: Name и Category. Метаданные не включают Press.DynamicProperties свойство из класса CLR.

Запрос сущности

Чтобы получить книгу с ISBN, равной "978-0-7356-7942-9", отправьте запрос GET по .~/Books('978-0-7356-7942-9') Текст ответа должен выглядеть примерно так: (С отступом, чтобы сделать его более удобочитаемым.)

{
  "@odata.context":"http://localhost:37141/$metadata#Books/$entity",
    "ISBN":"978-0-7356-7942-9",
    "Title":"Microsoft Azure SQL Database Step by Step",
    "Press":{
      "Name":"Microsoft Press",
      "Category":"EBook",
      "Blog":"https://blogs.msdn.com/b/microsoft_press/",
      "Address":{
        "@odata.type":"#MyApp.Models.Address",
        "City":"Redmond",
        "Street":"One Microsoft Way"
      }
  },
  "Published":"2014-07-03T00:00:00Z",
  "Authors@odata.type":"#Collection(String)",
  "Authors":[
    "Leonard G. Lobel","Eric D. Boyd"
  ],
  "OtherCategories@odata.type":"#Collection(MyApp.Models.Category)",
  "OtherCategories":[
    "Book","Magazine"
  ]
}

Обратите внимание, что динамические свойства включены в список объявленных свойств.

POST сущности

Чтобы добавить сущность Book, отправьте запрос POST в ~/Books. Клиент может задавать динамические свойства в полезных данных запроса.

Ниже приведен пример запроса. Обратите внимание на свойства Price и Published.

POST http://localhost:37141/Books HTTP/1.1
User-Agent: Fiddler
Host: localhost:37141
Content-Type: application/json
Content-Length: 191

{
  "ISBN":"978-0-7356-8383-9","Title":"Programming Microsoft ASP.NET MVC","Press":{
  "Name":"Microsoft Press","Category":"Book"
   }, "Price": 49.99, "Published":"2014-02-15T00:00:00Z"
}

Если вы задали точку останова в методе контроллера, вы увидите, что веб-API добавил эти свойства в словарь Properties .

Снимок экрана: код, который отправляет запрос POST, где выделена часть кода

Дополнительные ресурсы

Пример открытого типа OData