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

ONTAP Select 的請求和回應 API 交易

PDF

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

控制 API 要求的輸入變數

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

請求標頭

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

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

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

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

請求本文

請求本文的內容會因特定呼叫而異。HTTP 請求本文包含下列其中一項：

  • 包含輸入變數（例如新叢集的名稱）的 JSON 物件

  • 空白

篩選物件

使用 GET 方法發出 API 呼叫時，您可以根據任何屬性限制或篩選傳回的物件。例如，您可以指定要匹配的確切值：

<field>=<query value>

除了精確匹配之外，還有其他運算子可用於傳回一組值範圍內的物件。ONTAP 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 狀態碼

以下說明 Deploy REST API 所使用的 HTTP 狀態碼。

程式碼 意義 說明

200

確定

表示不會建立新物件的呼叫成功。

201

已建立

已成功建立物件；位置回應標頭包含物件的唯一識別碼。

202

已接受

已啟動長時間執行的背景工作來執行要求，但作業尚未完成。

400

錯誤的請求

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

403

禁止

由於授權錯誤，存取被拒絕。

404

找不到

請求中引用的資源不存在。

405

不允許使用此方法

此資源不支援請求中的 HTTP 謂詞。

409

衝突

嘗試建立物件失敗，因為該物件已存在。

500

內部錯誤

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

501

未實作

URI 已知，但無法執行請求。

回應標頭

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

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

  • location 當建立物件時，location 標頭包含新物件的完整 URL，包括唯一的物件識別碼。

回應本文

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

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

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

  • Job 物件如果 API 呼叫是非同步處理的，則會傳回一個 Job 物件，該物件用於錨定背景工作。例如，用於部署叢集的 POST 要求是非同步處理的，並傳回一個 Job 物件。

  • Error 物件如果發生錯誤，則會始終傳回 Error 物件。例如，嘗試建立名稱已存在的叢集時，將會收到錯誤。

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