[水煮 ASP.NET Web API2 方法论]（12-3）OData 查询

问题

Web API 怎么支持通用的 OData 系统查询项，例如 $select 或 $filter。

 

解决方案

为了在 Web API 中启用查询项，我们需要在 Action 上使用 EnableQueryAttribute。

如果 Action 没有返回集合，而是返回单个对象的实例，调用端仍然可以使用 $expand 和 $select 两个查询语句，要达到这个目的，我们必须将返回对象包装在 SingleResult<T> 中。集合和单个对象实例作为返回值的例子如订单 12-7 所示

清单 12-7. 在两个路由上启用查询语句

    public class PlayersController : ODataController

    {

        private readonly PlayersContext playersDbContext = new PlayersContext();

        [EnableQuery]

        public IQueryable<Player> GetAllPlayers()

        {

            Return playersDbContext;

        }

        [EnableQuery]

        public SingleResult<Player> GetSinglePlayers(int key)

        {

            return SingleResult.Create(playersDbContext.Where(x => x.Id == key).AsQueryable());

        }

    }

工作原理

OData 查询选项是被定义在 OData 规范中，如，查询字符串的参数控制的是返回资源的数量和顺序。ASP.NET Web API 几乎支持所有的标准查询项：

• $expand：允许响应给客户端的信息包含关联资源（导航属性）
• $select：限制返回的属性
• $filter：过滤 Api 暴露出来的资源
• $count：获取集合中实体的总数
• $orderby：指定集合的排序 key
• $skip：获取集合跳过的数量
• $top：限制集合返回集合的数量
• $format：请求特定的响应格式

唯一不支持的是 $search 查询参数。

 

小提示 可以查看 OData 4.0 支持的完整的文档地址：http://docs.oasis-open.org/OData/new-in-OData/v4.0/cn01/new-in-OData-v4.0-cn01.html

查询项是在 ASP.NET Web API 中被 ODataQueryOption 类所描述的。EnableQueryAttribute 的工作方式实际是非常简单的。因为他是 Action 的 Filter，在 OnActionExecuted 方法中会获取 Action 的响应，并转换 HttpContent 为ObjectContent<T>。然后根据 HttpRequest 基于客户端的参数构造 ODataQueryOptions 实例，并返回相应的响应给客户端。如果响应是集合的话，可以响应客户端所有的查询项。如果响应不是集合，就会通过 ObjectContent 包装成 SingleResult<T>。这些时候，$expand 和 $select 都是可用的。

不使用 EnableQueryAttribute，也可以使用 ODataQueryOptions，他是可以接受 Action 的参数的。这种方式是通过自定义 HttpParameterBinding 类型的 ODataQueryParameterBinding 来支持的。我们也可以使用 ODataQueryOptions 实例中的信息手动执行相关查询。

在 Web API 中我们不需要完全掌握 OData 就可以体会到查询项给我们带来的便利。就算不是基于 ODataCotrollers，只要 Action 上使用了 EnableQueryAttribute 属性标签，我们还是可以在 Web API 上使用一些基础查询项，例如，$top,$skip,$select。

 

代码演示

在 Controller 的 Action 上使用 EnableQueryAttribute，这样的请求就可以使用 OData 查询项，如清单 12-7

• Host/Plays(1)$select=Name,Team：使用 Player 实体的 Id 进行过滤，仅仅返回 Name 和 Team 两个属性。这个例子的响应，如清单 12-8.

 

清单 12-8. 从 OData 的 Web API 查询响应例子

{
  "@OData.context":"http://localhost:43539/OData/$metadata#Players(Name,Team)/$entity","Name":"Name1","Team":"Team"
} 

• Host/Players?skip=1&$top=2：忽略集合中第一个实体，然后再剩下的实体中获取两个返回（可以理解为分页的第二页数据，每页大小是 2）。具体响应，如清单 12-9 所示。

清单 12-9. 从 OData 的 Web API 查询响应例子

{
  "@OData.context":"http://localhost:43539/OData/$metadata#Players","value":[
    {
      "Id":1,"Name":"Name1","Team":"Team"
    },{
      "Id":2,"Name":"Name11","Team":"Team"
    }
  ]
}

• Host/Players?$format=application/json;OData.metadata=full&$filter=Team%20eq%20%27Team2%27：请求条件你为 Team 属性值为 Whales，以 json 格式返回 ,包含 OData 元数据的所有信息，包含类型和导航链接。具体响应结果，如清单 12-10 所示

{
  "@OData.context":"http://localhost:43539/OData/$metadata#Players","value":[
    {
      "@OData.type":"#BoiledCode.WebApi.Recipe.ODataDemo.Models.Player","@OData.id":"http://localhost:43539/OData/Players(3)","@OData.editLink":"http://localhost:43539/OData/Players(3)","Id":3,"Name":"Name2","Team":"Team2"
    },{
      "@OData.type":"#BoiledCode.WebApi.Recipe.ODataDemo.Models.Player","@OData.id":"http://localhost:43539/OData/Players(4)","@OData.editLink":"http://localhost:43539/OData/Players(4)","Id":4,"Name":"Name21","Team":"Team2"
    }
  ]
}

就像上面提到的，我们可以通过在 Action 方法中使用 ODataQueryOptions 参数，来手动的实现询项。ODataQueryParameterBinding 会帮我完成将对象传入到 Action 的操作，这样我们就可以 Action 内部提取 OData 相关的查询项了。 

清单 12-11. 在 Action 中使用 ODataQueryOptions

        public IQueryable<Player> GetAllPlayers(ODataQueryOptions queryOptions)

        {

            // 客户端传入的 top 和 skip

            var filtered = db.Players.Skip(queryOptions.Skip.Value);

            if (queryOptions.Top.Value > 0)

            {

                filtered = filtered.Take(queryOptions.Top.Value);

            }

            return filtered.AsQueryable();

        }