Web APIを利用する場合の、各APIの共通仕様について説明します。
Web APIで利用するデータ型は下表のとおりです。
リクエストでの各パラメータの指定や、レスポンスボディのフィールド値の参照はデータ型に合わせてください。
型名 | 対応するJSONの型 | 説明 |
|---|---|---|
文字列 | string | テキストデータです。
|
数値 | number | 数値データです。 |
リスト | string | 規定値を扱うデータです。 |
日時 | string | 日付と時刻のデータです。
YYYY：年を4桁で0000～9999で表します。 |
真偽値 | true, false | 真偽値のデータです。 |
リクエスト行
リクエスト行は、利用するリソースに合わせて指定します。
リクエスト行はASCII文字で指定します。パス名の一部(パスパラメータ)にマルチバイト文字が含まれる場合は、UTF-8でURLエンコードしてください。
リクエスト行 | 指定内容 |
|---|---|
メソッド | 各リソースで使用可能なHTTPメソッドを指定します。 |
パス名 | 各リソースのURIおよびクエリ文字列を指定します。 |
HTTPバージョン | “HTTP/1.1”を指定します。 |
各リソースの一覧取得をする場合、絞り込みやレスポンスの制御のためクエリパラメータを使用します。一覧取得で使用できるクエリパラメータの共通仕様は、以下のとおりです。
パラメータ名 | 省略値 | 説明 |
|---|---|---|
subsystem | “18.2.3.5 サブシステム番号”を参照 | 一覧取得する対象のサブシステムを指定します。指定可能な値は“18.2.3.5 サブシステム番号”を参照してください。 |
offset | 0 | 返却するレコードの開始位置を指定します。 |
limit | 15000 | 返却するレコードの最大数を指定します。 指定可能な値は0～15000です。 |
リクエストヘッダ
以下のリクエストヘッダを指定します。
リクエストヘッダ | 指定内容 |
|---|---|
Host | 接続先のSystemwalker Operation Managerサーバのホスト名とIPアドレスを以下の形式で指定します。 host:port |
Authorization | Basic認証の認証情報を指定します。 |
Content-Type | リクエストボディにパラメータを指定する場合に指定します。 |
リクエストボディ
JSONでリクエストパラメータを指定します。
指定可能なパラメータは各リソースで異なります、詳細は、各リソースの“リクエスト”の項目を参照してください。
ステータス行
リクエストの処理結果をHTTPステータスコードで返却します。
返却するHTTPステータスコードは、各リソースの“レスポンス”を参照してください。
正常時と異常時でレスポンスボディの形式が異なります。レスポンスボディは、HTTPステータスコードを確認してから利用してください。
レスポンスヘッダ
以下のレスポンスヘッダを設定して、返却します。
レスポンスヘッダ | 設定内容 | 説明 |
|---|---|---|
Content-Type | application/json;charset=UTF-8 | レスポンスボディのメディアタイプです。 |
レスポンスボディ
レスポンスヘッダ“Content-Type”のメディアタイプで返却します。
レスポンスボディの形式を以下に示します。
各リソースのリクエストを正常に処理できた場合の形式は、以下のとおりです。
{
"next": false,
"total: n,
"data": [ ←---＋
{ … }, ｜
… 各リソースのオブジェクト配列
{ … } ｜
] ←---＋
}n: 返却対象のオブジェクト配列の要素数
対象のオブジェクトが1件以上の場合は、dataフィールドに対象のオブジェクト配列が格納されます。nextおよびtotalフィールドの値で対象のオブジェクトがすべて返却されたかどうかを判断できます。
対象のオブジェクトが0件の場合、nextはfalse、totalは0、dataは空配列となります。
フィールド名 | 型 | 説明 |
|---|---|---|
next | 真偽値 | 返却対象のオブジェクトのうち、dataフィールドに格納していないオブジェクトが存在するかを真偽値で示します。返却対象のオブジェクト配列の要素数がクエリパラメータのlimitで指定した値以上である場合に、trueとなります。 true: 未返却のオブジェクトが存在する |
total | 数値 | 返却対象のオブジェクト配列の要素数です。 |
data | － | 返却対象のオブジェクト配列です。 |
注意
異常時のレスポンスボディでtext/htmlのようにJSON以外のデータフォーマットが返却される場合があります。レスポンスヘッダ“Content-Type”を確認し、適切なデータフォーマットで参照してください。
各リソースのリクエストの処理で異常が発生した場合の形式は、以下のとおりです。
{
"code": "エラーコード",
"message": "メッセージ文"
}HTTPステータスコードやエラーコード、メッセージ文によりエラー情報を返却します。エラーコードとメッセージ文の詳細は“Systemwalker Operation Manager メッセージ集”の“Web APIの出力メッセージ【Windows版】【Linux版】”を参照してください。
フィールド名 | 型 | 説明 |
|---|---|---|
code | 文字列 | エラー情報を示すコードです。 |
message | 文字列 | エラー情報を示すメッセージです。 |
APIのリクエストごとに認証が必要です。
リクエストヘッダーにBasic認証の情報を設定します。
ユーザIDとパスワードは、接続先のSystemwalker Operation Managerサーバ導入マシンの認証情報です。
拡張ユーザ管理機能が有効な場合は、Operation Managerユーザを指定してください。【Linux版】
指定したユーザIDの権限で各リソースを操作します。必要な権限は各リソースの説明を参照してください。
Authorization: Basic <ユーザID:パスワード をBase64エンコードした文字列> |
サブシステム番号の指定方法は以下のとおりです。
パスパラメータ
/subsystems/{subsystem}は指定不要です。
サブシステム番号0として指定することはできます。1～9の値は指定できません。
クエリパラメータ
?subsystem={subsystem}は指定不要です。
サブシステム番号0として指定することはできます。1～9の値を指定した場合、一覧取得の絞り込み結果は0件となります。
パスパラメータ
/subsystems/{subsystem}で指定できます。
サブシステム番号は、リソースを一意に特定するために必要です。
指定した場合はそのサブシステム番号を、省略した場合はサブシステム番号0を対象とします。
クエリパラメータ
?subsystem={subsystem}で指定できます。
省略した場合、すべてのサブシステム番号を対象に処理を行います。そのため、意図して起動させていないサブシステムがある場合は、対象とならないよう、対象のサブシステムだけを指定してください。
リクエスト例 (/Systemwalker-omgr/api 以降)
jobnetsリソースでジョブネットの操作をする場合
サブシステム番号を指定する場合
/v1/subsystem/1/projects/{projectname}/jobnets/{jobnetname} 【EE】
/v1/subsystem/0/projects/{projectname}/jobnets/{jobnetname}
サブシステム番号を省略する場合
/v1/projects/{projectname}/jobnets/{jobnetname}
jobnetsリソースでジョブネット情報の一覧取得をする場合
サブシステム番号を指定する場合
/v1/jobnets?subsystem=1
/v1/jobnets?subsystem=0
サブシステム番号を省略する場合
/v1/jobnets