Skip to main content
此產品有較新版本可以使用。
本繁體中文版使用機器翻譯,譯文僅供參考,若與英文版本牴觸,應以英文版本為準。

要求及回應API交易

貢獻者

每個部署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刪除現有主機之後、回應本文為空白。