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

回應是與請求中的過濾器匹配的資源的原始計數。