要求と応答のAPIトランザクション
変更を提案
PDF
Deploy API 呼び出しはすべて、 Deploy 仮想マシンへの HTTP 要求として実行され、クライアントへの関連する応答が生成されます。この要求と応答のペアはAPIトランザクションとみなされます。Deploy API を使用する前に、要求の制御に使用できる入力変数と応答出力の内容を理解しておく必要があります。
API要求を制御する入力変数
API 呼び出しの処理方法は、 HTTP 要求で設定されたパラメータを使用して制御できます。
要求ヘッダー
HTTP 要求には、次のようなヘッダーを含める必要があります。
-
content-type 要求の本文に 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
たとえば、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 ステータスコードを次に示します。
| コード | 意味 | 製品説明 |
|---|---|---|
200 |
OK |
新しいオブジェクトを作成しない呼び出しが成功したことを示します。 |
201 |
作成済み |
オブジェクトが作成されました。場所の応答ヘッダーにはオブジェクトの一意の識別子が含まれています。 |
202 |
承認済み |
長時間のバックグラウンドジョブで要求の実行が開始されましたが、処理はまだ完了していません。 |
400 |
無効な要求です |
要求の入力が認識されないか不適切です。 |
403 |
禁止 |
認証エラーによりアクセスが拒否されました。 |
404 |
見つかりません |
要求で参照されているリソースが存在しません。 |
405 |
許可されていないメソッド |
要求内の HTTP 動詞はリソースでサポートされていません。 |
409 |
競合 |
オブジェクトがすでに存在するため、オブジェクトの作成に失敗しました。 |
500 |
内部エラー |
サーバで一般的な内部エラーが発生しました。 |
501 |
実装されていません |
URI は既知ですが、要求を実行できません。 |
応答ヘッダー
Deploy サーバによって生成される HTTP 応答には、次のようなヘッダーが含まれています。
-
request-id 成功したすべての API 要求には、一意の要求 ID が割り当てられます。
-
Location ：オブジェクトが作成されると、一意のオブジェクト識別子を含む新しいオブジェクトへの完全な URL が格納されます。
応答の本文
API 要求に関連する応答の内容は、オブジェクト、処理タイプ、および要求の成功または失敗によって異なります。応答の本文は JSON 形式になります。
-
単一のオブジェクト単一のオブジェクトを要求に基づいて一連のフィールドとともに返すことができます。たとえば、GETを使用すると、一意の識別子を使用してクラスタの選択したプロパティを取得できます。
-
リソースコレクションから複数のオブジェクトを返すことができます。いずれの場合も、オブジェクトインスタンスの配列を含むレコードとレコードの数を示す一貫した形式が使用され
num_recordsます。たとえば、特定のクラスタに定義されているすべてのノードを取得できます。 -
ジョブオブジェクト API 呼び出しが非同期で処理されると、バックグラウンドタスクのアンカーを設定するジョブオブジェクトが返されます。たとえば、クラスタの導入に使用された POST 要求は非同期で処理され、ジョブオブジェクトが返されます。
-
エラーオブジェクトエラーが発生した場合は、常にエラーオブジェクトが返されます。たとえば、既存の名前を使用してクラスタを作成しようとするとエラーが表示されます。
-
空の場合もあります。データが返されず、応答の本文が空になっていることもあります。たとえば、 DELETE を使用して既存のホストを削除したあとは、応答の本文が空になります。