Skip to main content
本繁體中文版使用機器翻譯，譯文僅供參考，若與英文版本牴觸，應以英文版本為準。

要求及回應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

例如，您可以依遞減順序排序類型欄位，然後依遞增順序排序識別碼：
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

已接受

執行要求的背景工作已開始執行、但作業尚未完成。

400

錯誤要求

無法辨識或不適當的要求輸入。

403

禁止

由於授權錯誤、存取遭拒。

404

找不到

要求中提及的資源不存在。

405

不允許使用方法

資源不支援要求中的HTTP動詞。

409

衝突

建立物件的嘗試失敗、因為物件已經存在。

500

內部錯誤

伺服器發生一般內部錯誤。

501

未實作

URI已知但無法執行要求。

回應標頭

部署伺服器產生的HTTP回應中包含數個標頭、包括：

  • 每個成功的API要求都會指派一個唯一的要求識別碼。

  • 位置建立物件時、位置標頭會包含新物件的完整URL、包括唯一物件識別碼。

回應本文

與API要求相關的回應內容會因物件、處理類型、以及要求的成功或失敗而有所不同。回應本文會以Json呈現。

  • 單一物件單一物件可根據要求傳回一組欄位。例如、您可以使用「Get」（取得）、使用唯一識別碼擷取叢集的選定內容。

  • 可從資源集合傳回多個物件。在所有情況下、都會使用一致的格式、並 num_records 指出包含物件執行個體陣列的記錄和記錄數目。例如、您可以擷取在特定叢集中定義的所有節點。

  • 工作物件如果API呼叫以非同步方式處理、則會傳回工作物件來固定背景工作。例如、用於部署叢集的POST要求會以非同步方式處理、並傳回工作物件。

  • 錯誤物件如果發生錯誤、一律會傳回錯誤物件。例如、當您嘗試建立已存在名稱的叢集時、會收到錯誤訊息。

  • 在某些情況下為空白、不會傳回任何資料、回應本文則為空白。例如、使用DELETE刪除現有主機之後、回應本文為空白。