OData：開發RESTful API的標準

一、OData概述

OData（Open Data Protocol）是一種基於RESTful Web服務標準的協議，用於建立和使用Web應用程序和非Web應用程序之間的數據服務。它可以輕鬆地跨平台、跨語言和跨企業之間共享數據，支持數據的查詢、創建、更新和刪除操作。作為一種標準協議，OData有以下優點：

易於理解和實現，可以縮短服務開發時間和成本；
具有廣泛的兼容性，支持不同語言、不同框架之間的數據交換；
提供自描述能力和可擴展性，可以方便地集成到現有的系統中。

如果您需要開發RESTful API，並希望您的API能夠被多個語言和框架所支持，那麼OData是一個不錯的選擇。

二、OData架構

OData的核心概念包括：

服務端：數據服務的提供者，暴露OData服務端點，實現數據存儲、查詢、創建、更新和刪除操作；
客戶端：OData服務的消費者，根據服務端提供的元數據描述，使用RESTful API與服務端通信操作數據；
元數據：用於描述OData服務端暴露的資源（實體集、實體類型、屬性、關聯）以及這些資源的關係、實體集、實體類型、關聯之間的約束；
URI（Uniform Resource Identifier）：用於唯一標識OData服務端暴露的資源，支持多層次的查詢、操作和篩選。

因此，OData架構是一個基於RESTful風格的架構，它的核心是RESTful API和元數據，並且使用URI來描述資源的唯一標識。

三、OData基本操作

1. 查詢操作

查詢操作是OData最基本的操作，它可以按請求獲取服務端的數據資源。OData查詢語言包括以下關鍵詞：

$filter：用於篩選數據，通常用於條件判斷；
$orderby：用於對數據進行排序，通常用於分頁；
$top：用於指定返回數據的條數；
$skip：用於指定跳過的數據條數；
$select：用於指定返回的屬性，通常用於數據精簡。

以下是一個OData查詢請求的示例：

https://services.odata.org/V4/Northwind/Northwind.svc/Customers?$select=CustomerID,CompanyName&$filter=Country eq 'Germany'

上述查詢請求返回的結果將包含所有國家是德國的客戶，並且只返回客戶ID和公司名稱兩個屬性。

2. 創建和更新操作

OData服務端提供的創建和更新操作通常是基於HTTP協議中的POST、PUT和PATCH方法。其中：

POST方法用於創建新資源，通常請求的URI是資源的集合，請求正文包含要創建的新資源的屬性；
PUT方法用於替換完整的資源，通常請求的URI是資源的單個實例，請求正文包含完整的更新屬性；
PATCH方法用於更新資源的局部屬性，通常請求的URI是資源的單個實例，請求正文包含要更新的局部屬性。

以下是一個OData創建請求的示例：

POST https://services.odata.org/V4/Northwind/Northwind.svc/Categories HTTP/1.1
Content-Type: application/json

{
    "CategoryName": "Beverages",
    "Description": "Soft drinks, coffees, teas, beers, and ales"
}

上述創建請求將在分類實體集中創建一個新的分類，並設置分類名稱和描述屬性。

3. 刪除操作

刪除操作也是OData服務端提供的基本操作之一，它通常基於HTTP協議中的DELETE方法。DELETE方法用於刪除請求URI所標識的資源。例如：

DELETE https://services.odata.org/V4/Northwind/Northwind.svc/Categories(1) HTTP/1.1

上述請求將刪除分類實體集中ID為1的分類。

四、OData服務端開發

OData服務端開發通常包含以下步驟：

定義數據模型，並使用Entity Framework或自定義數據訪問層進行訪問；
創建OData控制器，並使用OData路由進行註冊和定義操作；
提供OData元數據描述，以描述實體、屬性、關聯、操作和約束；
配置OData服務端，包括數據存儲配置、數據服務配置和安全配置等。

以下是基於.NET Core框架實現的一個OData服務端開發示例：

1. 安裝OData Nuget包

dotnet add package Microsoft.AspNetCore.OData

2. 添加OData服務端配置信息

在Startup.cs文件的ConfigureServices方法中添加以下代碼：

services.AddOData();

3. 註冊OData路由

在Startup.cs文件的Configure方法中添加以下代碼：

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

4. 定義數據模型

在Models文件夾中添加數據模型（例如Category模型），並使用Entity Framework或自定義數據訪問層進行訪問。例如：

public class Category
{
    public int ID { get; set; }
    public string CategoryName { get; set; }
    public string Description { get; set; }
    public ICollection Products { get; set; }
}

5. 創建OData控制器

在Controllers文件夾中添加OData控制器（例如CategoryController），並定義GET、POST、PUT和DELETE等操作。例如：

[Produces("application/json")]
[EnableQuery]
public class CategoriesController : ODataController
{
    private readonly NorthwindContext _context;

    public CategoriesController(NorthwindContext context)
    {
        _context = context;
    }

    [HttpGet]
    [EnableQuery]
    public IEnumerable GetCategories()
    {
        return _context.Categories;
    }

    [HttpGet]
    [EnableQuery]
    public SingleResult GetCategory([FromODataUri] int key)
    {
        var result = _context.Categories.Where(c => c.ID == key);
        return SingleResult.Create(result);
    }

    [HttpPut]
    public async Task Put([FromODataUri] int key, [FromBody] Category category)
    {
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }
        if (key != category.ID)
        {
            return BadRequest();
        }
        _context.Entry(category).State = EntityState.Modified;
        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException)
        {
            if (!CategoryExists(key))
            {
                return NotFound();
            }
            else
            {
                throw;
            }
        }
        return NoContent();
    }

    [HttpPost]
    public async Task Post([FromBody] Category category)
    {
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }
        _context.Categories.Add(category);
        await _context.SaveChangesAsync();
        return Created(category);
    }

    [HttpDelete]
    public async Task Delete([FromODataUri] int key)
    {
        var category = await _context.Categories.FindAsync(key);
        if (category == null)
        {
            return NotFound();
        }
        _context.Categories.Remove(category);
        await _context.SaveChangesAsync();
        return NoContent();
    }

    private bool CategoryExists(int key)
    {
        return _context.Categories.Any(c => c.ID == key);
    }
}

6. 提供OData元數據描述

在Controllers文件夾中添加EdmModelBuilder類，提供OData元數據描述信息。例如：

public class EdmModelBuilder
{
    public static IEdmModel GetEdmModel()
    {
        var builder = new ODataConventionModelBuilder();
        builder.EntitySet("Categories").EntityType.HasKey(c => c.ID);
        return builder.GetEdmModel();
    }
}

以上示例展示了OData服務端開發的基本流程和代碼實現。

五、總結

OData作為一種基於RESTful Web服務的標準協議，提供了簡單、可靠、可擴展的數據交換方式，具有廣泛的兼容性和自描述能力。OData服務端開發可以通過.NET Core框架中的OData Nuget包和相關工具進行開發，實現數據模型定義、OData控制器定義、元數據描述和路由設置等操作。使用OData協議可以大大簡化服務端開發的複雜性，使數據交換變得更加容易。

原創文章，作者：小藍，如若轉載，請註明出處：https://www.506064.com/zh-hant/n/207223.html