在数据 API 生成器中托管 REST 终结点

数据 API 生成器提供 RESTful Web API,使你能够从连接的数据库中访问表、视图和存储过程。 实体表示数据 API 生成器运行时配置中的数据库对象。 必须在运行时配置中设置实体,以便它在 REST API 终结点上可用。

调用 REST API 方法

若要读取或写入资源(或实体),请使用以下模式构造请求:

{HTTP method} https://{base_url}/{rest-path}/{entity}

备注

URL 路径的所有组件(包括实体和查询参数)都区分大小写。

请求的组件包括:

描述
{HTTP method} 对数据 API 生成器的请求中使用的 HTTP 方法
{base_url} 托管数据 API 生成器实例的域(或 localhost 服务器和端口)
{rest-path} 运行时配置中设置的 REST API 终结点的基本路径
{entity} 运行时配置中定义的数据库对象的名称

下面是本地开发环境中位于 REST 终结点基础 /apibook 实体的示例 GET 请求 localhost

GET https:/localhost:5001/api/Book

HTTP 方法

数据 API 生成器对请求使用 HTTP 方法来确定对请求指定实体执行的操作。 以下 HTTP 谓词可用,具体取决于特定实体的权限集。

方法 描述
GET 获取零项、一个或多个项
POST 创建新项
PATCH 如果存在,请使用新值更新项。 否则,创建新项
PUT 将项替换为新的项(如果存在)。 否则,创建新项
DELETE 删除项

Rest 路径

其余路径指定数据 API 生成器的 REST API 的位置。 该路径在运行时配置中可配置,默认为 /api。 有关详细信息,请参阅 REST 路径配置

实体

实体 是用于引用数据 API 生成器中的 REST API 资源的术语。 默认情况下,实体的 URL 路由值是在运行时配置中定义的实体名称。 实体的 REST URL 路径值可在实体的 REST 设置中配置。 有关详细信息,请参阅 实体配置

结果集格式

返回的结果是采用以下格式的 JSON 对象:

{
    "value": []    
}

与所请求实体相关的项在 value 数组中可用。 例如:

{
  "value": [
    {
      "id": 1000,
      "title": "Foundation"
    },
    {
      "id": 1001,
      "title": "Foundation and Empire"
    }
  ]
}

备注

默认情况下,仅返回前 100 个项目。

获取

使用 GET 方法可以检索所需实体的一个或多个项。

URL 参数

REST 终结点允许使用 URL 参数按项的主键检索项。 对于具有单个主键的实体,格式非常简单:

GET /api/{entity}/{primary-key-column}/{primary-key-value}

若要检索 ID 为 1001的书籍,请使用:

GET /api/book/id/1001

对于具有复合主键的实体,其中多个列用于唯一标识记录,URL 格式按顺序包括所有键列:

GET /api/{entity}/{primary-key-column1}/{primary-key-value1}/{primary-key-column2}/{primary-key-value2}

如果 books 实体具有由 id1id2组成的复合键,你将检索如下所示的特定书籍:

GET /api/books/id1/123/id2/abc

例如:

下面是通话的外观:

### Retrieve a book by a single primary key
GET /api/book/id/1001

### Retrieve an author by a single primary key
GET /api/author/id/501

### Retrieve a book by compound primary keys (id1 and id2)
GET /api/books/id1/123/id2/abc

### Retrieve an order by compound primary keys (orderId and customerId)
GET /api/orders/orderId/789/customerId/456

### Retrieve a product by compound primary keys (categoryId and productId)
GET /api/products/categoryId/electronics/productId/987

### Retrieve a course by compound primary keys (departmentCode and courseNumber)
GET /api/courses/departmentCode/CS/courseNumber/101

查询参数

REST 终结点支持以下查询参数(区分大小写)来控制返回的项:

查询参数可以一起使用。

$select

查询参数 $select 允许指定必须返回哪些字段。 例如:

### Get all fields
GET /api/author

### Get only first_name field
GET /api/author?$select=first_name

### Get only first_name and last_name fields
GET /api/author?$select=first_name,last_name

备注

如果任何请求的字段不存在或由于配置的权限而无法访问,则返回 400 - Bad Request

$select 查询参数(也称为“投影”)用于控制 API 响应中返回的数据的大小。 仅使用所需的列时,$select 可减少有效负载大小,从而通过最小化分析时间、降低带宽使用率和加快数据处理速度来提高性能。 此优化扩展到数据库。 在那里,只检索请求的列。

$filter

$filter 选项的值是使用实体字段返回布尔结果的谓词表达式(返回布尔结果的表达式)。 只有表达式的计算结果为 True 的项才会包含在响应中。 例如:

### Get books titled "Hyperion" (Equal to)
GET /api/book?$filter=title eq 'Hyperion'

### Get books not titled "Hyperion" (Not equal to)
GET /api/book?$filter=title ne 'Hyperion'

### Get books published after 1990 (Greater than)
GET /api/book?$filter=year gt 1990

### Get books published in or after 1990 (Greater than or equal to)
GET /api/book?$filter=year ge 1990

### Get books published before 1991 (Less than)
GET /api/book?$filter=year lt 1991

### Get books published in or before 1990 (Less than or equal to)
GET /api/book?$filter=year le 1990

### Get books published between 1980 and 1990 (Logical and)
GET /api/book?$filter=year ge 1980 and year le 1990

### Get books published before 1960 or titled "Hyperion" (Logical or)
GET /api/book?$filter=year le 1960 or title eq 'Hyperion'

### Get books not published before 1960 (Logical negation)
GET /api/book?$filter=not (year le 1960)

### Get books published in 1970 or later, and either titled "Foundation" or with more than 400 pages (Grouping)
GET /api/book?$filter=(year ge 1970 or title eq 'Foundation') and pages gt 400

$filter 选项支持的运算符包括:

算子 类型 描述
eq 比较 平等 title eq 'Hyperion'
ne 比较 不等于 title ne 'Hyperion'
gt 比较 大于 year gt 1990
ge 比较 大于或等于 year ge 1990
lt 比较 小于 year lt 1990
le 比较 小于或等于 year le 1990
and 逻辑 逻辑和 year ge 1980 and year lt 1990
or 逻辑 逻辑或 year le 1960 or title eq 'Hyperion'
not 逻辑 逻辑求反 not (year le 1960)
( ) 分组 优先分组 (year ge 1970 or title eq 'Foundation') and pages gt 400

备注

$filter 是区分大小写的参数。

Azure 数据 API Builder 中的 $filter 查询参数可能会提醒某些用户 OData,这是因为它直接受到 OData 筛选功能的启发。 语法几乎完全相同,使熟悉 OData 的开发人员可以轻松选取和使用。 这种相似性是有意的,旨在提供一种熟悉且强大的方法来筛选不同 API 中的数据。

$orderby

orderby 参数的值是用于对项进行排序的表达式的逗号分隔列表。

orderby 参数值中的每个表达式可能包含后缀 desc 以请求降序,以一个或多个空格分隔表达式。

例如:

### Order books by title in ascending order
GET /api/book?$orderby=title

### Order books by title in ascending order
GET /api/book?$orderby=title asc

### Order books by title in descending order
GET /api/book?$orderby=title desc

### Order books by year of publication in ascending order, then by title in ascending order
GET /api/book?$orderby=year asc, title asc

### Order books by year of publication in descending order, then by title in ascending order
GET /api/book?$orderby=year desc, title asc

### Order books by number of pages in ascending order, then by title in descending order
GET /api/book?$orderby=pages asc, title desc

### Order books by title in ascending order, then by year of publication in descending order
GET /api/book?$orderby=title asc, year desc

备注

$orderBy 是区分大小写的参数。

$orderby 查询参数对于直接在服务器上对数据进行排序非常有用,也可以轻松地在客户端进行处理。 但是,当与其他查询参数(如 $filter$first)结合使用时,它将变得很有用。 参数允许分页在对大型集合进行分页时维护稳定且可预测的数据集。

$first$after

$first 查询参数限制单个请求中返回的项数。 例如:

GET /api/book?$first=5

此请求返回前五本书。 Azure 数据 API Builder 中的 $first 查询参数类似于 SQL 中的 TOP 子句。 这两者用于限制从查询返回的记录数。 正如 SQL 中的 TOP 允许指定要检索的行数一样,$first 允许你控制 API 返回的项数。 如果要提取少量数据(例如前 10 个结果),而不检索整个数据集,则 $first 非常有用。 主要优势是效率,因为它减少了传输和处理的数据量。

备注

在 Azure 数据 API 生成器中,默认情况下返回的行数受配置文件中的设置的限制。 用户可以使用 $first 参数重写此限制以请求更多行,但仍有一个配置的最大行数,可以整体返回。 此外,单个响应中可以返回的总兆字节数限制,该响应也是可配置的。

如果超出指定限制的更多项可用,响应将包括 nextLink 属性:

{
    "value": [],
    "nextLink": "dab-will-generate-this-continuation-url"
}

nextLink 可与 $after 查询参数一起使用,以检索下一组项:

GET /api/book?$first={n}&$after={continuation-data}

此延续方法使用基于游标的分页。 唯一游标是对数据集中特定项的引用,用于确定下一个集中继续检索数据的位置。 与使用偏移量或索引的索引分页不同,基于游标的分页不依赖于跳过记录。 游标延续使它更可靠地处理大型数据集或频繁更改的数据。 而是根据提供的游标,从最后一个查询离开的位置开始,确保数据检索的流畅且一致。

例如:

### Get the first 5 books explicitly
GET /api/book?$first=5

### Get the next set of 5 books using the continuation token
GET /api/book?$first=5&$after={continuation-token}

### Get the first 10 books, ordered by title
GET /api/book?$first=10&$orderby=title asc

### Get the next set of 10 books after the first set, ordered by title
GET /api/book?$first=10&$after={continuation-token}&$orderby=title asc

### Get books without specifying $first (automatic pagination limit)
GET /api/book

### Get the next set of books using the continuation token without specifying $first
GET /api/book?$after={continuation-token}

发布

为指定实体创建新项。 例如:

POST /api/book
Content-type: application/json

{
  "id": 2000,
  "title": "Do Androids Dream of Electric Sheep?"
}

POST 请求将创建新书籍。 必须提供所有不能为 null 的字段。 如果成功,将返回完整的实体对象(包括任何 null 字段):

{
  "value": [
    {
      "id": 2000,
      "title": "Do Androids Dream of Electric Sheep?",
      "year": null,
      "pages": null
    }
  ]
}

PUT 创建或替换指定实体的项。 查询模式为:

PUT /api/{entity}/{primary-key-column}/{primary-key-value}

例如:

PUT /api/book/id/2001
Content-type: application/json

{  
  "title": "Stranger in a Strange Land",
  "pages": 525
}

如果某个项具有指定的主键 2001,则所提供的数据 将完全替换该项。 如果不存在具有该主键的项,则会创建一个新项。

无论哪种情况,结果都类似于:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": null,
      "pages": 525
    }
  ]
}

补丁

PATCH 创建或更新指定实体的项。 仅影响指定的字段。 请求正文中未指定的所有字段均不受影响。 如果具有指定主键的项不存在,则会创建一个新项。

查询模式为:

PATCH /api/{entity}/{primary-key-column}/{primary-key-value}

例如:

PATCH /api/book/id/2001
Content-type: application/json

{    
  "year": 1991
}

结果如下所示:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": 1991,
      "pages": 525
    }
  ]
}

删除

DELETE 删除指定实体的项。 查询模式为:

DELETE /api/{entity}/{primary-key-column}/{primary-key-value}

例如:

DELETE /api/book/id/2001

如果成功,则结果为状态代码为 204 的空响应。

REST API 请求的数据库事务

处理 POST、PUT、PATCH 和 DELETE API 请求;数据 API 生成器在事务中构造和执行数据库查询。

下表列出了为每个数据库类型创建事务的隔离级别。

数据库类型 隔离级别 详细信息
Azure SQL (或) SQL Server 已提交读取 Azure SQL
MySQL 可重复读取 MySQL
PostgreSQL 已提交读取 PostgreSQL