5.3 ABP分布式服务 - 集成OData

5.3.1 简介

开放数据协议(Open Data Protocol,缩写OData)是一种描述如何创建和访问Restful服务。你可以在Abp中使用OData,只需要通过Nuget来安装Abp.Web.Api.OData.

5.3.2 安装

1. 使用Nuget安装

首先应该使用Nuget安装Abp.Web.Api.OData到我们的WebApi项目:

Install-PackageAbp.Web.Api.Odata

2. 配置依赖模块

将AbpWebApiODataModule添加到被依赖的模块上,如下所示:

[DependsOn(typeof(AbpWebApiODataModule))]
public class MyProjectWebApiModule : AbpModule
{
    ...
}

了解模块依赖请参考模块系统

3. 配置实体

为了使实体能够作为一个OData源,我们应该在模块的 PreInitialize 方法中对实体进行OData配置。如下所示:

[DependsOn(typeof(AbpWebApiODataModule))]
public class MyProjectWebApiModule : AbpModule
{
    public override void PreInitialize()
    {
        var builder = Configuration.Modules.AbpWebApiOData().ODataModelBuilder;

        //Configure your entities here...
        builder.EntitySet<Person>("Persons");
    }

    ...
}

在这里,我们得到了ODataModelBuilder的引用并且配置了Person实体。类似的你可以使用 EntitySet 方法来添加其他实体。更多信息请参考OData文档

4. 创建控制器

Abp.Web.Api.OData 中包含了基类:AbpODataEntityController(扩展自标准的ODataController),为了能够更容易的创建你自己的控制器,你应该继承该基类。如下所示:

public class PersonsController : AbpODataEntityController<Person>
{
    public PersonsController(IRepository<Person> repository)
        : base(repository)
    {
    }
}

AbpODataEntityController 中的所有方法都是virtual,所以你可以重写 **Get, Post, Put, Patch, Delete ** 和其它的Actions来实现你自己的逻辑。

6. 配置

Abp.Web.Api.OData使用约定的配置自动的调用HttpConfiguration.MapODataServiceRoute方法。如果你需要,你可以设置Configuration.Modules.AbpWebApiOData().MapAction 来映射你自己的OData路由。

5.3.3 示例

这里有一些请求上面已定义的Controller的示例。假设你的应用的URL是:http://localhost:61842。下面将展示一些基础的例子。

1. 获取实体列表

取得所有的people。

Request
 GET  http://localhost:61842/odata/Persons
Response
{
  "@odata.context":"http://localhost:61842/odata/$metadata#Persons","value":[
    {
      "Name":"Douglas Adams","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":1
    },{
      "Name":"John Nash","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":2
    }
  ]
}

2. 获取单个实体

根据Id = 2来获取person

Request
 GET http://localhost:61842/odata/Persons(2)
Response
{
  "@odata.context":"http://localhost:61842/odata/$metadata#Persons/$entity","Name":"John Nash","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":2
}

3. 根据导航属性获取单个实体

根据Id = 1来获取person并且包括他的电话信息

Request
GET http://localhost:61842/odata/Persons(1)?$expand=Phones
Response
{
  "@odata.context":"http://localhost:61842/odata/$metadata#Persons/$entity","Name":"Douglas Adams","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":1,"Phones":[
    {
      "PersonId":1,"Type":"Mobile","Number":"4242424242","CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":1
    },{
      "PersonId":1,"Type":"Mobile","Number":"2424242424","CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":2
    }
  ]
}

4. 查询

在这里我们将使用一个高级查询,在过滤,排序后取得排在最前面的2条数据。

Request
GET http://localhost:61842/odata/Persons?$filter=Name eq 'Douglas Adams'&$orderby=CreationTime&$top=2
Response
{
  "@odata.context":"http://localhost:61842/odata/$metadata#Persons","value":[
    {
      "Name":"Douglas Adams","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2015-11-07T20:12:39.363+03:00","CreatorUserId":null,"Id":1
    },{
      "Name":"Douglas Adams","IsDeleted":false,"DeleterUserId":null,"DeletionTime":null,"LastModificationTime":null,"LastModifierUserId":null,"CreationTime":"2016-01-12T20:29:03+02:00","CreatorUserId":null,"Id":3
    }
  ]
}

OData支持分页,排序,过滤,投影功能等等;详细请查看OData网站

5. 创建新实体

我们会创建一个新的person实体,示例如下:

Request
POST http://localhost:61842/odata/Persons

{
    Name: "Galileo Galilei"
}

注意:"Content_Type" 头的值是 "application/json"

Response
{
  "@odata.context": "http://localhost:61842/odata/$metadata#Persons/$entity",
  "Name": "Galileo Galilei",
  "IsDeleted": false,
  "DeleterUserId": null,
  "DeletionTime": null,
  "LastModificationTime": null,
  "LastModifierUserId": null,
  "CreationTime": "2016-01-12T20:36:04.1628263+02:00",
  "CreatorUserId": null,
  "Id": 4
}

如果我们再次获取一次实体列表,我们会看到新增的person;我们也可以更新或者删除一个已经存在的实体,这正是OData协议所支持的。

6. 获取元数据

我们可以获取一个实体的元数据,如下所示:

Request
GET http://localhost:61842/odata/$metadata
Response
<?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="AbpODataDemo.People" xmlns="http://docs.oasis-open.org/odata/ns/edm">
            <EntityType Name="Person">
                <Key>
                    <PropertyRef Name="Id" />
                </Key>
                <Property Name="Name" Type="Edm.String" Nullable="false" />
                <Property Name="IsDeleted" Type="Edm.Boolean" Nullable="false" />
                <Property Name="DeleterUserId" Type="Edm.Int64" />
                <Property Name="DeletionTime" Type="Edm.DateTimeOffset" />
                <Property Name="LastModificationTime" Type="Edm.DateTimeOffset" />
                <Property Name="LastModifierUserId" Type="Edm.Int64" />
                <Property Name="CreationTime" Type="Edm.DateTimeOffset" Nullable="false" />
                <Property Name="CreatorUserId" Type="Edm.Int64" />
                <Property Name="Id" Type="Edm.Int32" Nullable="false" />
                <NavigationProperty Name="Phones" Type="Collection(AbpODataDemo.People.Phone)" />
            </EntityType>
            <EntityType Name="Phone">
                <Key>
                    <PropertyRef Name="Id" />
                </Key>
                <Property Name="PersonId" Type="Edm.Int32" />
                <Property Name="Type" Type="AbpODataDemo.People.PhoneType" Nullable="false" />
                <Property Name="Number" Type="Edm.String" Nullable="false" />
                <Property Name="CreationTime" Type="Edm.DateTimeOffset" Nullable="false" />
                <Property Name="CreatorUserId" Type="Edm.Int64" />
                <Property Name="Id" Type="Edm.Int32" Nullable="false" />
                <NavigationProperty Name="Person" Type="AbpODataDemo.People.Person">
                    <ReferentialConstraint Property="PersonId" ReferencedProperty="Id" />
                </NavigationProperty>
            </EntityType>
            <EnumType Name="PhoneType">
                <Member Name="Unknown" Value="0" />
                <Member Name="Mobile" Value="1" />
                <Member Name="Home" Value="2" />
                <Member Name="Office" Value="3" />
            </EnumType>
        </Schema>
        <Schema Namespace="Default" xmlns="http://docs.oasis-open.org/odata/ns/edm">
            <EntityContainer Name="Container">
                <EntitySet Name="Persons" EntityType="AbpODataDemo.People.Person" />
            </EntityContainer>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

元数据被用来服务审查。

5.3.4 示例项目

你可以从这里获得示例项目的代码:: https://github.com/aspnetboilerplate/sample-odata