1. はじめに¶

1.1. 対象読者と目的¶

『CLUSTERPRO® X RESTful APIリファレンスガイド』は、管理者を対象に、『CLUSTERPRO X』が提供するRESTful API （以降、REST API と記載）の設定から運用開始前までに必須の事項について説明します。REST APIの設定時、運用時に必要な情報を参照してください。

1.2. 本書の構成¶

「2. REST APIについて」 : 動作環境の確認や設定について説明します。
「3. API リファレンス」 : 各 REST API の使用法について説明します。
「4. トラブルシューティング」 : インストールや設定関連のトラブルとその解決策について説明します。

1.3. CLUSTERPRO マニュアル体系¶

CLUSTERPRO のマニュアルは、以下の 4 つに分類されます。各ガイドのタイトルと役割を以下に示します。

『CLUSTERPRO X スタートアップガイド』 (Getting Started Guide)

すべてのユーザを対象読者とし、製品概要、動作環境、アップデート情報、既知の問題などについて記載します。

『CLUSTERPRO X インストール&設定ガイド』 (Install and Configuration Guide)

CLUSTERPRO を使用したクラスタシステムの導入を行うシステムエンジニアと、クラスタシステム導入後の保守・運用を行うシステム管理者を対象読者とし、CLUSTERPRO を使用したクラスタシステム導入から運用開始前までに必須の事項について説明します。実際にクラスタシステムを導入する際の順番に則して、CLUSTERPRO を使用したクラスタシステムの設計方法、CLUSTERPRO のインストールと設定手順、設定後の確認、運用開始前の評価方法について説明します。

『CLUSTERPRO X リファレンスガイド』 (Reference Guide)

管理者、および CLUSTERPRO を使用したクラスタシステムの導入を行うシステムエンジニアを対象とし、CLUSTERPRO の運用手順、各モジュールの機能説明およびトラブルシューティング情報等を記載します。『インストール&設定ガイド』を補完する役割を持ちます。

『CLUSTERPRO X メンテナンスガイド』 (Maintenance Guide)

管理者、および CLUSTERPRO を使用したクラスタシステム導入後の保守・運用を行うシステム管理者を対象読者とし、CLUSTERPRO のメンテナンス関連情報を記載します。

1.4. 本書の表記規則¶

本書では、注意すべき事項、重要な事項および関連情報を以下のように表記します。

注釈

この表記は、重要ではあるがデータ損失やシステムおよび機器の損傷には関連しない情報を表します。

重要

この表記は、データ損失やシステムおよび機器の損傷を回避するために必要な情報を表します。

参考

この表記は、参照先の情報の場所を表します。

また、本書では以下の表記法を使用します。

表記	使用方法	例
[ ] 角かっこ	コマンド名の前後画面に表示される語（ダイアログボックス、メニューなど）の前後	[スタート]をクリックします。 [プロパティ]ダイアログボックス
コマンドライン中の [ ] 角かっこ	かっこ内の値の指定が省略可能であることを示します。	`clpstat -s [-h host_name ]`
モノスペースフォント	パス名、コマンドライン、システムからの出力(メッセージ、プロンプトなど)、ディレクトリ、ファイル名、関数、パラメータ	`curl -u user:password http://10.0.0.1:29009/api/v1/cluster`
太字	ユーザが実際にコマンドラインから入力する値を示します。	以下を入力します。 http://<IP address>:<port>/api/v1
`斜体`	ユーザが有効な値に置き換えて入力する項目	`http://<IP address>:<port>/api/v1`

1.5. 最新情報の入手先¶

最新の製品情報については、以下のWebサイトを参照してください。

https://jpn.nec.com/clusterpro/

2. REST APIについて¶

2.1. 概要¶

本章では、『CLUSTERPRO X』が提供する REST API の使用方法について、説明しています。

重要

REST API は、X 4.2 以降の『CLUSTERPRO X』が対象です。対象外のバージョンの CLUSTERPRO では動作しませんので、ご使用前に X 4.2 以降の CLUSTERPRO であることをご確認ください。

2.2. 動作環境¶

REST API は、Node.js 環境で動作します。 REST API を実行するためには、CLUSTERPRO API サービスの設定とクラスタを構成するすべてのサーバに Node.js をインストールする必要があります。 CLUSTERPRO API サービスの設定をおこなう前に、クラスタを構成するすべてのサーバに Node.js をインストールしてください。

以下の環境で動作確認済みです。

実行環境
Node.js 18.13.0
Node.js 20.10.0

CLUSTERPRO X の内部バージョンと REST API のバージョンの関係は以下の通りです。 REST API のバージョンによっては、提供されない API が存在します。

CLUSTERPRO X for Windows	CLUSTERPRO X for Linux	REST API
12.20~	4.2.0-1~	v1.0
12.22	4.2.2-1	v1.1
12.30~	4.3.0-1~	v1.2
13.20~	5.2.0-1~	v1.3

2.3. 設定方法¶

CLUSTERPRO API サービスの設定については、『CLUSTERPRO X リファレンスガイド』の「パラメータの詳細」「パラメータの設定について」「クラスタプロパティ」の「API タブ」および「暗号化タブ」を参照してください。

2.4. 実行方法¶

REST API は、クライアント上で動作する他のアプリケーションに対して、CLUSTERPRO の各種ステータスの取得やクラスタ操作をおこなうための手段を提供します。 REST API は、クライアント上で動作する他のアプリケーションから後述するリクエスト形式に従った HTTP リクエストを発行することによって実行されます。

CLUSTERPRO API サービスは、発行されたリクエストに対して処理をおこない、実行結果や各種ステータス情報をレスポンス (JSON) として返却します。詳細は、「3. API リファレンス」を参照してください。

重要

本 REST API を実行するにはクラスタを構成するサーバ OS への認証が可能なユーザ名とパスワードが必要です。詳細は、後述の「2.認証方法」を参照してください。

エンドポイント

REST API のエンドポイントのベース URI は以下の通りです。

http://<IP address>:<port>/api/v1

IP address

CLUSTERPRO サーバをインストールしたサーバの IP アドレスを指定します。

port

インストール時に指定した API HTTP ポート番号と同じ番号を指定します。(既定値：29009)

(例) http://10.0.0.1:29009/api/v1

参考

CLUSTERPRO サーバと暗号化通信を有効にして接続する場合は、『CLUSTERPRO X リファレンスガイド』の「パラメータの詳細」 - 「クラスタプロパティ」 - 「暗号化タブ」を参照してください。暗号化通信を行う場合は下記を入力します。

https://10.0.0.1:29009/api/v1

上述のベース URI に対して、本書「3. API リファレンス」に従って、各エンドポイントのパスを指定します。

(例) クラスタステータスを取得する場合

http://10.0.0.1:29009/api/v1/cluster

指定したエンドポイントに対して、GET、POST の HTTP メソッドでパラメータを送信することで、本書「3. API リファレンス」に記載の各リソースの操作をおこないます。

認証方法

REST API では、CLUSTERPRO サーバへの接続に認証が必要です。 REST API 実行時に CLUSTERPRO サーバをインストールした OS への認証が可能なユーザ名、パスワードを指定します。

(例) curl コマンドで REST API を実行する場合

curl http://10.0.0.1:29009/api/v1/cluster -u user:password

重要

通信方式に HTTP を使用する設定は、認証情報 (ユーザー名、パスワード) の秘匿が行われないため非推奨です。API サービスの設定にて、通信方式を HTTPS に設定することを推奨します。

2.5. 注意・制限事項¶

本REST API の注意・制限事項は以下の通りです。

REST API における最大接続数は、CLUSTERPRO サーバ 1ノードにつき、最大で 64 です。
CLUSTERPRO の操作をおこなう REST API を実行する場合、操作完了まで待合わせません。要求したクラスタ操作の結果は、該当するステータス取得 API を使用して確認してください。
REST API 実行後、キャンセルはできません。
CLUSTERPRO の操作をおこなう REST API の並列実行はできません。レスポンスが返却されてから次の REST API を実行してください。
サーバへの認証失敗回数が設定した閾値を超えた場合、一定時間の間、同じ接続元、ユーザ名、パスワードでは、 REST API の実行はできなくなります。
REST API を実行する場合、リクエストパラメータは JSON 形式で指定してください。

3. API リファレンス¶

本章では、クラスタ情報取得 REST API、クラスタ操作 REST API、メトリクス情報取得 REST API について、説明します。

3.1. クラスタ情報取得 REST API¶

3.1.1. ステータス取得¶

概要: クラスタのステータス情報を取得します。

形式

GET /api/v1/cluster

クエリパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
cluster		object	クラスタ情報
	name	string	クラスタ名
	status	string	クラスタステータス

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/cluster

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "cluster": {
        "name": "cluster",
        "status": "Normal"
    }
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "cluster": {
        "name": "",
        "status": ""
    }
}

3.1.2. タイムアウト倍率取得¶

概要: クラスタタイムアウト倍率情報を取得します。

REST API v1.2 以降で利用可能です。

形式

GET /api/v1/cluster/toratio

クエリパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
cluster		object	クラスタ情報
	toratio	integer	クラスタタイムアウト倍率

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/cluster/toratio

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "cluster": {
        "toratio": 2
    }
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "cluster": {
        "toratio": 0
    }
}

3.2. サーバ情報取得 REST API¶

3.2.1. ステータス取得¶

概要: 各サーバステータスを取得します。

{servername} を指定した場合、指定したサーバに絞り込みをおこないます。

形式

GET /api/v1/servers
GET /api/v1/servers/{servername}

クエリパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
servers		array	サーバ情報
	name	string	サーバ名
	status	string	サーバステータス

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/servers
curl -u user:password http://10.0.0.1:29009/api/v1/servers/server1

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "servers": [
        {
            "name": "server1",
            "status": "Online"
        },
        {
            "name": "server2",
            "status": "Offline"
        }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "servers": [{
        "names": "",
        "status": ""
    }]
}

3.2.2. 名前一覧取得¶

概要: 各サーバの名前一覧を取得します。

形式

GET /api/v1/servers

クエリパラメータ

パラメータ	型	指定値	説明
select	string	name	名前情報に絞り込む

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
servers		array	サーバ情報
	name	string	サーバ名

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/servers?select=name

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "servers": [
        {
            "name": "server1"
        },
        {
            "name": "server2"
        }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "servers": [
        {
            "names": ""
        }
    ]
}

3.3. グループ情報取得 REST API¶

3.3.1. ステータス取得¶

概要: 各グループのステータスを取得します。

{groupname} を指定した場合、指定したグループに絞り込みをおこないます。

REST API v1.1 以降では、グループに属するグループリソースの名前一覧も取得可能です。

形式

GET /api/v1/groups
GET /api/v1/groups/{groupname}

クエリパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
groups		array	グループ情報
	name	string	グループ名
	status	string	グループステータス
	current	string	起動済サーバ名
	resources	array	グループに属するグループリソースの名前一覧(RESTAPI v1.1以降で使用可能)

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/groups
curl -u user:password http://10.0.0.1:29009/api/v1/groups/failover1

REST API v1.0 レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "groups": [
        {
            "name": "failover1",
            "status": "Online",
            "current": "server1"
        },
        {
            "name": "failover2",
            "status": "Online",
            "current": "server2"
        }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "groups": [
         {
            "name": "",
            "status": "",
            "current": ""
         }
    ]
}

REST API v1.1 レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "groups": [
        {
            "name": "failover1",
            "status": "Online",
            "current": "server1",
            "resources": [
                {
                    "name": "fip1"
                },
                {
                    "name": "script1"
                }
            ]
        },
        {
            "name": "failover2",
            "status": "Online",
            "current": "server2"
            "resources": [
                {
                    "name": "fip2"
                },
                {
                    "name": "script2"
                }
            ]
        }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "groups": [
         {
            "name": "",
            "status": "",
            "current": "",
            "resources": []
         }
    ]
}

3.3.2. 名前一覧取得¶

概要: グループの名前一覧を取得します。

クエリパラメータ resources を指定する場合のみ、{groupname} の指定は必須です。

クエリパラメータ resources は REST API v1.1 以降で使用可能です。

形式

GET /api/v1/groups
GET /api/v1/groups/{groupname}

クエリパラメータ

パラメータ	型	指定値	説明
select	string	name	名前情報に絞り込む
select	string	resources	グループに属するグループリソースの名前一覧情報に絞り込む(REST API v1.1以降で使用可能)

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
groups		array	グループ情報
	name	string	グループ名
	resources	string	グループに属するグループリソースの名前一覧 (RESTAPI v1.1 以降で使用可能)

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/groups?select=name
curl -u user:password http://10.0.0.1:29009/api/v1/groups/failover1?select=resources

クエリパラメータに name を指定した場合のレスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "groups": [
        {
            "name": "failover1"
        },
        {
            "name": "failover2"
        }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "servers": [
        {
            "names": ""
        }
    ]
}

クエリパラメータに resources を指定した場合のレスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "groups": [
        {
            "resources": [
                {
                    "name": "fip1"
                },
                {
                    "name": "script1"
                }
            ]
        }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "groups": [
        {
            "resources": []
        }
    ]
}

3.4. グループリソース情報取得 REST API¶

3.4.1. ステータス取得¶

概要: 各グループリソースのステータスを取得します。

{resourcename} を指定した場合、指定したグループリソースに絞り込みをおこないます。

REST API v1.1 以降では、グループリソースが属するグループ名情報も取得可能です。

形式

GET /api/v1/resources
GET /api/v1/resources/{resourcename}

クエリパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
resources		array	グループリソース情報
	name	string	グループリソース名
	type	string	グループリソース種別
	status	string	グループリソースステータス
	current	string	起動済サーバ名
	group	string	グループリソースが属するグループ名 (REST API v1.1 以降で利用可能)

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/resources
curl -u user:password http://10.0.0.1:29009/api/v1/resources/fip1

REST API v1.0 レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "resources": [
        {
            "name": "fip1",
            "type": "fip",
            "status": "Online",
            "current": "server1"
        },
        {
            "name": "fip2",
            "type": "fip",
            "status": "Online",
            "current":"server2"
         }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "resources": [
        {
            "name": "",
            "type": "",
            "status": "",
            "current": ""
        }
    ]
}

REST API v1.1 レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "resources": [
        {
            "name": "fip1",
            "type": "fip",
            "status": "Online",
            "current": "server1",
            "group": "failover1"
        },
        {
            "name": "fip2",
            "type": "fip",
            "status": "Online",
            "current":"server2",
            "group": "failover2"
         }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "resources": [
        {
            "name": "",
            "type": "",
            "status": "",
            "current": "",
            "group": ""
        }
    ]
}

3.4.2. 名前一覧取得¶

概要: 各グループリソースの名前一覧を取得します。

形式

GET /api/v1/resources

クエリパラメータ

パラメータ	型	指定値	説明
select	string	name	名前情報に絞り込む

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
resources		array	グループリソース情報
	name	string	グループリソース名

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/resources?select=name

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "resources": [
        {
            "name": "fip1"
        },
        {
            "name": "fip2"
         }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "resources": [
        {
            "name": ""
        }
    ]
}

3.5. モニタリソース情報取得 REST API¶

3.5.1. ステータス取得¶

概要: 各モニタリソースステータスを取得します。

{monitorname} を指定した場合、指定したモニタリソースに絞り込みをおこないます。

形式

GET /api/v1/monitors
GET /api/v1/monitors/{monitorname}

クエリパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ			型	説明
result			object	処理結果情報
	code		integer	詳細コード
	message		string	詳細メッセージ
monitors			array	モニタリソース情報
	name		string	モニタリソース名
	type		string	モニタリソース種別
	status		string	モニタステータス
	servers		array	サーバ情報
		name	string	サーバ名
		status	string	該当サーバ上でのモニタステータス

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/monitors
curl -u user:password http://10.0.0.1:29009/api/v1/monitors/fipw1

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "monitors": [
        {
            "name": "fipw1",
            "type": "fip",
            "status": "Normal",
            "servers": [
                {
                    "name": "server1",
                    "status": "Normal"
                },
                {
                    "name": "server2",
                    "status": "Normal"
                }
            ]
        }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "monitors": [
        {
            "name": "",
            "type": "",
            "status": "",
            "servers": []
        }
    ]
}

3.5.2. 名前一覧取得¶

概要: 各モニタリソースの名前一覧を取得します。

形式

GET /api/v1/monitors

クエリパラメータ

パラメータ	型	指定値	説明
select	string	name	名前情報に絞り込む

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
monitors		array	モニタリソース情報
	name	string	モニタリソース名

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/monitors?select=name

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "monitors": [
        {
           "name": "fipw1"
        },
        {
           "name": "fipw2"
        }
    ]
}

異常

{
    "result": {
        "code": 1,
        "message": ""
    },
    "monitors": [
        {
           "name": ""
        }
    ]
}

3.6. クラスタ操作 REST API¶

3.6.1. 起動¶

概要: クラスタを起動します。

形式

POST /api/v1/cluster/start

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/start

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.6.2. 停止¶

概要: クラスタを停止します。

形式

POST /api/v1/cluster/stop

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/stop

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.6.3. 再起動¶

概要: クラスタを再起動します。

形式

POST /api/v1/cluster/reboot

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/reboot

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.6.4. シャットダウン¶

概要: クラスタをシャットダウンします。

形式

POST /api/v1/cluster/shutdown

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/shutdown

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.6.5. サスペンド¶

概要: クラスタをサスペンドします。

形式

POST /api/v1/cluster/suspend

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/suspend

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.6.6. リジューム¶

概要: クラスタをリジュームします。

形式

POST /api/v1/cluster/resume

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/resume

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.6.7. タイムアウト値一時調整¶

概要

クラスタ内の全サーバで、以下の各種タイムアウト値の一時的な延長をおこないます。

モニタリソース

ハートビートリソース 1

ディスクエージェント

アラート同期サービス

Webmanagerサービス

REST API v1.2 以降で利用可能です。

1: Windows版のカーネルモードLANハートビートリソースは未対応です。

形式

POST /api/v1/cluster/toratio/set

リクエストパラメータ

パラメータ

型

説明

ratio

integer

タイムアウト倍率(1 - 10000)

ratio=1の場合、変更したタイムアウト倍率を元に戻します。

time

string

延長期間(分m、時間h、日d(最大延長期間30日)で指定) 例）2m、3h、4d

ratio=1の場合、指定不可です。

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/toratio/set -d '{ "ratio" : 2, "time" : "3d"}'

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.6.8. タイムアウト値初期化¶

概要: 変更した各種タイムアウト値を元に戻します。

REST API v1.2 以降で利用可能です。

形式

POST /api/v1/cluster/toratio/reset

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/toratio/reset

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.7. サーバ操作 REST API¶

3.7.1. サーバサービス起動¶

概要: サーバサービスを起動します。

形式

POST /api/v1/servers/{servername}/start

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/servers/server1/start

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.7.2. サーバサービス停止¶

概要: サーバサービスを停止します。

形式

POST /api/v1/servers/{servername}/stop

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/servers/server1/stop

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.7.3. 再起動¶

概要: サーバを再起動します。

形式

POST /api/v1/servers/{servername}/reboot

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/servers/server1/reboot

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.7.4. シャットダウン¶

概要: サーバをシャットダウンします。

形式

POST /api/v1/servers/{servername}/shutdown

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/servers/server1/shutdown

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.8. グループ操作 REST API¶

3.8.1. 起動¶

概要: グループを起動します。

形式

POST /api/v1/groups/start
POST /api/v1/groups/{groupname}/start

リクエストパラメータ

パラメータ

型

説明

target

string

グループを起動するサーバ名

{groupname}の指定がない場合、指定されたサーバ上で起動可能な全てのグループを起動します。

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/start -d '{ "target" : "server1" }'
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/failover1/start -d '{ "target" : "server1" }'

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.8.2. 停止¶

概要: グループを停止します。

形式

POST /api/v1/groups/stop
POST /api/v1/groups/{groupname}/stop

リクエストパラメータ

パラメータ

型

説明

target

string

グループが起動しているサーバ名

{groupname}の指定がある場合のみ、省略可。

{groupname}の指定がない場合、指定されたサーバ上で停止可能な全てのグループを停止します。

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/stop -d '{ "target" : "server1" }'
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/failover1/stop

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.8.3. 移動¶

概要: グループを移動します。

形式

POST /api/v1/groups/{groupname}/move

リクエストパラメータ

パラメータ

型

説明

target

string

移動先サーバ名（省略可）

指定がある場合、指定したサーバに移動します。

指定がない場合、次フェイルオーバポリシのサーバに移動します。

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/failover1/move
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/failover1/move -d '{ "target" : "server1" }'

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.9. グループリソース操作 REST API¶

3.9.1. 起動¶

概要: グループリソースを起動します。

対象のリソースが依存しているグループリソースで、停止状態のグループリソースがあれば、それらのグループリソースも起動します。

形式

POST /api/v1/resources/{resourcename}/start

リクエストパラメータ

パラメータ	型	説明
target	string	グループリソースを起動するサーバ名

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/resources/fip1/start -d '{ "target" : "server1" }'

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.9.2. 停止¶

概要: グループリソースを停止します。

形式

POST /api/v1/resources/{resourcename}/stop

リクエストパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/resources/exec1/stop

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.10. モニタリソース操作 REST API¶

3.10.1. 再開¶

概要: モニタリソースを再開します。

形式

POST /api/v1/monitors/{monitorname}/resume

リクエストパラメータ

パラメータ	型	説明
target	string	モニタリソースを再開するサーバ名

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/monitors/fipw1/resume -d '{ "target" : "server1" }'

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.10.2. 一時停止¶

概要: モニタリソースを一時停止します。

形式

POST /api/v1/monitors/{monitorname}/suspend

リクエストパラメータ

パラメータ	型	説明
target	string	モニタリソースを一時停止するサーバ名

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/monitors/fipw1/suspend -d '{ "target" : "server1" }'

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.11. スクリプト実行要求操作 REST API¶

3.11.1. スクリプト実行要求¶

概要: スクリプト実行要求をおこないます。

REST API v1.2 以降で利用可能です。

形式

POST /api/v1/scripts/run

リクエストパラメータ

パラメータ	型	説明
script	string	実行するスクリプト名 target に指定したサーバの CLUSTERPRO インストールディレクトリ配下の work/rexec ディレクトリ配下にスクリプトを配置する必要があります。
target	string	スクリプトを実行する CLUSTERPRO サーバの IP アドレス
timeout	integer	API のタイムアウト値 (省略可)。指定がない場合、180 秒です。
logdir	string	1回分の実行要求に対する詳細ログを出力するファイルパス (省略可)。指定がない場合、出力しません。

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/scripts/run -d '{ "script" : "script.bat", "target" : "10.0.0.2", "timeout" : 60, "logdir" : "C:\tmp\script.log" }'

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    }
}

異常

{
    "result": {
        "code": 0,
        "message": "xxxxxxx."
    }
}

3.12. メトリクス情報取得 REST API¶

3.12.1. グループの連続稼働時間取得¶

概要: 指定されたフェイルオーバーグループ (または全グループ) の連続稼働時間を取得します。

{groupname} を指定した場合、指定したグループに絞り込みをおこないます。

REST API v1.3 以降で利用可能です。

形式

GET /api/v1/metrics/groups/uptime
GET /api/v1/metrics/groups/{groupname}/uptime

クエリパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ			型	説明
result			object	処理結果情報
	code		integer	詳細コード
	message		string	詳細メッセージ
groups			array	グループ情報
	name		string	グループ名
	current		string	グループの起動サーバ名
	uptime		object	連続稼働時間
		days	integer	グループの連続稼働時間 (日)
		hours	integer	グループの連続稼働時間 (時)
		minutes	integer	グループの連続稼働時間 (分)
		seconds	integer	グループの連続稼働時間 (秒)

注意事項

以下の場合、連続稼働時刻取得 API が失敗もしくは実際と異なる時間を返します。

サマータイム中に連続稼働時刻を取得する
システム時刻を変更した後で連続稼働時刻を取得する

リクエスト例 (通信方式は HTTP、curl コマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/metrics/groups/uptime
curl -u user:password http://10.0.0.1:29009/api/v1/metrics/groups/failover1/uptime

レスポンス (JSON) 例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "groups": [
        {
            "name": "failover1",
            "current": "server1"
            "uptime":{
                "days":1,
                "hours":1,
                "minutes":1,
                "seconds":1
            }
        },
        {
            "name": "failover2",
            "current": "server2"
            "uptime":{
                "days":1,
                "hours":1,
                "minutes":1,
                "seconds":1
            }
        }
    ]
}

異常

{
    "result": {
        "code": 0 以外,
        "message": "xxxxxxx."
    }
}

3.12.2. クラスタ構成情報の最終反映日時取得¶

概要: クラスタ構成情報の最終反映日時を取得します。

REST API v1.3 以降で利用可能です。

形式

GET /api/v1/metrics/config/last-applied-date

クエリパラメータ: なし

ステータスコード

取得成功	200
取得失敗	200以外

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
config		object	クラスタ構成情報
	last-applied-date	string	最終クラスタ構成情報反映日時

リクエスト例(通信方式は HTTP、curlコマンド利用による)

curl -u user:password http://10.0.0.1:29009/api/v1/metrics/config/last-applied-date

レスポンス(JSON)例

正常

{
    "result": {
        "code": 0,
        "message": ""
    },
    "config": {
            "last-applied-date": "2023-07-17T01:19:03+09:00"
    }
}

異常

{
    "result": {
        "code": 0 以外,
        "message": "xxxxxxx."
    }
}

4. トラブルシューティング¶

REST API エラーレスポンス一覧

HTTPステータス	メッセージ	対処
400	The requested URL has an error.	リクエストURLに誤りがあります。 URLの内容をご確認、誤りを修正の上、再度APIを実行してください。
401	Authentication failed.	認証に失敗しました。 REST API要求で指定しているユーザ名またはパスワードに誤りがあります。ご確認、誤りを修正の上、再度APIを実行してください。
403	The request has not been allowed.	リクエストを許可されていません。 REST API要求で指定しているユーザ名またはパスワードを、REST APIで指定している接続先サーバに認証許可されているユーザ名、パスワードに変更の上、再度APIを実行してください。
405	The request has an error.	リクエスト方式に誤りがあります。設定している通信方式とURLで指定している通信方式があっているか、HTTPメソッドにGET、POST以外が指定されていないか、ご確認の上、再度APIを実行してください。
500	An error occurred while sending the request.	リクエスト送信中にエラーが発生しました。 CLUSTERPROサーバ側に問題が発生している可能性があります。問題をご確認の上、APIを実行してください。
500	An error occurred while processing the request.	リクエスト処理中にエラーが発生しました。 CLUSTERPROサーバ側に問題が発生している可能性があります。問題をご確認の上、APIを実行してください。
500	An error occurred while analyzing the response data.	レスポンスデータの解析中にエラーが発生しました。しばらく待ってから、APIを実行してください。