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ファイル形式のバイナリデータを返します。

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

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

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

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

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

{
    "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”です。
その場合のレスポンスの例を以下に示します。

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

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

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

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

{
"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 レスポンス