在数据 API 生成器中托管 REST 终结点
数据 API 生成器提供 RESTful Web API,使你能够从连接的数据库中访问表、视图和存储过程。 实体表示数据 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 终结点基础 /api
book
实体的示例 GET 请求 localhost
:
GET https:/localhost:5001/api/Book
数据 API 生成器对请求使用 HTTP 方法来确定对请求指定实体执行的操作。 以下 HTTP 谓词可用,具体取决于特定实体的权限集。
其余路径指定数据 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 方法可以检索所需实体的一个或多个项。
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
实体具有由 id1
和 id2
组成的复合键,你将检索如下所示的特定书籍:
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
:仅返回所选列 -
$filter
:筛选返回的项目 -
$orderby
:定义如何对返回的数据进行排序 -
$first
和$after
:仅返回顶部n
项
查询参数可以一起使用。
查询参数 $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
选项的值是使用实体字段返回布尔结果的谓词表达式(返回布尔结果的表达式)。 只有表达式的计算结果为 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
参数值中的每个表达式可能包含后缀 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
查询参数限制单个请求中返回的项数。 例如:
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 的空响应。
处理 POST、PUT、PATCH 和 DELETE API 请求;数据 API 生成器在事务中构造和执行数据库查询。
下表列出了为每个数据库类型创建事务的隔离级别。
数据库类型 | 隔离级别 | 详细信息 |
---|---|---|
Azure SQL (或) SQL Server | 已提交读取 | Azure SQL |
MySQL | 可重复读取 | MySQL |
PostgreSQL | 已提交读取 | PostgreSQL |