API要求を制御する入力変数
API呼び出しの処理方法は、HTTP要求で設定されたパラメータと変数を使用して制御できます。
HTTPメソッド
次の表に、SnapCenter REST APIでサポートされるHTTPメソッドを示します。
|
RESTエンドポイントのそれぞれですべてのHTTPメソッドを使用できるわけではありません。 |
HTTPメソッド | 説明 |
---|---|
GET |
リソース インスタンスまたはコレクションのオブジェクトのプロパティを取得します。 |
POST |
指定された入力に基づいて新しいリソース インスタンスを作成します。 |
DELETE |
既存のリソース インスタンスを削除します。 |
PUT |
既存のリソース インスタンスを変更します。 |
要求ヘッダー
HTTP要求には複数のヘッダーを含める必要があります。
Content-type
リクエスト本文に JSON が含まれている場合、このヘッダーは application/json に設定する必要があります。
受け入れる
このヘッダーは application/json に設定する必要があります。
承認
base64文字列としてエンコードされたユーザ名とパスワードを使用するベーシック認証を設定する必要があります。
リクエスト本文
要求の本文の内容は、それぞれの呼び出しに応じて異なります。HTTP要求の本文は、次のいずれかで構成されます。
-
JSONオブジェクトと入力変数
-
空の
オブジェクトのフィルタ
GETを使用するAPI呼び出しを発行する際、返されるオブジェクトを任意の属性に基づいて制限またはフィルタできます。たとえば、一致する完全な値を指定できます。
<field>=<query value>
完全一致に加えて、他の演算子を使用して、特定の範囲の値の一連のオブジェクトを返すことができます。次の表に、SnapCenter REST APIでサポートされるフィルタ演算子を示します。
オペレーター | 説明 |
---|---|
= |
等しい |
< |
小なり |
> |
より大きい |
⇐ |
以下 |
>= |
より大きいか等しい |
UPDATE |
または |
! |
等しくない |
* |
すべてに一致するワイルドカード |
クエリの一部として null キーワードまたはその否定 !null を使用することで、特定のフィールドが設定されているかどうかに基づいてオブジェクトのコレクションを返すこともできます。
|
通常、設定されていないフィールドはクエリの照合から除外されます。 |
特定のオブジェクト フィールドの要求
デフォルトでは、GETを使用してAPI呼び出しを実行すると、1つまたは複数のオブジェクトを一意に識別する属性のみが返されます。この最小のフィールド セットは各オブジェクトのキーとして機能し、オブジェクト タイプによって異なります。追加のオブジェクトプロパティを選択するには、 `fields`クエリパラメータを次の方法で指定します。
共通または標準のフィールド
最もよく使用されるオブジェクト フィールドを取得するには、fields=* を指定します。通常、これらのフィールドはローカル サーバ メモリに保持されているか、ほとんど処理を必要とせずにアクセスできます。これらのプロパティは、URLパス キー(UUID)を指定してGETを使用した場合にオブジェクトに対して返されるプロパティと同じです。
すべてのフィールド
fields=** を指定すると、アクセスするために追加のサーバー処理が必要なものも含め、すべてのオブジェクト フィールドが取得されます。
カスタム フィールド選択
必要なフィールドを正確に指定するには、fields=<field_name> を使用します。複数のフィールドを要求する場合は、各値の間にスペースを入れずにカンマで区切る必要があります。
|
ベストプラクティスとして、必要なフィールドを常に個別に指定することを推奨します。一連の共通のフィールドやすべてのフィールドを取得するのは、必要な場合だけにしてください。どのフィールドが共通として分類され、fields=* を使用して返されるかは、 NetAppによって内部パフォーマンス分析に基づいて決定されます。フィールドの分類は、今後のリリースで変更される可能性があります。 |
出力セット内のオブジェクトのソート
リソース コレクション内のレコードは、オブジェクトで定義されたデフォルトの順序で返されます。順序を変更するには、 `order_by`フィールド名と並べ替え方向を指定したクエリ パラメータは次のとおりです。
order_by=<field name> asc|desc
たとえば、次のように指定すると、typeフィールドで降順にソートしてから、idで昇順にソートできます。
order_by=type desc, id asc
-
ソートするフィールドを指定してソート順序を指定しなかった場合、値は昇順でソートされます。
-
複数のパラメータを指定する場合は、各フィールドをカンマで区切る必要があります。
オブジェクトのコレクションを取得するときのページ付け
GETを使用するAPI呼び出しを発行して同じタイプのオブジェクトのコレクションにアクセスする場合、SnapCenterでは2つの制約に基づいて可能なかぎり多くのオブジェクトを返します。これらの各制約は、要求に対する追加のクエリ パラメータを使用して制御できます。それぞれのGET要求に対する最初の制約に達した時点で要求が終了され、結果として返されるレコードの数が制限されます。
|
すべてのオブジェクトについての処理が完了する前に要求が終了した場合、次のレコードのバッチを取得するために必要なリンクが応答に含まれます。 |
オブジェクト数の制限
デフォルトでは、 SnapCenter はGET リクエストに対して最大 10,000 個のオブジェクトを返します。この制限は、max_records クエリ パラメータを使用して変更できます。例えば:
max_records=20
実際に返されるオブジェクトの数は、関連する時間の制約やシステム内のオブジェクトの総数に基づいて、有効な最大数よりも少なくなることがあります。
オブジェクトを取得する時間の制限
デフォルトでは、SnapCenterはGET要求に許可された時間の範囲内でできるだけ多くのオブジェクトを返します。デフォルトのタイムアウトは15秒です。この制限は、return_timeout クエリ パラメータを使用して変更できます。例えば:
return_timeout=5
実際に返されるオブジェクトの数は、関連するオブジェクト数の制約やシステム内のオブジェクトの総数に基づいて、有効な最大数よりも少なくなることがあります。
結果セットの絞り込み
必要に応じて、これらの2つのパラメータを追加のクエリ パラメータと組み合わせて、結果セットを絞り込むことができます。たとえば、次の例では、指定した時間のあとに生成されたEMSイベントを最大10件まで返します。
time⇒ 2018-04-04T15:41:29.140265Z&max_records=10
複数の要求を発行してオブジェクトをページングすることができます。以降のAPI呼び出しでは、前回の結果セットの最後のイベントに基づいて新しい時間の値を使用する必要があります。
サイズのプロパティ
一部のAPI呼び出しおよびクエリ パラメータでは、入力値として数値が使用されます。バイト単位で整数を指定する代わりに、必要に応じて次の表に示すサフィックスを使用することができます。
サフィックス | 説明 |
---|---|
KB |
KB:キロバイト(1,024バイト)またはキビバイト |
MB |
MB:メガバイト(KB x 1,024バイト)またはメビバイト |
GB |
GB:ギガバイト(MB x 1,024バイト)またはギビバイト |
TB |
TB:テラバイト(GB x 1,024バイト)またはテビバイト |
PB |
PB:ペタバイト(TB x 1,024バイト)またはペビバイト |