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

ONTAP Select的請求和回應 API 事務

PDF

每個 Deploy API 呼叫都會以 HTTP 請求的形式傳送到 Deploy 虛擬機，並產生相關的回應傳回給客戶端。此請求/回應對被視為一次 API 事務。在使用 Deploy API 之前，您應該熟悉可用於控制請求的輸入變數以及回應輸出的內容。

控制 API 請求的輸入變數

您可以透過 HTTP 請求中設定的參數來控制如何處理 API 呼叫。

請求標頭

您必須在 HTTP 請求中包含幾個標頭，其中包括：

  • content-type 如果請求主體包含 JSON，則此標頭必須設定為 application/json。

  • accept 如果回應主體將包含 JSON，則此標頭必須設定為 application/json。

  • 授權必須使用以 base64 字串編碼的使用者名稱和密碼設定基本驗證。

請求正文

請求主體的內容根據具體呼叫而有所不同。 HTTP請求主體由以下之一組成：

  • 帶有輸入變數的 JSON 物件（例如，新叢集的名稱）

  • 空的

篩選對象

發出使用 GET 的 API 呼叫時，您可以根據任意屬性限製或過濾傳回的物件。例如，您可以指定要符合的精確值：

<field>=<query value>

除了完全匹配之外，還有其他運算子可用於傳回一組包含特定值範圍的物件。 ONTAPONTAP Select支援以下篩選運算子。

操作員 描述

=

等於

<

少於

>

大於

⇐

小於或等於

>=

大於或等於

或者

！

不等於

*

貪婪通配符

您也可以透過使用 null 關鍵字或其否定（！null）作為查詢的一部分，根據特定欄位是否設定來傳回一組物件。

選擇對象字段

預設情況下，使用 GET 發出 API 呼叫僅傳回唯一標識一個或多個物件的屬性。這組最小欄位將充當每個物件的鍵，並根據物件類型而有所不同。您可以使用 fields 查詢參數透過以下方式選擇其他物件屬性：

  • 廉價字段指定 `fields=*`檢索在本機伺服器記憶體中維護或幾乎不需要處理即可存取的物件欄位。

  • 昂貴字段指定 `fields=**`檢索所有物件字段，包括那些需要額外的伺服器處理才能存取的字段。

  • 自訂欄位選擇使用 `fields=FIELDNAME`指定您想要的確切欄位。請求多個欄位時，必須使用逗號分隔值，且不能使用空格。

提示 作為最佳實踐，您應該始終識別所需的特定欄位。您應僅在需要時檢索廉價或昂貴欄位集。廉價和昂貴的分類由NetApp根據內部效能分析決定。給定字段的分類可能隨時變更。

對輸出集中的物件進行排序

資源集合中的記錄將按照物件定義的預設順序傳回。您可以使用 order_by 查詢參數，並附帶欄位名稱和排序方向來變更順序，如下所示：
order_by=<field name> asc|desc

例如，您可以按降序對類型欄位進行排序，然後按升序對 id 進行排序：
order_by=type desc, id asc

當包含多個參數時，必須用逗號分隔欄位。

分頁

使用 GET 方式發出 API 呼叫來存取相同類型的物件集合時，預設會傳回所有符合的物件。如有需要，您可以使用請求中的 max_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 已知但無法執行請求。

響應標頭

Deploy 伺服器產生的 HTTP 回應中包含幾個標頭，包括：

  • request-id 每個成功的 API 請求都會指派一個唯一的請求識別碼。

  • 位置 當建立物件時，位置標頭包含新物件的完整 URL，其中包含唯一物件識別碼。

回應正文

與 API 請求相關的回應內容會根據物件、處理類型以及請求的成功或失敗而有所不同。回應主體以 JSON 格式呈現。

  • 單一物件：可以根據請求傳回包含一組欄位的單一物件。例如，您可以使用 GET 操作，透過唯一識別碼檢索叢集的選定屬性。

  • 多個物件 可以傳回資源集合中的多個物件。在所有情況下，都使用一致的格式， `num_records`指示記錄數以及包含物件實例陣列的記錄。例如，您可以檢索特定叢集中定義的所有節點。

  • Job 物件如果 API 呼叫是非同步處理的，則會傳回一個 Job 對象，該物件用於錨定後台任務。例如，用於部署叢集的 POST 請求是非同步處理的，並傳回一個 Job 物件。

  • 錯誤物件 如果發生錯誤，則總是會傳回一個 Error 物件。例如，當您嘗試建立名稱已存在的叢集時，就會收到錯誤。

  • 空 某些情況下，沒有回傳任何數據，響應體為空，例如使用 DELETE 刪除一個已經存在的主機，響應體為空。