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