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