控制API要求的輸入變數
您可以透過HTTP要求中設定的參數和變數來控制API呼叫的處理方式。
HTTP方法
下表顯示了由REST API支援的HTTP方法ONTAP 。
並非所有的HTTP方法都可在每個REST端點上使用。此外、修補程式和刪除功能也可用於集合。如需詳細資訊、請參閱_Object參考資料和access_。 |
HTTP方法 | 說明 |
---|---|
取得 |
擷取資源執行個體或集合上的物件屬性。 |
貼文 |
根據提供的輸入建立新的資源執行個體。 |
修補程式 |
根據提供的輸入內容更新現有的資源執行個體。 |
刪除 |
刪除現有的資源執行個體。 |
標題 |
有效發出GET要求、但僅傳回HTTP標頭。 |
選項 |
判斷特定端點支援哪些HTTP方法。 |
路徑變數
每個 REST API 呼叫所使用的端點路徑可以包含各種識別碼。每個 ID 對應特定的資源執行個體。範例包括叢集 ID 和 SVM ID 。
要求標頭
您必須在HTTP要求中包含多個標頭。
- 內容類型
-
如果申請本文包含Json、則此標頭必須設定為「application/json」。
- 接受
-
此標頭應設定為「application/hal+json」。如果改為「application/json」、則除了擷取下一批記錄所需的連結之外、不會傳回任何的HAL連結。如果標頭是這兩個值以外的其他值、則回應中「content-type」標頭的預設值為「application/hal+json」。
- 授權
-
基本驗證必須使用編碼為基礎64字串的使用者名稱和密碼來設定。例如:
Authorization: Basic YWRtaW46cGV0ZXJzb24=
。
申請本文
申請本文的內容會因特定通話而有所不同。HTTP要求本文包含下列其中一項:
-
具有輸入變數的Json物件
-
清空Json物件
篩選物件
使用 GET 方法發出 API 呼叫時、您可以使用查詢參數、根據任何屬性來限制或篩選傳回的物件。
一組或多個參數可以附加到 URL 字串、從開始於 ?
字元。如果提供多個參數、則會根據分割查詢參數 &
字元。參數中的每個機碼和值都會在分割 =
字元。
例如、您可以使用等號來指定完全符合的值:
<field>=<value>
對於較複雜的查詢、額外的運算子會置於等號之後。例如、若要根據大於或等於某個值的特定欄位來選取物件集、查詢將是:
<field>=>=<value>
除了上述範例之外、還有其他運算子可用於傳回超過某個值範圍的物件。ONTAP REST API 支援的篩選運算子摘要如下表所示。
任何未設定的欄位通常都會排除在相符查詢之外。 |
營運者 |
說明 |
= |
等於 |
< |
小於 |
> |
大於 |
<= |
小於或等於 |
>= |
大於或等於 |
! |
不等於 |
* |
貪婪的萬用字元 |
您也可以使用「null」關鍵字或其否定詞「!null」作為查詢的一部分、根據是否設定特定欄位來傳回物件集合。
以下是本網站 REST API 工作流程的一些範例。
-
根據篩選
state
變數以選取備用磁碟。
要求特定物件欄位
根據預設、使用Get發出API呼叫時、只會傳回唯一識別物件的屬性、以及可用的HAL自我連結。這組最小欄位可做為每個物件的金鑰、而且會根據物件類型而有所不同。您可以使用「功能變數」查詢參數、以下列方式選取其他物件內容:
-
一般或標準欄位
指定「Fields =*」以擷取最常用的物件欄位。這些欄位通常會保留在本機伺服器記憶體中、或只需少量處理即可存取。使用Get搭配URL路徑金鑰(UUID)之後、傳回的物件內容相同。
-
所有欄位
指定「Fields =」以擷取所有物件欄位、包括需要額外伺服器處理才能存取的欄位。
-
自訂欄位選擇
使用「field=<field_name>'」來指定所需的確切欄位。要求多個欄位時、必須使用不含空格的逗號分隔值。
最佳實務做法是、務必找出您想要的特定欄位。您只能在需要時擷取一組通用欄位或所有欄位。哪些欄位屬於一般欄位、並使用「Fields =*」傳回、由NetApp根據內部效能分析來決定。欄位的分類可能會在未來的版本中變更。
排序輸出集中的物件
資源集合中的記錄會以物件定義的預設順序傳回。您可以使用「order_by」查詢參數、以下列欄位名稱和排序方向來變更順序:
「order_by=<欄位名稱> asc|desc」
例如、您可以依遞增順序、以遞減順序排序類型欄位、然後依ID排序:
「order_by=type desc、id asc」
請注意下列事項:
-
如果您指定排序欄位但未提供方向、則會以遞增順序排序這些值。
-
包含多個參數時、您必須以逗號分隔欄位。
擷取集合中的物件時分頁
使用Get存取同一類型物件的集合時發出API呼叫ONTAP 、根據兩個限制、嘗試傳回盡可能多的物件。您可以使用要求上的其他查詢參數來控制這些限制。針對特定Get要求所達成的第一個限制會終止要求、因此會限制傳回的記錄數目。
如果要求在重複所有物件之前結束、回應會包含擷取下一批記錄所需的連結。 |
- 限制物件數量
-
根據預設、ONTAP 針對Get要求、最多可傳回10、000個物件。您可以使用「max_Records」查詢參數來變更此限制。例如:
"Marax_Records=20"
實際傳回的物件數目可能會低於有效的最大值、取決於相關的時間限制、以及系統中的物件總數。
- 限制擷取物件所用的時間
-
根據預設、ONTAP 在允許的取得要求時間內、將盡可能多的物件傳回。預設的逾時時間為15秒。您可以使用「RETON_Timeout」查詢參數來變更此限制。例如:
"RETON_Timeout=5"
實際傳回的物件數目可能會低於有效的最大值、這是根據物件數目的相關限制、以及系統中的物件總數而定。
- 縮小結果集
-
如有需要、您可以將這兩個參數與其他查詢參數結合、以縮小結果集範圍。例如、下列項目最多會傳回指定時間之後產生的10個EMS事件:
time=> 2018-04-04T15:41:29.140265Z&max_records=10
您可以針對物件發出多個分頁要求。每次後續的API呼叫都應根據最後結果集中的最新事件、使用新的時間值。
大小屬性
某些API呼叫所使用的輸入值以及某些查詢參數均為數值。您可以選擇使用下表所示的字尾、而不是提供以位元組為單位的整數。
後置 | 說明 |
---|---|
KB |
KB千位元組(1024位元組)或Kibibibyte |
MB |
MB MB(KB x 1024位元組)或百萬位元組 |
GB |
GB GB GB(MB x 1024位元組)或GB |
TB |
TB TB TB(GB x 1024位元組)或TB位元組 |
PB |
PB PB PB(TB x 1024位元組)或pibibbytes |