> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 资源

> API 端口的 HTTP 方法、过滤、排序和分页。

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

## HTTP 方法

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

### GET

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

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

这是相应的响应：

```json theme={null}
{
  "@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

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

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

这是相应的响应：

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

### PUT

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

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

这是相应的响应：

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

### 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'`

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

| 运算符 | 描述    |
| --- | ----- |
| Eq  | 等于    |
| Ne  | 不等于   |
| Gt  | 大于    |
| Ge  | 大于或等于 |
| Lt  | 小于    |
| Le  | 小于或等于 |
| Not | 取反    |

还可以使用 `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 属性：

```json theme={null}
{
  "@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` 的客户端分页。

可以使用 `$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`

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

```json theme={null}
{
  "@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"
}
```

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

### 仅计数

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

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

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