SnapCenter Software 4.9
API要求を制御する入力変数
API呼び出しの処理方法は、HTTP要求で設定されたパラメーターと変数を使用して制御できます。
HTTPメソッド
次の表に、SnapCenter REST APIでサポートされるHTTPメソッドを示します。
| RESTエンドポイントのそれぞれですべてのHTTPメソッドを使用できるわけではありません。 |
| HTTPメソッド | 説明 |
|---|---|
GET |
リソース インスタンスまたはコレクションのオブジェクトのプロパティを取得します。 |
POST |
指定された入力に基づいて新しいリソース インスタンスを作成します。 |
DELETE |
既存のリソース インスタンスを削除します。 |
PUT |
既存のリソース インスタンスを変更します。 |
要求ヘッダー
HTTP要求には複数のヘッダーを含める必要があります。
Content-type
要求の本文にJSONが含まれている場合は、このヘッダーを application/json に設定する必要があります。
Accept
このヘッダーは、application/json に設定する必要があります。
Authorization
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=* を指定した場合に返される共通のフィールドとして分類されるフィールドは、Fujitsuの内部のパフォーマンス分析に基づいて決定されます。フィールドの分類は、今後のリリースで変更される可能性があります。 |
出力セット内のオブジェクトのソート
リソース コレクション内のレコードは、オブジェクトで定義されたデフォルトの順序で返されます。この順序は、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バイト）またはペビバイト |
