.NET Core開發日誌——OData

OData .NETCore · 發表 2019-02-10 21:55:00

摘要：簡述 OData，即Open Data Protocol，是由微軟在2007年推出的一款開放協議，旨在通過簡單、標準的方式建立和使用查詢式及互動式RESTful API。類庫在.NET Core中想要使用OData功能的話需要新增Microsoft.AspNetCor...

簡述

OData，即Open Data Protocol，是由微軟在2007年推出的一款開放協議，旨在通過簡單、標準的方式建立和使用查詢式及互動式RESTful API。

類庫

在.NET Core中想要使用OData功能的話需要新增Microsoft.AspNetCore.OData 包。

dotnet add package Microsoft.AspNetCore.OData

準備模型類

public class Address
{
public string City { get; set; }
public string Street { get; set; }
}
public enum Category
{
Book,
Magazine,
EBook
}
public class Press
{
public int Id { get; set; }
public string Name { get; set; }
public string Email { get; set; }
public Category Category { get; set; }
}
public class Book
{
public int Id { get; set; }
public string ISBN { get; set; }
public string Title { get; set; }
public string Author { get; set; }
public decimal Price { get; set; }
public Address Address { get; set; }
public Press Press { get; set; }
}

建立Edm模型

OData使用EDM，即Entity Data Model來描述資料的結構。在Startup檔案中新增建立方法。

private static IEdmModel GetEdmModel()
{
var builder = new ODataConventionModelBuilder();
builder.EntitySet<Book>("Books");
builder.EntitySet<Press>("Presses");
return builder.GetEdmModel();
}

註冊OData服務

在Startup檔案的ConfigureServices方法裡註冊OData服務。

services.AddOData();
services.AddMvc(options =>
{
options.EnableEndpointRouting = false;
}).SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

這裡要注意的是在.NET Core 2.2裡，預設已經有終結點，所以要使用OData的終結點的話需要將預設選項禁用掉。

註冊OData終結點

同樣在Startup檔案裡，在其Configure方法內將原來的註冊路由內容改為註冊OData的終結點。

app.UseMvc(b =>
{
b.MapODataServiceRoute("odata", "odata", GetEdmModel());
});

顯示元資料

執行程式後訪問https://localhost:5001/odata/$metadata 地址，可以看到所有可用模型的元資料。

<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
<edmx:DataServices>
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
<EntityType Name="Book">
<Key>
<PropertyRef Name="Id"/>
</Key>
<Property Name="Id" Type="Edm.Int32" Nullable="false"/>
<Property Name="ISBN" Type="Edm.String"/>
<Property Name="Title" Type="Edm.String"/>
<Property Name="Author" Type="Edm.String"/>
<Property Name="Price" Type="Edm.Decimal" Nullable="false"/>
<Property Name="Address" Type="Default.Address"/>
<NavigationProperty Name="Press" Type="Default.Press"/>
</EntityType>
<EntityType Name="Press">
<Key>
<PropertyRef Name="Id"/>
</Key>
<Property Name="Id" Type="Edm.Int32" Nullable="false"/>
<Property Name="Name" Type="Edm.String"/>
<Property Name="Email" Type="Edm.String"/>
<Property Name="Category" Type="Default.Category" Nullable="false"/>
</EntityType>
<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>
<EntityContainer Name="Container">
<EntitySet Name="Books" EntityType="Default.Book">
<NavigationPropertyBinding Path="Press" Target="Presses"/>
</EntitySet>
<EntitySet Name="Presses" EntityType="Default.Press"/>
</EntityContainer>
</Schema>
</edmx:DataServices>
</edmx:Edmx>

建立Controller

本文例項中不考慮資料庫的操作，故而使用hard code方式構建必要的模型物件。

public class BooksController : ODataController
{
private static IList<Book> Books {get; set;}
public BooksController()
{
Books = new List<Book>
{
new Book
{
Id = 1,
ISBN = "111-0-321-56789-1",
Title = "Calculus",
Price = 66.6m,
Address = new Address
{
City = "Shanghai",
Street = "Beijin Xi Road"
},
Press = new Press
{
Id = 1,
Name = "Shanghai Tongji",
Category = Category.Book
}
},
new Book
{
Id = 2,
ISBN = "222-2-654-00000-2",
Title = "Linear Algebra",
Price = 53.2m,
Address = new Address
{
City = "Shanghai",
Street = "Beijin Dong Road"
},
Press = new Press
{
Id = 2,
Name = "Shanghai Fudan",
Category = Category.EBook
}
}
};
}

[EnableQuery]
public IActionResult Get()
{
return Ok(Books);
}

[EnableQuery]
public IActionResult Get(int key)
{
return Ok(Books.FirstOrDefault(b => b.Id == key));
}
}

EnableQuery特性在需要高階查詢的場景時必須新增。

查詢

加入Controller之後，訪問https://localhost:5001/odata/Books 地址，可得到所有Book資料。

{
"@odata.context": "https://localhost:5001/odata/$metadata#Books",
"value": [
{
"Id": 1,
"ISBN": "111-0-321-56789-1",
"Title": "Calculus",
"Author": null,
"Price": 66.6,
"Address": {
"City": "Shanghai",
"Street": "Beijin Xi Road"
}
},
{
"Id": 2,
"ISBN": "222-2-654-00000-2",
"Title": "Linear Algebra",
"Author": null,
"Price": 53.2,
"Address": {
"City": "Shanghai",
"Street": "Beijin Dong Road"
}
}
]
}

訪問https://localhost:5001/odata/Books(1) 地址，可得到key值為1的Book資料。

{
"@odata.context": "https://localhost:5001/odata/$metadata#Books/$entity",
"Id": 1,
"ISBN": "111-0-321-56789-1",
"Title": "Calculus",
"Author": null,
"Price": 66.6,
"Address": {
"City": "Shanghai",
"Street": "Beijin Xi Road"
}
}

高階查詢

如果想要使用OData查詢的高階功能，可以在註冊終結點時額外加上相應的配置。

app.UseMvc(b =>
{
b.Select().Expand().Filter().OrderBy().MaxTop(100).Count();
b.MapODataServiceRoute("odata", "odata", GetEdmModel());
});

訪問網址時加上所需的查詢內容：

https://localhost:5001/odata/Books?$select=Id,Title

{
"@odata.context": "https://localhost:5001/odata/$metadata#Books(Id,Title)",
"value": [
{
"Id": 1,
"Title": "Calculus"
},
{
"Id": 2,
"Title": "Linear Algebra"
}
]
}

如果想要按特定條件過濾資料內容的話也很容易：

https://localhost:5001/odata/Books?$filter=Price%20le%2060

{
"@odata.context": "https://localhost:5001/odata/$metadata#Books",
"value": [
{
"Id": 2,
"ISBN": "222-2-654-00000-2",
"Title": "Linear Algebra",
"Author": null,
"Price": 53.2,
"Address": {
"City": "Shanghai",
"Street": "Beijin Dong Road"
}
}
]
}

總結

不難看出，OData的真正魅力在於其對那些高階查詢功能的支援，所以在建立RESTful API時，不妨考慮使用OData，這樣應該能減少許多不必要的程式碼工作。