要求と応答の API トランザクション
Deploy API 呼び出しはすべて、 Deploy 仮想マシンへの HTTP 要求として実行され、クライアントへの関連する応答が生成されます。この要求と応答のペアで API トランザクションが構成されます。Deploy API を使用する前に、要求の制御に使用できる入力変数と応答出力の内容を理解しておく必要があります。
API 要求を制御する入力変数
API 呼び出しの処理方法は、 HTTP 要求で設定されたパラメータを使用して制御できます。
要求ヘッダー
HTTP 要求には、次のようなヘッダーを含める必要があります。
-
コンテンツタイプ
要求の本文にJSONが含まれている場合は、このヘッダーをapplication/jsonに設定する必要があります。 -
同意する
応答の本文にJSONが含まれる場合は、このヘッダーをapplication/jsonに設定する必要があります。 -
許可
base64文字列でエンコードされたユーザ名とパスワードを使用してベーシック認証を設定する必要があります。
本文を要求します
要求の本文の内容は、それぞれの呼び出しに応じて異なります。HTTP 要求の本文は、次のいずれかで構成されます。
-
JSON オブジェクトと入力変数(新しいクラスタの名前など)
-
空です
オブジェクトのフィルタ
GET を使用する API 呼び出しを発行する際、返されるオブジェクトを任意の属性に基づいて制限またはフィルタできます。たとえば、一致する正確な値を指定できます。
<field>=<query value>
完全一致に加えて、他の演算子を使用して、一連のオブジェクトを一定範囲の値で返すことができます。ONTAP Select では、次のフィルタ演算子がサポートされています。
演算子 | 説明 |
---|---|
= |
等しい |
< |
より小さい |
> |
が次の値より大きい |
⇐ |
が次の値以下です |
>= |
が次の値以上である必要があります |
または |
|
! |
と等しくない |
* |
すべてに一致するワイルドカード |
また、 null キーワードまたはその否定 (!null) をクエリの一部として使用して、特定のフィールドが設定されているかどうかに基づいてオブジェクトのセットを返すこともできます。
オブジェクトフィールドの選択
デフォルトでは、 GET を使用する API 呼び出しを発行すると、オブジェクトを一意に識別する属性のみが返されます。この最小のフィールドセットは、各オブジェクトのキーとして機能し、オブジェクトタイプによって異なります。fields query パラメータを使用すると、次の方法で追加のオブジェクトプロパティを選択できます。
-
安価なフィールド
を指定しますfields=*
ローカルサーバメモリに保持されているオブジェクトフィールドを取得するか、アクセスにほとんど処理を必要としないオブジェクトフィールドを取得します。 -
高価なフィールド
を指定しますfields=**
にアクセスするために追加のサーバ処理が必要なフィールドも含め、すべてのオブジェクトフィールドを取得します。 -
カスタムフィールドの選択
使用fields=FIELDNAME
必要な正確なフィールドを指定します。複数のフィールドを要求する場合は、スペースを入れずにカンマで区切る必要があります。
ベストプラクティスとして、必要なフィールドを常に個別に指定することを推奨します。安価なフィールドや高コストのフィールドは、必要な場合にのみ取得してください。低コストでコストな分類は、ネットアップが社内パフォーマンス分析に基づいて決定します。特定のフィールドの分類は、いつでも変更できます。 |
出力セット内のオブジェクトをソートする
リソースコレクション内のレコードは、オブジェクトによって定義されたデフォルトの順序で返されます。次のように'フィールド名とソート方向を指定した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 応答には、次のようなヘッダーが含まれています。
-
要求ID
成功するたびに、一意の要求識別子が割り当てられます。 -
場所
オブジェクトが作成されると、一意のオブジェクトIDを含む新しいオブジェクトへの完全なURLが格納されます。
応答の本文
API 要求に関連する応答の内容は、オブジェクト、処理タイプ、および要求の成功または失敗によって異なります。応答の本文は JSON 形式になります。
-
単一のオブジェクト
1 つのオブジェクトを要求に基づいて一連のフィールドとともに返すことができます。たとえば、 GET では、一意の識別子を使用してクラスタの選択したプロパティを取得できます。 -
複数のオブジェクト
リソースコレクションから複数のオブジェクトを返すことができます。いずれの場合も、で一貫した形式が使用されますnum_records
オブジェクトインスタンスの配列を含むレコードとレコードの数を示します。たとえば、特定のクラスタに定義されているすべてのノードを取得できます。 -
ジョブオブジェクト
API 呼び出しが非同期で処理されると、バックグラウンドタスクのアンカーを設定するジョブオブジェクトが返されます。たとえば、クラスタの導入に使用された POST 要求は非同期で処理され、ジョブオブジェクトが返されます。 -
エラーオブジェクト
エラーが発生した場合は、常にエラーオブジェクトが返されます。たとえば、既存の名前を使用してクラスタを作成しようとするとエラーが表示されます。 -
空です
場合によっては、データが返されず、応答の本文が空になることがあります。たとえば、 DELETE を使用して既存のホストを削除したあとは、応答の本文が空になります。