AspNet.OData 协议概述

2021-10-08 02:01:06

1. 什么是OData？

　　OData 全称 Open Data Protocol，字面理解为开放数据协议，是一个基于Http协议且API实现为Restful风格的协议标准，目前由微软支持大力推广，你可以看到MS自家产品，如WebApi、WCF均开始支持，可谓前景一片光明，其官网为：http://www.odata.org

2. 用它来做什么？

　　说的通俗点，大家在开发B/S应用时，前后台交互，大多采用 Ajax + json，而且大量操作是针对业务实体的增删改查和分页，但是大家对于Ajax请求的Url地址以及请求和应答的Json格式定义可谓千差万别，这时候OData站出来了，说：”你们特么都别瞎搞了，我定义一套统一的标准，大家都按我的搞吧“，于是前后台交互的数据规范产生了，为什么要统一？规范统一之后各种基于这个标准的类库、工具就会层出不穷，这不，官网列了很多基于此标准的工具（（http://www.odata.org/libraries），既然是通信协议，就会包括服务端和客户端，我们后面要讲的AspNet.OData就是服务端的一种实现，不久以后大家的增删改查也许嗖嗖几行代码就解决了，鼓掌吧~~~~~

3. 协议基础介绍

　　OData协议目前最新版本为V4，本教程以V4为例进行介绍，官方已经实现了一个开源的服务端，名为TripPin，具体介绍可以参考：http://www.odata.org/blog/trippin-new-odata-v4-sample-service，该服务的访问地址为：http://services.odata.org/V4/TripPinServiceRW，下面的协议介绍大家可以通过访问对应的链接（使用服务地址替换下方的serviceRoot）进行对比学习，本文仅介绍典型特性，参考了官方基础教程（basic-tutorial）协议细节请查看官方文档 OData Documentation

3.1 请求实体

请求实体集合

此请求返回 People 实体的集合（默认是前8个）

GET serviceRoot/People

替换之后实际的url是 http://services.odata.org/V4/TripPinServiceRW/People ，访问之后返回了json格式的People实体集合

 {
     "@odata.context": "serviceRoot/$metadata#People",
     "@odata.nextLink": "serviceRoot/People?%24skiptoken=8",
     "value": [
         {
             "@odata.id": "serviceRoot/People('russellwhyte')",
             "@odata.etag": "W/\"08D1694BD49A0F11\"",
             "@odata.editLink": "serviceRoot/People('russellwhyte')",
             "UserName": "russellwhyte",
             "FirstName": "Russell",
             "LastName": "Whyte",
             "Emails": [
                 "Russell@example.com",
                 "Russell@contoso.com"
             ],
             "AddressInfo": [
                 {
                     "Address": "187 Suffolk Ln.",
                     "City": {
                         "CountryRegion": "United States",
                         "Name": "Boise",
                         "Region": "ID"
                     }
                 }
             ],
             "Gender": "Male",
             "Concurrency": 635404796846280400
         },
         ......
         ,
         {
             "@odata.id": "serviceRoot/People('keithpinckney')",
             "@odata.etag": "W/\"08D1694BD49A0F11\"",
             "@odata.editLink": "serviceRoot/People('keithpinckney')",
             "UserName": "keithpinckney",
             "FirstName": "Keith",
             "LastName": "Pinckney",
             "Emails": [
                 "Keith@example.com",
                 "Keith@contoso.com"
             ],
             "AddressInfo": [],
             "Gender": "Male",
             "Concurrency": 635404796846280400
         }
     ]
 }

其中带@字符的属性都是一些便捷查询与数据本身无关，比如上面的 @odata.context、@odata.nextLink、@odata.id、@odata.etag、@odata.editLink，有一些后面再介绍。这里介绍一下 @odata.context和@odata.nextLink，@odata.context是数据服务的元数据查询请求，类似于webservice的wsdl，可以使用 OData Client for .NET 生成客户端代码，进而进行调用，类似与Webservice的使用。而 @odata.nextLink 是下一页的意思，默认/People查询只会返回8个实体，使用skiptoken=8，可以跳过前8个实体，这样就达到了分页的目的。

通过主键请求单个实体

因为People实体的主键是UserName，所以此请求会返回一个UserName为russellwhyte的实体。

GET serviceRoot/People('russellwhyte')

应答结果为：

 {
     "@odata.context": "serviceRoot/$metadata#People/$entity",
     "@odata.id": "serviceRoot/People('russellwhyte')",
     "@odata.etag": "W/\"08D1694BF26D2BC9\"",
     "@odata.editLink": "serviceRoot/People('russellwhyte')",
     "UserName": "russellwhyte",
     "FirstName": "Russell",
     "LastName": "Whyte",
     "Emails": [
         "Russell@example.com",
         "Russell@contoso.com"
     ],
     "AddressInfo": [
         {
             "Address": "187 Suffolk Ln.",
             "City": {
                 "CountryRegion": "United States",
                 "Name": "Boise",
                 "Region": "ID"
             }
         }
     ],
     "Gender": "Male",
     "Concurrency": 635404797346655200
 }

请求单个属性

在单实体查询url的后面加上属性名称可以进行指定属性的查询，如果实体属性是复杂对象，可以使用类似的方式继续查询其内部属性。

先看一下Airport实体的结构，使用 GET serviceRoot/Airport，然后用F12看下返回值

可以确定主键是IcaoCode属性，而且Location属性是复杂对象，下面看一下属性查询的格式

简单属性查询

GET serviceRoot/Airports('KSFO')/Name

应答结果：

{
    "@odata.context": "serviceRoot/$metadata#Airports('KSFO')/Name",
    "value": "San Francisco International Airport"
}

复杂属性查询

GET serviceRoot/Airports('KSFO')/Location/Address

应答结果：

{
"@odata.context": "serviceRoot/$metadata#Airports('KSFO')/Location/Address",
"value": "South McDonnell Road, San Francisco, CA 94128"
}

查询属性原始值

通过在属性查询url中增加$value，直接查询属性原始值，如：

GET serviceRoot/Airports('KSFO')/Name/$value

应当结果为：

San Francisco International Airport

其他查询请求

还有一些其他请求，本来打算一并介绍，后来觉得原文已经介绍的很好了，而且英文很简单，所以在此只抛砖引玉，不再赘述。

查询请求，通过协议中规定的一套查询表达式，可以任意的构造类似SQL语句的查询请求，这个结合服务端实现，会让后端代码骤减。
- 根据FirstName获取People GET serviceRoot/People?$filter=FirstName eq 'Scott'
- 复杂属性Location的Address属性包含“San Francisco” GET serviceRoot/Airports?$filter=contains(Location/Address, 'San Francisco')
- 查询枚举属性获取所有男性 GET serviceRoot/People?$filter=Gender eq Microsoft.OData.SampleService.Models.TripPin.PersonGender'Female'
- 查询排序 GET serviceRoot/People('scottketchum')/Trips?$orderby=EndsAt desc
- 分页查询 GET serviceRoot/People?$top=2 GET serviceRoot/People?$skip=18
- 计数查询 GET serviceRoot/People/$count
- 导航属性 GET serviceRoot/People('keithpinckney')?$expand=Friends
- 选择检索 GET serviceRoot/Airports?$select=Name, IcaoCode
- lambsa GET serviceRoot/People?$filter=Emails/any(s:endswith(s, 'contoso.com'))
数据修改请求，实现实体的增删改查。

码农公寓