ONTAP Select のリクエストとレスポンスの API トランザクション
Deploy API呼び出しはすべて、Deploy仮想マシンへのHTTPリクエストとして実行され、その仮想マシンはクライアントに対して関連する応答を生成します。このリクエストとレスポンスのペアは、APIトランザクションとみなされます。Deploy APIを使用する前に、リクエストを制御するために使用できる入力変数と、レスポンス出力の内容について理解しておく必要があります。
API要求を制御する入力変数
HTTPリクエストに設定されたパラメータを通して、API呼び出しの処理方法を制御できます。
要求ヘッダー
HTTPリクエストには、以下のヘッダーを含める必要があります:
-
content-type リクエスト本文に JSON が含まれる場合、このヘッダーは application/json に設定する必要があります。
-
accept レスポンスボディに JSON が含まれる場合、このヘッダーは application/json に設定する必要があります。
-
authorization 基本認証は、ユーザー名とパスワードをbase64文字列でエンコードして設定する必要があります。
要求の本文
要求の本文の内容は、それぞれの呼び出しに応じて異なります。HTTP要求の本文は、次のいずれかで構成されます。
-
入力変数(新しいクラスタの名前など)を含むJSONオブジェクト
-
空の
オブジェクトをフィルタリング
GETを使用するAPI呼び出しを発行する際、返されるオブジェクトを任意の属性に基づいて制限またはフィルタできます。たとえば、一致する完全な値を指定できます。
<field>=<query value>
完全一致に加えて、値の範囲にわたるオブジェクトのセットを返すための他の演算子も利用可能です。ONTAP Selectは以下のフィルタリング演算子をサポートしています。
| 演算子 | 説明 |
|---|---|
= |
等しい |
< |
小なり |
> |
より大きい |
⇐ |
次の値以下 |
>= |
次の値以上 |
または |
|
! |
等しくない |
* |
すべてに一致するワイルドカード |
また、nullキーワードまたはその否定(!null)をクエリの一部として使用することで、特定のフィールドが設定されているかどうかに基づいてオブジェクトのセットを返すこともできます。
オブジェクトフィールドの選択
デフォルトでは、GETメソッドを使用してAPI呼び出しを行うと、オブジェクトを一意に識別する属性のみが返されます。この最小限のフィールドセットは、各オブジェクトのキーとして機能し、オブジェクトの種類によって異なります。フィールドクエリパラメータを使用して、以下の方法で追加のオブジェクトプロパティを選択できます:
-
安価なフィールドを指定 `fields=*`して、ローカルサーバーのメモリに保持されている、またはアクセスにほとんど処理を必要としないオブジェクトフィールドを取得します。
-
高価なフィールド `fields=**`を指定して、追加のサーバー処理が必要なフィールドを含むすべてのオブジェクトフィールドを取得します。
-
カスタムフィールドの選択 `fields=FIELDNAME`を使用して、希望するフィールドを正確に指定してください。複数のフィールドを要求する場合は、値をスペースを入れずにカンマで区切る必要があります。
|
|
ベストプラクティスとして、必要な特定のフィールドを常に特定する必要があります。安価なフィールドまたは高価なフィールドのセットは、必要な場合にのみ取得してください。安価および高価の分類は、内部パフォーマンス分析に基づいてNetAppによって決定されます。特定のフィールドの分類はいつでも変更される可能性があります。 |
出力セット内のオブジェクトをソートします
リソースコレクション内のレコードは、オブジェクトによって定義されたデフォルトの順序で返されます。order_byクエリパラメータにフィールド名とソート方向を指定して、順序を変更できます。
order_by=<field name> asc|desc
例えば、typeフィールドを降順でソートし、次に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 ステータスコードを以下に説明します。
| Code | 説明 | 説明 |
|---|---|---|
200 |
OK |
新しいオブジェクトを作成しない呼び出しが成功したことを示します。 |
201 |
Created |
オブジェクトが正常に作成されました。ロケーション応答ヘッダーには、オブジェクトの一意の識子が含まれています。 |
202 |
Accepted |
リクエストを実行するために長時間実行されるバックグラウンドジョブが開始されましたが、処理はまだ完了していません。 |
400 |
Bad request |
要求の入力が認識されないか不適切です。 |
403 |
Forbidden |
認証エラーのためアクセスが拒否されました。 |
404 |
Not found |
要求で参照されているリソースが存在しません。 |
405 |
Method not allowed |
リクエストで使用されているHTTP動詞は、このリソースではサポートされていません。 |
409 |
競合 |
オブジェクトがすでに存在するため、オブジェクトの作成に失敗しました。 |
500 |
内部エラー |
サーバで一般的な内部エラーが発生しました。 |
501 |
未実装 |
URIは既知だが、リクエストを実行する能力がない。 |
応答ヘッダー
Deployサーバーによって生成されるHTTPレスポンスには、以下のヘッダーが含まれます:
-
request-id 成功したすべてのAPIリクエストには、一意のリクエスト識別子が割り当てられます。
-
オブジェクトが作成されると、location ヘッダーには、一意のオブジェクト識別子を含む、新しいオブジェクトへの完全な URL が含まれます。
応答の本文
APIリクエストに関連付けられたレスポンスの内容は、オブジェクト、処理タイプ、およびリクエストの成功または失敗によって異なります。レスポンスボディはJSON形式で出力されます。
-
単一オブジェクト リクエストに基づいて、一連のフィールドを持つ単一のオブジェクトが返されます。例えば、GETを使用して、一意の識別子を用いてクラスタの選択したプロパティを取得できます。
-
複数のオブジェクト リソースコレクションから複数のオブジェクトを返すことができます。いずれの場合も、一貫した形式が使用され、 `num_records`でレコード数が示され、recordsにオブジェクトインスタンスの配列が含まれます。たとえば、特定のクラスタで定義されているすべてのノードを取得できます。
-
Jobオブジェクト API呼び出しが非同期で処理される場合、バックグラウンドタスクのアンカーとなるJobオブジェクトが返されます。例えば、クラスタの導入に使用されるPOSTリクエストは非同期で処理され、Jobオブジェクトが返されます。
-
エラーオブジェクト エラーが発生した場合は、必ずエラーオブジェクトが返されます。たとえば、すでに存在する名前でクラスタを作成しようとすると、エラーが発生します。
-
空の場合:場合によってはデータが返されず、レスポンスボディが空になります。例えば、DELETEを使用して既存のホストを削除した場合、レスポンスボディは空になります。