要求及回應API交易
建議變更
PDF
每個部署API呼叫都會以HTTP要求的形式執行、以供部署虛擬機器產生與用戶端相關的回應。此要求/回應配對被視為API交易。在使用部署API之前、您應該先熟悉可用於控制要求的輸入變數、以及回應輸出的內容。
控制API要求的輸入變數
您可以透過HTTP要求中設定的參數來控制API呼叫的處理方式。
要求標頭
您必須在HTTP要求中包含多個標頭、包括：
-
內容類型
如果要求主體包含 JSON 、則必須將此標頭設定為 application/json 。 -
接受
如果回應本文將包含 JSON 、則必須將此標頭設定為 application/json 。 -
授權
必須使用以 base64 字串編碼的使用者名稱和密碼來設定基本驗證。
申請本文
申請本文的內容會因特定通話而有所不同。HTTP要求本文包含下列其中一項：
-
具有輸入變數的Json物件（例如新叢集的名稱）
-
空白
篩選物件
發出使用Get的API呼叫時、您可以根據任何屬性來限制或篩選傳回的物件。例如、您可以指定要符合的確切值：
<field>=<query value>
除了完全符合的項目、還有其他運算子可以傳回一系列值的一組物件。支援下列篩選操作員。ONTAP Select
| 營運者 | 說明 |
|---|---|
= |
等於 |
< |
小於 |
> |
大於 |
&l;= |
小於或等於 |
>= |
大於或等於 |
或 |
|
！ |
不等於 |
* |
貪婪的萬用字元 |
您也可以使用null關鍵字或其否定（！null）做為查詢的一部分、根據是否設定特定欄位來傳回一組物件。
選取物件欄位
根據預設、使用Get發出API呼叫時、只會傳回唯一識別物件的屬性。這組最小欄位可做為每個物件的金鑰、而且會根據物件類型而有所不同。您可以使用「欄位查詢」參數、以下列方式選取其他物件屬性：
-
經濟實惠的欄位
指定fields=*擷取在本機伺服器記憶體中維護的物件欄位、或只需少量處理即可存取。 -
昂貴的領域
指定fields=**擷取所有物件欄位、包括需要額外伺服器處理才能存取的欄位。 -
自訂欄位選擇
使用fields=FIELDNAME指定您要的確切欄位。要求多個欄位時、必須使用不含空格的逗號分隔值。
|
最佳實務做法是、務必找出您想要的特定欄位。您只能在需要時擷取一組廉價或昂貴的欄位。價格低廉且昂貴的分類是由NetApp根據內部效能分析所決定。特定欄位的分類可隨時變更。 |
排序輸出集中的物件
資源集合中的記錄會以物件定義的預設順序傳回。您可以使用 order_by 查詢參數變更訂單、並使用欄位名稱和排序方向、如下所示：
order_by=<field name> asc|desc
例如、您可以依遞增順序、以遞減順序排序類型欄位、然後依ID排序：
order_by=type desc, id asc
包含多個參數時、您必須以逗號分隔欄位。
分頁
使用Get存取同一類型物件的集合時發出API呼叫、預設會傳回所有相符的物件。如有需要、您可以使用main_Records查詢參數搭配要求來限制傳回的記錄數。例如：
max_records=20
如有需要、您可以將此參數與其他查詢參數合併、以縮小結果集範圍。例如、下列項目最多會傳回指定時間之後產生的 10 個系統事件：
time⇒ 2019-04-04T15:41:29.140265Z&max_records=10
您可以針對事件（或任何物件類型）發出多個分頁要求。每次後續的API呼叫都應根據最後結果集中的最新事件、使用新的時間值。
解讀API回應
每個API要求都會對用戶端產生回應。您可以檢查回應以判斷
是否成功、並視需要擷取其他資料。
HTTP狀態代碼
部署REST API所使用的HTTP狀態代碼如下所述。
| 程式碼 | 意義 | 說明 |
|---|---|---|
200 |
好的 |
表示未建立新物件的通話成功。 |
201 |
已建立 |
已成功建立物件；位置回應標頭包含物件的唯一識別碼。 |
202.02 |
已接受 |
執行要求的背景工作已開始執行、但作業尚未完成。 |
400 |
錯誤要求 |
無法辨識或不適當的要求輸入。 |
403. |
禁止 |
由於授權錯誤、存取遭拒。 |
404.04 |
找不到 |
要求中提及的資源不存在。 |
405 |
不允許使用方法 |
資源不支援要求中的HTTP動詞。 |
409. |
衝突 |
建立物件的嘗試失敗、因為物件已經存在。 |
500 |
內部錯誤 |
伺服器發生一般內部錯誤。 |
501.. |
未實作 |
URI已知但無法執行要求。 |
回應標頭
部署伺服器產生的HTTP回應中包含數個標頭、包括：
-
要求識別碼
每個成功的 API 要求都會指派唯一的要求識別碼。 -
位置
建立物件時、位置標頭會包含新物件的完整 URL 、包括唯一物件識別碼。
回應本文
與API要求相關的回應內容會因物件、處理類型、以及要求的成功或失敗而有所不同。回應本文會以Json呈現。
-
單一物件
單一物件可根據要求傳回一組欄位。例如、您可以使用「Get」（取得）、使用唯一識別碼擷取叢集的選定內容。 -
多個物件
可從資源集合傳回多個物件。在任何情況下、都會使用一致的格式num_records指出包含物件執行個體陣列的記錄和記錄數。例如、您可以擷取在特定叢集中定義的所有節點。 -
工作物件
如果API呼叫以非同步方式處理、則會傳回工作物件、以固定背景工作。例如、用於部署叢集的POST要求會以非同步方式處理、並傳回工作物件。 -
錯誤物件
如果發生錯誤、一律會傳回錯誤物件。例如、當您嘗試建立已存在名稱的叢集時、會收到錯誤訊息。 -
空白
在某些情況下、不會傳回任何資料、回應本文是空的。例如、使用DELETE刪除現有主機之後、回應本文為空白。