[水煮 ASP.NET Web API2 方法论](12-4)OData 支持的 Function 和 Action

问题

在 Web API 中使用 OData Function 和 Action。

 

解决方案

可以通过 ODataModelBuilder,使用 OData 构建 ASP.NET Web API, EntityCollectionConfiguration,EnityTypeConfiguration 类中提供的一系列 Function 和 Action 来自定义 Function 和 Action。

当我们都建自己的 ODataModelBuilder 的时候,可以指定 Function 或 Action 名称并定义他们的输入参数。如清单12-12 所示。

清单 12-12. 

 1             var ODataBuilder = new ODataConventionModelBuilder();
 2 
 3             ODataBuilder.EntitySet<Player>("Players");
 4 
 5             var player = ODataBuilder.EntityType<Player>();
 6 
 7             // Function – 读取数据
 8 
 9             player.Function("PercentageOfAllGoals").Returns<double>();
10 
11             // Action – 请求操作
12 
13             player.Action("TradePlayer").Parameter<string>("NewTeam");

 

Controller Action 和 OData Function/Action 之间是通过命名的约定建立关联,因此,我们需要在 OData 的 controller 中添加合适的 Action。

 

工作原理

ASP.NET WEB API 从 2.2 版本开始支持 OData,而且,已经成为 OData 3.0 规范的一部分。另一方面,在之前 Web API 中 OData 的 Action 也是可以使用的。

我们是可以以 Web API Action 的形式定义 OData Function/Action 同时暴露给客户端访问。

使用 Action 或 Function 的主要优势是,我们可以将查询的责任转交给服务器,尤其是复杂查询的时候,可以减轻客户端的不必要的麻烦。

OData 的 Action 和 Function 是有点不一样的;他们都是在规范中被定义的“一组可以被执或可以作为服务或可以作为资源的操作的扩展”。主要的不同是

  • Function:可以能没有什么结果,但是必须有返回值
  • Action:可以对服务器产生影响,但是不能有返回值
  • 另外,Function 可以在 $filter 中被调用

在实现了 OData 的 ASP.NET WEB API 中,Action 和 Function 是连同 OData 约定一起被定义,他们是通过 ODataConventionModelBuilder 的实例定义。WEB API OData 的构建支持三种类型(级别)的操作:

  • 服务 Action/Function:ODataModelBuilder 直接定义
  • 集合 Action/Function:EntityCollectionConfiguration 直接定义
  • 实体 Action/Function:EntityTypeConfiguration直接定义

 

代码演示

 

如清单 12-13 所示,一个简单的数据集合,为了演示的方面,在 Controller 中通过内存进行数据的操作,还有一个 Player 的 DTO 的类。

我们就使用这些代码模拟 OData 的三种类型:服务,集合,实体绑定。演示中主要关注在 Function 上,但是, Action 的定义和使用也是几乎一样的。也就是说,在所有使用 Function 声明的方法的地方,都换成 Action 声明的方法是没有毛病的。

 

清单 12-13. 内存数据和实体模型

 1     public class Player
 2     {
 3         public int Id { get; set; }
 4 
 5         public string Name { get; set; }
 6 
 7         public string Team { get; set; }
 8 
 9         public SkaterStat Stats { get; set; }
10     }
11 
12     public class SkaterStat
13     {
14         public int Goals { get; set; }
15 
16         public int Assists { get; set; }
17 
18         public int GamesPlayed { get; set; }
19     }
20 
21     public class PlayersController : ODataController
22     {
23         private static List<Player> _players = new List<Player>
24         {
25             new Player
26             {
27                 Id = 1,
28                 Name = "Filip",
29                 Team = "Whales",
30                 Stats = new SkaterStat
31                 {
32                     GamesPlayed = 82,
33                     Goals = 37,
34                     Assists = 43
35                 }
36             },
37             new Player
38             {
39                 Id = 2,
40                 Name = "Felix",
41                 Team = "Whales",
42                 Stats = new SkaterStat
43                 {
44                     GamesPlayed = 80,
45                     Goals = 30,
46                     Assists = 31
47                 }
48             new Player
49 {
50     Id        = 3,
51                 Name = "Luiz",
52                 Team = "Dolphins",
53                 Stats = new SkaterStat
54                 {
55                     GamesPlayed = 78,
56                     Goals = 20,
57                     Assists = 30
58                 }
59             },
60             new Player
61             {
62                 Id = 4,
63                 Name = "Terry",
64                 Team = "Dolphins",
65                 Stats = new SkaterStat
66                 {
67                     GamesPlayed = 58,
68                     Goals = 19,
69                     Assists = 30
70                 }
71             }
72         };
73     }

 

前面提到的 Function 方法,来自于 ODataModelBuilder;EntityCollectionConfiguration,EntityTypeConfiguration,都返回一个 FunctionConfiguration 的实例,我们就是用它来配置我们的 Function,例如,在 $filter 中是否支持 Function,接收什么样的参数,应该返回什么。例如,这个演示的 Startup 类中定义了 ODataModelBuilder的 三个 OData  Function 类型和一个实体类型,如清单 12-14 所示。

 

清单 12-14 OData Function 服务、集合、实体

 1     public class Startup
 2     {
 3 
 4         public void Configuration(IAppBuilder builder)
 5         {
 6 
 7             var ODataBuilder = new ODataConventionModelBuilder();
 8 
 9             ODataBuilder.EntitySet<Player>("Players");
10 
11             var player = ODataBuilder.EntityType<Player>();
12 
13             /* 集合 Function */
14 
15             player.Collection.Function("TopPpg").ReturnsCollection<Player>();
16 
17             /* 实体 Function */
18 
19             player.Function("PercentageOfAllGoals").Returns<double>();
20 
21             /* 服务 Function */
22 
23             var serviceFunc = ODataBuilder.Function("TotalTeamPoints");
24 
25             serviceFunc.Returns<int>().Parameter<string>("team");
26 
27             serviceFunc.IncludeInServiceDocument = true;
28 
29             var edm = ODataBuilder.GetEdmModel();
30 
31             var config = new HttpConfiguration();
32 
33             config.MapODataServiceRoute("Default OData", "OData", edm);
34 
35             builder.UseWebApi(config);
36 
37         }
38 
39     }

 

TopPpg 是一个集合 Function,他将返回每场比赛最高分(得分+助攻)比例 player 的集合。PercentageOfAllGoals 是一个实体 Function,返回每场比赛给定参赛者相对所有得分的分数比例。这个 Function 需要客户端传一个 key(player ID),但是,需要注意的是,这个 key 是实体对象的 Id,不需要在 Function 中特殊指明。最后,TotalTeamPoints 是无限制的服务 Function,也就是说,不是特指某一个 player,而是传入一个队名最为参数,同时返回整个队内所有队员分数(得分+助攻)的总和。另外,TotalTeamPoints 也会包含在文档服务中,/OData/$metadata ,作为 Function 入口。

这些 Function 在 Action 中都是使用的 LINQ 表达式。无限制服务的 Function 使用了 ODataRoute 属性,因为默认的 EMD 驱动路由约定不能完成整个功能。

 

12-15/ 使用 OData Function 来暴露 Controller 的 Action

 1         [HttpGet]
 2         public IEnumerable<Player> TopPpg()
 3         {
 4             var result = _players.OrderByDescending(x => (double)(x.Stats.Goals + x.Stats.Assists) / (double)x.Stats.GamesPlayed).Take(3);
 5             return (result);
 6         }
 7 
 8 
 9         [HttpGet]
10         public IHttpActionResult PercentageOfAllGoals(int key)
11         {
12             var player = _players.FirstOrDefault(x => x.Id == key);
13             if (player == null)
14                 return (NotFound());
15             var result = (double)player.Stats.Goals / (double)_players.Sum(x => x.Stats.Goals) * 100;
16             return (Ok(result));
17         }
18 
19 
20         [HttpGet]
21         [ODataRoute("TotalTeamPoints(team={team})")]
22         public int TotalTeamPoints([FromODataUri] string team)
23         {
24             var result = _players.Where(x => string.Equals(x.Team, team, StringComparison.
25                                      InvariantCultureIgnoreCase))
26                      .Sum(x => x.Stats.Goals + x.Stats.Assists);
27             return (result);
28         }

 

在这些地方,可以在 URI 中使用 Function 名称来调用他们。根据规范,调用 OData Function 的时候需要使用括号:

  • /OData/Players/Default.TopPpg()
  • /OData/Players(1)/Default.PercentageOfAllGoals()
  • /OData/TotalTeamPoints(team='Whales')

 关于 OData 在 ASP.NET WEB API 中的介绍就此告一段落,接下来,一段时间将介绍关于 Route 的东西。

 

posted @ 2016-11-23 08:03  水煮Code  阅读(1082)  评论(0编辑  收藏  举报