日本語は機械翻訳による参考訳です。内容に矛盾や不一致があった場合には、英語の内容が優先されます。

要求と応答の API トランザクション

寄稿者

Deploy API 呼び出しはすべて、 Deploy 仮想マシンへの HTTP 要求として実行され、クライアントへの関連する応答が生成されます。この要求と応答のペアで API トランザクションが構成されます。Deploy API を使用する前に、要求の制御に使用できる入力変数と応答出力の内容を理解しておく必要があります。

API 要求を制御する入力変数

API 呼び出しの処理方法は、 HTTP 要求で設定されたパラメータを使用して制御できます。

要求ヘッダー

HTTP 要求には、次のようなヘッダーを含める必要があります。

  • content-type 要求の本文に JSON が含まれている場合は、このヘッダーを application/json に設定する必要があります。

  • 応答の本文に JSON が含まれる場合は受け入れます。このヘッダーを application/json に設定する必要があります。

  • 認証基本認証は、 base64 文字列でエンコードされたユーザ名とパスワードを使用して設定する必要があります。

本文を要求します

要求の本文の内容は、それぞれの呼び出しに応じて異なります。HTTP 要求の本文は、次のいずれかで構成されます。

  • JSON オブジェクトと入力変数(新しいクラスタの名前など)

  • 空です

オブジェクトのフィルタリング

GET を使用する API 呼び出しを発行する際、返されるオブジェクトを任意の属性に基づいて制限またはフィルタできます。たとえば、一致する正確な値を指定できます。

< フィールド >=< クエリ値 >

完全一致に加えて、他の演算子を使用して、一連のオブジェクトを一定範囲の値で返すことができます。ONTAP Select では、次のフィルタ演算子がサポートされています。

演算子 説明

=

等しい

<

より小さい

>

が次の値より大きい

が次の値以下です

>=

が次の値以上である必要があります

または

と等しくない

*

すべてに一致するワイルドカード

また、 null キーワードまたはその否定 (!null) をクエリの一部として使用して、特定のフィールドが設定されているかどうかに基づいてオブジェクトのセットを返すこともできます。

オブジェクトフィールドの選択

デフォルトでは、 GET を使用する API 呼び出しを発行すると、オブジェクトを一意に識別する属性のみが返されます。この最小のフィールドセットは、各オブジェクトのキーとして機能し、オブジェクトタイプによって異なります。fields query パラメータを使用すると、次の方法で追加のオブジェクトプロパティを選択できます。

  • 安価なフィールドは 'fields=*' を指定して ' ローカル・サーバ・メモリに保持されているオブジェクト・フィールドを取得するか ' アクセスするためにほとんど処理を必要としません

  • 高価なフィールドでは 'fields=**' を指定して ' 追加のサーバ処理を必要とするオブジェクトフィールドも含め ' すべてのオブジェクトフィールドを取得します

  • カスタムフィールドの選択では、「 fieldName=fieldName 」を使用して、目的のフィールドを指定します。複数のフィールドを要求する場合は、スペースを入れずにカンマで区切る必要があります。

ヒント ベストプラクティスとして、必要なフィールドを常に個別に指定することを推奨します。安価なフィールドや高コストのフィールドは、必要な場合にのみ取得してください。低コストでコストな分類は、ネットアップが社内パフォーマンス分析に基づいて決定します。特定のフィールドの分類は、いつでも変更できます。

出力セット内のオブジェクトのソート

リソースコレクション内のレコードは、オブジェクトによって定義されたデフォルトの順序で返されます。ORDER BY クエリ・パラメータを使用して ' フィールド名とソート方向を次のように指定して順序を変更できます 'ORDER BY = < フィールド名 > asc | desc

たとえば、タイプフィールドを降順にソートし、 id を昇順にソートできます。「 order_by= type desc 、 id asc 」

複数のパラメータを指定する場合は、各フィールドをカンマで区切る必要があります。

ページ付け

GET を使用する API 呼び出しを発行して同じタイプのオブジェクトのコレクションにアクセスする場合、一致するすべてのオブジェクトがデフォルトで返されます。必要に応じて、 max_records クエリパラメータを要求とともに使用して返されるレコード数を制限することもできます。たとえば 'max_crecords =20` です

必要に応じて、このパラメータを他のクエリパラメータと組み合わせて、結果セットを絞り込むことができます。たとえば、「 time⇒ 2019-04-04T15 : 41 : 29.140265Z & max_records = 10 」という指定時間を経過すると、最大 10 件のシステムイベントが生成されます

複数の要求を問題 で送信して、各イベント(または任意のオブジェクトタイプ)をページングできます。以降の API 呼び出しでは、前回の結果セットの最新イベントに基づいて新しい時間の値を使用する必要があります。

API 応答の解釈

各 API 要求でクライアントへの応答が生成されます。応答を調べて成功したかどうかを確認し、必要に応じて追加データを取得できます。

HTTP ステータスコード

Deploy REST API で使用される HTTP ステータスコードを次に示します。

コード 意味 説明

200

わかりました

新しいオブジェクトを作成しない呼び出しが成功したことを示します。

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 を使用して既存のホストを削除したあとは、応答の本文が空になります。