API Resources

Version 24.3.9111

HTTP 方法
- GET
- POST
- PUT
- DELETE
过滤 Resources
- 单一 Resource
- 过滤
选择属性
排序
分页

API Resources

知行之桥 API 中的 Resource 使用 JSON 格式的 OData 作为访问数据的默认 REST 协议。支持其他 Web 服务格式，包括 OData (Atom)、JSONP、HTML 和 CSV。

HTTP 方法

Resource 是 API 中公开的对象，可以查询、创建、更新和删除。 Resource 可以支持全方位的创建、读取、更新和删除 (CRUD) 操作，也可以仅限于少数操作。本节介绍用于对应用程序公开的 Resource 执行 CRUD 操作的 HTTP 方法。

GET

Resource 可以使用 HTTP GET 请求从服务器检索一个 Resource 或一组 Resource 。以下是对整个集合的请求示例：

GET http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars

这是相应的响应：

{
  "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ]
}

POST

Resource 可以使用 HTTP POST 请求来创建新 Resource 。该请求必须包含创建 Resource 所需的输入。以下是请求示例：

POST http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars
{
  "Color": "Color_1", "Model": "Model_1" 
}

这是相应的响应：

{
	"@odata.context":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
	"value": [
		{ "Color": "Color_1", "Model": "Model_2" }
	]
}

PUT

Resource 可以使用 HTTP PUT 请求来更新 Resource 。主键是必需的。以下是请求示例：

PUT http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('Id_1')
{
  "Color": "Color_1", "Model": "Model_1"
}

这是相应的响应：

{
	"@odata.context":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars/$entity",  
	"Id": "Id_1", "Color": "Color_1", "Model": "Model_1"
}

DELETE

Resource 可以使用 HTTP DELETE 请求来删除 Resource 。主键是必需的。以下是请求示例：

DELETE http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars/('Id_1')

响应为空，并显示 204 No Content HTTP 状态行。

过滤 Resources

Resource 可以使用 HTTP GET 请求来检索所有 Resource 、过滤 Resource 、对 Resource 进行排序以及限制从每个 Resource 返回的数据。 URL 的路径指定要检索的 Resource 集。例如，要检索所有汽车 Resource ，请使用以下 URL：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars

单一 Resource

要检索单个 Resource ，请向该 Resource 的 URL 发出请求。要构造 URL，请使用所需 Resource 的主键。例如：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')

某些 Resource 可能有多个主键，这些主键的索引如下例所示：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars(Id='1000', Date='2016-07-01')

过滤

客户端应用程序可以根据请求中提供的过滤器检索多个 Resource 。例如，用于检索 Make 与 ‘BYD’ 匹配的所有 Resource 的过滤器如下所示：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=Make eq 'BYD'

该应用程序支持以下逻辑运算符进行比较：

Eq	等于
Ne	不等于
Gt	大于
Ge	大于或等于
Lt	小于
Le	小于或等于
Not	取反

Resource 还可以使用 and 和 or 来组合多个过滤器。例如：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=Make eq 'BYD' and Date lt '2023-07-01'

Resource 可以将 startswith, endswith, toupper, tolower, 和 contains 函数与 $filter 查询选项一起使用。例如，以下请求返回其属性包含指定子字符串的 Resource ：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=contains(Make,'BYD')

选择属性

要检索属性的子集，请使用 $select，如以下示例所示：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$select=Id,Model

这将返回与请求中的过滤器匹配的所有 Resource 的 Id 和 Model 属性。

Resource 还可以检索单个 Resource 的单独属性值，如以下示例所示：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')/Model/$value

排序

Resource 可以使用 $orderby 对 Resource 进行排序，如下例所示：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$orderby=Model asc, Color desc

这将返回按型号（升序）排序的 Resource ，然后按颜色（降序）排序的 Resource 。

分页

服务器端

该应用程序支持服务器端分页。在 设置 > 服务器 中启用此选项。当页面大小大于 0 并且请求返回的结果大于页面大小时，下一页结果的 URL 将包含在响应的 @odata.nextlink 属性中。结果的最后一页不包含此属性。此 URL 包含一个寻呼令牌，该令牌在接下来的两分钟内保持有效。例如，以下响应具有三个 Resource 和一个包含下一页记录的 URL 的 @odata.nextLink 属性：

{
  "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ],
  "@odata.nextLink":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$skiptoken=0f87696b-aa28-4a70-b13d-c86af8338c80"
}

客户端

知行之桥还支持使用 $top, $skip, 和 $count 的客户端分页。

Resource 可以使用 $top=n 仅包含结果中的前 n 个 Resource 。例如，使用以下请求显示前十名的汽车 Resource ：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10

Resource 可以使用 $skip=n 从结果中排除前 n 个 Resource 。 Resource 可以使用 $top 和 $skip 来实现客户端分页。 $skip 始终在 $top 之前应用，无论它们在查询中的顺序如何。例如，以下两个查询检索两个页面中的前 20 个 Resource ：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10&$skip=10

Resource 可以将 $count 设置为 true 以返回结果中的记录总数。如果 Resource 使用的是 OData 版本 2.0 或 3.0，则可以将 $inlinecount 设置为 allpages 。例如，考虑以下查询：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=3&$skip=4&$count=true

此查询可能会返回如下响应：

{
  "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "@odata.count": 402,
	"value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ],
  "@odata.nextLink":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Account?$skip=7"
}

与过滤器匹配的总计数与单页结果一起在响应中返回。

仅计数

Resource 可以仅检索与查询匹配特定过滤器的 Resource 计数，如以下示例所示：

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$count=true&$filter=Make eq 'BYD'

响应是与请求中的过滤器匹配的 Resource 的原始计数。