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'
回應是與請求中的過濾器匹配的資源的原始計數。