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