HTTP 方法
资源是 API 中公开的对象,可以查询、创建、更新和删除。资源可以支持完整的创建、读取、更新和删除 (CRUD) 操作,也可以仅限于少数操作。本节介绍用于对应用程序公开的资源执行 CRUD 操作的 HTTP 方法。GET
可以使用 HTTP GET 请求从服务器检索一个资源或一组资源。以下是对整个集合的请求示例:GET http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars
这是相应的响应:
POST
可以使用 HTTP POST 请求创建新资源。该请求必须包含创建资源所需的输入。以下是请求示例:PUT
可以使用 HTTP PUT 请求更新资源。主键是必需的。以下是请求示例:DELETE
可以使用 HTTP DELETE 请求删除资源。主键是必需的。以下是请求示例:DELETE http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars/('Id_1')
响应为空,并显示 204 No Content HTTP 状态行。
过滤资源
可以使用 HTTP GET 请求检索所有资源、过滤资源、对资源进行排序以及限制每个资源返回的数据。URL 的路径指定要检索的资源集。例如,要检索所有 Cars 资源,请使用以下 URL:http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars
单个资源
要检索单个资源,请向该资源的 URL 发出请求。要构造 URL,请使用所需资源的主键。例如:http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')
某些资源可能有多个主键,这些主键的索引如下例所示:
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars(Id='1000', Date='2016-07-01')
过滤
客户端应用程序可以根据请求中提供的过滤器检索多个资源。例如,用于检索 Make 与 ‘Honda’ 匹配的所有资源的过滤器如下所示:http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=Make eq 'Honda'
该应用程序支持以下逻辑运算符进行比较:
还可以使用
and 和 or 来组合多个过滤器。例如:
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=Make eq 'Honda' and Date lt '2016-07-01'
可以将 startswith、endswith、toupper、tolower 和 contains 函数与 $filter 查询选项一起使用。例如,以下请求返回其属性包含指定子字符串的资源:
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=contains(Make,'Honda')
选择属性
要检索属性的子集,请使用$select,如以下示例所示:
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$select=Id,Model
这将返回与请求中的过滤器匹配的所有资源的 Id 和 Model 属性。
还可以检索单个资源的单独属性值,如以下示例所示:
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')/Model/$value
排序
可以使用$orderby 对资源进行排序,如下例所示:
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$orderby=Model asc, Color desc
这将返回按 Model(升序)排序的资源,然后按 Color(降序)排序。
分页
服务器端
该应用程序支持服务器端分页。在 设置 > 服务器 中启用此选项。当页面大小大于 0 并且请求返回的结果大于页面大小时,下一页结果的 URL 将包含在响应的@odata.nextlink 属性中。结果的最后一页不包含此属性。此 URL 包含一个分页令牌,该令牌在接下来的两分钟内保持有效。例如,以下响应具有三个资源和一个包含下一页记录 URL 的 @odata.nextLink 属性:
客户端
知行之桥还支持使用$top、$skip 和 $count 的客户端分页。
可以使用 $top=n 仅包含结果中的前 n 个资源。例如,使用以下请求显示前十个 Cars 资源:
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10
可以使用 $skip=n 从结果中排除前 n 个资源。可以结合使用 $top 和 $skip 来实现客户端分页。无论它们在查询中的顺序如何,$skip 始终在 $top 之前应用。例如,以下两个查询会分两页检索前 20 个资源:
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10&$skip=10
可以将 $count 设置为 true,以返回结果中的记录总数。如果使用 OData 版本 2.0 或 3.0,则可以改为将 $inlinecount 设置为 allpages。例如,考虑以下查询:
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=3&$skip=4&$count=true
此查询可能会返回如下响应:
仅计数
可以通过查询仅检索与特定过滤器匹配的资源计数,如以下示例所示:http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$count=true&$filter=Make eq 'Honda'
响应是与请求中的过滤器匹配的资源的原始计数。