OData – 基础语法 Basic

前言

有时候太久没有写真的会忘记，官网又太罗里吧嗦，还是写一篇帮助以后快速复习进入状况吧。

Request URL: "/root/version/entities"

OData path 长这样

/api/v1.0/projects

第一个 segment 是 API 路径的开头。

常见的是开头有 “/odata/” 或者 “/api/”

第二个 segment 是 version

比如： "v1.0" 或者 "v2.1"

第三个 segment 是 entity name (通常是以 plural 命名)

比如："products", "projects", "people"

完整的 URL 长这样

https://example.com/api/v1.0/projects

Response Data

OData 的 response 长这样

一定是一个对象。

value 是一个 array，里面是 entity 对象。

$select

$select 可以指定 response data 的 property，没有指定就是出到完

/api/v1.0/projects?$select=id

效果

property name 没了，因为 $select 指定只输出 property id 而已。

$skip, $top (pagination)

假设一页显示 10 条数据，当前在第二页，那需要显示的数据就是第 11 条到第 20 条。

/api/v1.0/projects?$skip=10&$top=10

$skip=10 表示前 10 条数据不要 (第 1 到 第 10 不要，也就是从第 11 开始拿)

$top=10 表示只拿 10 条数据出来 (也就是拿到第 20 条)

$count

$count 是用来弥补 $skip 和 $top 的。

$skip, $top 只取一部分数据出来，假如我们想知道在没有 $skip, $top 的情况下总数是多少条，那就可以使用 $count

/api/v1.0/projects?$count=true&$skip=10&$top=10

效果

response data 多了一个属性 "@odata.count"

$orderby

/api/v1.0/projects?$orderby=name

$orderby 就是依据 property value 排序。

默认是 ascending，要 descending 就加空格 desc

/api/v1.0/projects?$orderby=name desc

想 order by multiple property 就用逗号做分割

/api/v1.0/projects?$orderby=id desc, name asc

先 order by id descending then by name ascending ("asc” 不写也可以，默认就是 "asc")

$expand

$expand 的作用是额外输出 related entity，比如

public class Product
{
  public string Name { get; set; } = "";
  public List<Color> Colors { get; set; } = [];
}

public class Color
{
  public Product Product { get; set; } = null!;
  public string Name { get; set; } = "";
  public List<Size> Sizes { get; set; } = [];
}

public class Size
{
  public Color Color { get; set; } = null!;

  public string Name { get; set; } = "";
}

Product, Color, Size 相互都有关联。

/products?$expand=colors

效果

它还可以嵌套哦

/products?$expand=colors($expand=sizes)

效果

嵌套 $expand 还可以搭配其它 operator 使用

$expand=colors($select=id, name;$orderby=id desc)

用分号 “;” 做分割。

$filter

$filter 用于过滤数据

/api/v1.0/products?$filter=name eq 'abc'

上面这句的意思是只输出 property name 等于 "abc" 的 entities。

eq 是 equal 的缩写

‘abc’ 需要用 quote 符号框起来。假如碰巧 compare 的 value 内包含 quote 那需要 encode 把 single quote (') 变成 double single quote ('')，注：不是 double quote 而是 double single quote 哦

compare 的 operator 有非常的多，常见的：

1. not equal

   name ne 'abc'

2. greater than

   price gt 100 (注：只有 string 需要 quote)

3. less than

   price lt 100

4. greater than or equal to

   price ge 100

5. less than or eqaul to

   price le 100

6. startswith

   startswith(name, 'abc')

7. endswith

   endswith(name, 'abc')

8. contains

   contains(name, 'abc')

另外，表达式也支持 and, or, 括弧

$filter=(id gt 1 and id lt 2) or name eq 'abc'

等价于 LINQ

products.Where(p => (p.Id is > 1 and < 10) || p.Name == "x")

另外，$filter 也可以 filter related entity property

/api/colors?$filter=product/name eq 'abc'

等价于 LINQ

colors.Where(c => c.Product.Name == "abc")

$apply, groupby, aggregate

groupby 长这样

/api/v1.0/products?$apply=groupby(
  (prop1, prop2),
    aggregate(
      prop1 with sum as sumProp1,
      prop2 with average as aveProp2,
      $count as count,
      prop3 with countdistinct as prop3DistinctCount
  )
)

我们一句一句看

(prop1, prop2) 表达要 group by 依据哪些 properties，支持 group by multiple property。

group by 以后需要 aggregate 做 sum, average , max, min 等 operator。

prop1 with sum as sumProp1 就是把 prop1 sum 起来，然后以 property name "sumProp1" 作为输出。

$count 就是 group 之后的 count 咯

countdistinct 是针对指定 property distinct value 后的 count。

例子：

/api/products

效果

group by category sum price

/api/products?$apply=groupby((category), aggregate(price with sum as sumPrice))

效果