1.1.2 使用方法

本製品にリクエストを送付する場合は、任意のRESTクライアントを使用してください。
使用するRESTクライアントに特に制限はありません。

HTTPリクエスト送信

以下のようにHTTPリクエストを送信します。

HTTPメソッドがGETまたはDELETEの場合

https://<ホスト名:ポート番号>/<バージョン>/<リソース名>?<パラメーター>

ホスト名には、本製品が動作する仮想マシンのIPアドレスまたはFQDNを指定してください。
ポート番号が443の場合だけ、ポート番号の指定は省略可能です。
リソース名に続けて、“?”で区切ってパラメーターを指定します。複数のパラメーターがある場合、パラメーター間は“&”で区切って指定します。

例

RESTクライアントとしてcurlコマンドを使用した場合(認証トークンの有効期限確認)

# curl -i -X GET \
 'https://192.0.2.10:9856/v1/auth/tokens/validate?token=c7133246-9f5c-4122-b9cf-7fcb72ade251'

例

RESTクライアントとしてcurlコマンドを使用した場合(操作ログのダウンロード)
ファイルダウンロードを行うリクエストの場合、“-o”で出力するファイル名を指定します。

# curl -X GET \
   -o 'audit_log.zip' \
 'https://192.0.2.10:9856/v1/log/audit_logs/download?token=c7133246-9f5c-4122-b9cf-7fcb72ade251'

HTTPメソッドがPOSTまたはPUTの場合

https://<ホスト名:ポート番号>/<バージョン>/<リソース名>

ホスト名には、本製品が動作する仮想マシンのIPアドレスまたはFQDNを指定してください。
ポート番号が443の場合だけ、ポート番号の指定は省略可能です。
パラメーターは、リクエストボディーに指定してください。

例

RESTクライアントとしてcurlコマンドを使用した場合(ログインと認証トークンの取得)

# curl -i -X POST \
   -d "user_name=admin" \
   -d "password=root" \
 'https://192.0.2.10:9856/v1/auth/tokens'

HTTPリクエスト送信で指定する内容は、以下のとおりです。

表1.1 HTTPリクエスト送信の指定内容
内容	説明
HTTPメソッド	CSG REST APIは、以下のHTTPメソッドをサポートします。 GET: 情報の一覧表示または詳細表示 POST: 新規作成、追加 PUT: 設定変更 DELETE: 削除
本製品が動作する仮想マシンのホスト名	導入時に設定したIPアドレスまたはFQDNを指定します。
バージョン	CSG REST APIのバージョンを指定します。 “v1”を指定してください。
リソース名	「1.2 CSG REST API一覧」に記載されているリソース名を指定します。ただし、“{ }”で示す部分は、以下のように入力してください。 {id}: リソースを1つに絞る必要がある場合に、そのリソースのIDを指定します。同じ名前のリソースには、ID指定が不要の一覧表示機能が存在しています。そのCSG REST APIを実行してレスポンスに表示される[id]カラムの値(数値)を入力してください。
パラメーター	「1.2 CSG REST API一覧」に記載されているパラメーターを指定します。パラメーターは、“パラメーター名=値”の形式で指定してください。

レスポンスは、CSG REST APIのリクエストに対する応答であり、RESTクライアントで確認できます。
レスポンスは、以下の3種類の情報で構成されています。

ステータスコード

ステータスコードとは、Webサーバからのレスポンスの意味を3桁の数字で表現したものです。
CSG REST APIが返すステータスコードには、以下のものがあります。

表1.2 CSG REST APIのステータスコード一覧
コード	意味	説明
200	OK	同期処理の要求が実行され、正常に完了した場合に返却されます。
202	Accepted	非同期処理の要求が実行され、処理が正常に受け付けられた場合に返却されます。非同期処理の状況および結果は、CSG Web GUIのダッシュボードにある「ログ」パネルの操作ログで確認できます。非同期処理は、完了までに時間がかかる場合があります。また、実行待ちの要求が多数存在する場合も完了までに時間がかかります。実行中・実行待ちの要求の状況についても、操作ログで確認してください。
400	Bad Request	誤ったパラメーターが指定された場合に返却されます。構文エラーのケースに加えて、指定したパラメーターが仕様に違反している場合も、本ステータスが返却されます。
401	Unauthorized	正しく認証されなかった場合に返却されます。
403	Forbidden	実行する処理に対して権限が不足していた場合に返却されます。
404	Not Found	指定した識別子(id)を持つデータが存在しない場合に返却されます。ただし、状況を表示するためのCSG REST APIを実行し、表示件数が0件だった場合、本ステータスは返却されません。
409	Conflict	存在しているものを作成しようとした場合など、競合が検出された場合に返却されます。
413	Request Entity Too Large	許容範囲を超えた要求が実行された場合に返却されます。
500	Internal Server Error	予期しないエラーが発生した場合に返却されます。操作を再実行しても発生する場合は、本製品を再起動したあと、再実行してください。問題が解決しない場合は、調査資料を採取し、サポート窓口に連絡してください。

レスポンスヘッダー

レスポンスヘッダーとは、リクエストに対する返答の状態を示すデータです。
レスポンスヘッダーのうち、レスポンスボディーの内容を示す“Content-Type”は、“application/json;charset=UTF-8”となります。
ただし資料採取、監査ログのダウンロード、および性能データのダウンロードの“Content-Type”は、“application/zip”となります。

レスポンスボディー

レスポンスの形式はJSON形式、エンコーディングはUTF-8(BOMなし)です。
レスポンスは、JSONオブジェクトとして返します。詳細は、各CSG REST APIの「レスポンス詳細」を参照してください。
ただし資料採取、監査ログのダウンロード、および性能データのダウンロードは、zipファイル形式のバイナリデータを返します。

レスポンスの例を以下に示します。

処理が正常に完了または受け付けられた場合

例1) 単一のオブジェクトを返す場合

{
   "key_name": {
       "name": "sample",
       "created_at": "YYYY-MM-DDThh:mm:ss+09:00"
    }
}

例2) オブジェクトの配列を返す場合

{
    "key_name": [
        {
            "name": "sample",
            "created_at": "YYYY-MM-DDThh:mm:ss+09:00"
        },
        {
            "name": "sample",
            "created_at": "YYYY-MM-DDThh:mm:ss+09:00"
        }
    ]
}

エラーが発生した場合

エラーが発生した場合は、メッセージ番号とエラーメッセージを含むJSONオブジェクトを返します。

キー名は、“msg_id”と“error”です。

その場合のレスポンスの例を以下に示します。

例2) エラーメッセージを返す場合

{
"msg_id":st10000103,
"error":"st10000103: invalid authentication token."
}

通常は上記のようにエラーが返りますが、認証トークン取得時は上記に“detail”キーを追加し、以下のように返します。

例3) 認証トークン取得時にエラーメッセージを返す場合

{
"msg_id":st10310001,
"error":"st10310001: The specified user is already logged in."
"detail": { "user": "username",
            "role": "Administrator",
            "client_info": "1.1.1.1",
            "login_date": "YYYY-MM-DDThh:mm:ss",
            "last_ope_date": "YYYY-MM-DDThh:mm:ss"
          }
}

1.1.2 使用方法

1.1.2.1 リクエスト

1.1.2.2 レスポンス