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 インストール&設定ガイド』 (Installation 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
Node.js 22.11.0
Node.js 24.11.1

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
13.30~	5.3.0-1~	v1.4
14.00~	6.0.0-1~	v1.5

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 に設定することを推奨します。

注釈

「3. API リファレンス」の各項に記載している「リクエスト例 (通信方式は HTTP、curlコマンド利用による) 」では、実行方法の一例を挙げています。実行する環境によって、コマンドラインでの「'」や「"」等の扱いが異なりますので、環境に合った記述方法にて実行してください。

(一例) Windows のコマンドプロンプトで実行する場合は、リクエストの例に記載されているパラメータを、 JSON内の文字列を囲む「"」は「\"」に、パラメータ全体を囲む「'」は「"」に置き換えて実行してください。

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 以降で利用可能です。

形式

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.7.5. 疑似障害発生

概要: サーバの疑似障害を発生させます。

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

形式: POST /api/v1/servers/{servername}/dummy-failure/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/dummy-failure/start

レスポンス(JSON)例

正常

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

異常

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

3.7.6. 疑似障害解除

概要: サーバの疑似障害を解除します。

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

形式

POST /api/v1/servers/{servername}/dummy-failure/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/dummy-failure/stop

レスポンス(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.10.3. 疑似障害発生

概要: モニタリソースの疑似障害を発生させます。

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

形式

POST /api/v1/monitors/{monitorname}/dummy-failure/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/monitors/fipw1/dummy-failure/start -d '{ "target" : "server1" }'
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/monitors/fipw1/dummy-failure/start -d '{ "target" : "" }'

レスポンス(JSON)例

正常

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

異常

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

3.10.4. 疑似障害解除

概要: モニタリソースの疑似障害を解除します。

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

形式

POST /api/v1/monitors/{monitorname}/dummy-failure/stop

リクエストパラメータ

パラメータ

型

説明

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/dummy-failure/stop -d '{ "target" : "server1" }'
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/monitors/fipw1/dummy-failure/stop -d '{ "target" : "" }'

レスポンス(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."
    }
}

3.13. ミラー/ハイブリッドディスクのバックアップ/リストア補助 REST API

3.13.1. バックアップ作業前後におこなう処理の実行

概要: ミラーディスクやハイブリッドディスクのバックアップ作業前後に実施する処理を実行します。

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

本 API は、要求先のサーバにて clpbackup.sh (Linux版) や clpbackup.bat (Windows版) を起動します。

preaction の場合は、clpbackup.sh や clpbackup.bat に --pre オプションを指定した時と同じ動作となります。

postaction の場合は、clpbackup.sh や clpbackup.bat に --post オプションを指定した時と同じ動作となります。

その他のオプションについては、リクエストパラメータで指定します。

clpbackup.sh (Linux版) や clpbackup.bat (Windows版) については、「CLUSTERPRO X リファレンスガイド」の「CLUSTERPRO コマンドリファレンス」を参照してください。

また、手順や実施方法については、「CLUSTERPRO X メンテナンスガイド」を参考にしてください。

形式

POST /api/v1/mirrors/backup/preaction
POST /api/v1/mirrors/backup/postaction

リクエストパラメータ

パラメータ	型	説明
no-shutdown	boolean	true を指定した場合、clpbackup.{sh\|bat} に --no-shutdown オプションを追加指定した時の動作となります。
no-reboot	boolean	true を指定した場合、clpbackup.{sh\|bat} に --no-reboot オプションを追加指定した時の動作となります。
only-shutdown	boolean	true を指定した場合、clpbackup.{sh\|bat} に --only-shutdown オプションを追加指定した時の動作となります。
only-reboot	boolean	true を指定した場合、clpbackup.{sh\|bat} に --only-reboot オプションを追加指定した時の動作となります。
online	boolean	true を指定した場合、clpbackup.{sh\|bat} に --online オプションを追加指定した時の動作となります。
timeout	integer	clpbackup.{sh\|bat} を起動してからこの指定秒数の間に終了しなかった場合、タイムアウトと判定して、強制終了されます。指定しなかった場合の既定値は900秒です。

ステータスコード

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

レスポンスパラメータ

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

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

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/mirrors/backup/preaction -d '{ "online" : true, "timeout" : 600 }'
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/mirrors/backup/postaction -d '{ "online" : true, "timeout" : 300 }'

レスポンス(JSON)例

正常

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

異常

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

注意事項

本 API は、要求先のサーバにて clpbackup.sh (Linux版) や clpbackup.bat (Windows版) を起動します。

実行状況や実行結果は、確認用の API 「3.13.3. バックアップ/リストア用処理の実行状況取得」を使って確認してください。

curl -u user:password http://10.0.0.1:29009/api/v1/mirrors/backup/status

{
    "result": {
        "code": 0,
        "message": ""
    },
    "detail": {
        "code": 0,
        "status": "clpbackup.sh : Command succeeded."
    }
}

本 API により起動した clpbackup.sh (Linux版) や clpbackup.bat (Windows版) が動作中の間は、本 API や他の操作系の API を実行できません。実行した場合は、エラーコード 28 の応答が返ります。
```
{
    "result": {
        "code": 28,
        "message": "API is busy. Cannot be accepted."
    }
}
```

3.13.2. リストア作業前後におこなう処理の実行

概要: ミラーディスクやハイブリッドディスクのリストア作業前後に実施する処理を実行します。

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

本 API は、要求先のサーバにて clprestore.sh (Linux版) や clprestore.bat (Windows版) を起動します。

preaction の場合は、clprestore.sh や clprestore.bat に --pre オプションを指定した時と同じ動作となります。

postaction の場合は、clprestore.sh や clprestore.bat に --post オプションを指定した時と同じ動作となります。

その他のオプションについては、リクエストパラメータで指定します。

clprestore.sh (Linux版) や clprestore.bat (Windows版) については、「CLUSTERPRO X リファレンスガイド」の「CLUSTERPRO コマンドリファレンス」を参照してください。

また、手順や実施方法については、「CLUSTERPRO X メンテナンスガイド」を参考にしてください。

形式

POST /api/v1/mirrors/restore/preaction
POST /api/v1/mirrors/restore/postaction

リクエストパラメータ

パラメータ	型	説明
no-shutdown	boolean	true を指定した場合、clprestore.{sh\|bat} に --no-shutdown オプションを追加指定した時の動作となります。
no-reboot	boolean	true を指定した場合、clprestore.{sh\|bat} に --no-reboot オプションを追加指定した時の動作となります。
only-shutdown	boolean	true を指定した場合、clprestore.{sh\|bat} に --only-shutdown オプションを追加指定した時の動作となります。
only-reboot	boolean	true を指定した場合、clprestore.{sh\|bat} に --only-reboot オプションを追加指定した時の動作となります。
skip-copy	boolean	true を指定した場合、clprestore.{sh\|bat} に --skip-copy オプションを追加指定した時の動作となります。
online	boolean	true を指定した場合、clprestore.{sh\|bat} に --online オプションを追加指定した時の動作となります。
timeout	integer	clprestore.{sh\|bat} を起動してからこの指定秒数の間に終了しなかった場合、タイムアウトと判定して、強制終了されます。指定しなかった場合の既定値は900秒です。

ステータスコード

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

レスポンスパラメータ

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

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

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/mirrors/restore/preaction -d '{ "no-shutdown" : true }'
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/mirrors/restore/postaction -d '{ "skip-copy" : true }'

レスポンス(JSON)例

正常

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

異常

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

注意事項

本 API は、要求先のサーバにて clprestore.sh (Linux版) や clprestore.bat (Windows版) を起動します。

実行状況や実行結果は、確認用の API 「3.13.3. バックアップ/リストア用処理の実行状況取得」を使って確認してください。
```
curl -u user:password http://10.0.0.1:29009/api/v1/mirrors/restore/status
```
```
{
    "result": {
        "code": 0,
        "message": ""
    },
    "detail": {
        "code": 259,
        "status": "running"
    }
}
```
本 API により起動した clprestore.sh (Linux版) や clprestore.bat (Windows版) が動作中の間は、本 API や他の操作系の API を実行できません。実行した場合は、エラーコード 28 の応答が返ります。
```
{
    "result": {
        "code": 28,
        "message": "API is busy. Cannot be accepted."
    }
}
```

3.13.3. バックアップ/リストア用処理の実行状況取得

概要: 実行要求した処理の実行状況や実行結果を取得します。

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

形式

GET /api/v1/mirrors/backup/status
GET /api/v1/mirrors/restore/status

クエリパラメータ: なし

ステータスコード

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

レスポンスパラメータ

パラメータ		型	説明
result		object	処理結果情報
	code	integer	詳細コード
	message	string	詳細メッセージ
detail		object	実行状況情報
	code	integer	状態コード/終了コード
	status	string	状態メッセージ/実行結果メッセージ

result/code が 0（=正常）の場合に、detail/code と detail/status も返ります。 detail/code と detail/status については、スクリプトの実行状態に応じて以下が返ります。

状況/状態	detail/code	detail/status	説明
実行可能	257	"ready"	実行要求を受け付け可能であることを示します。
実行開始中	258	"starting"	実行要求を受け付けて、実行開始中の状態であることを示します。
実行中	259	"running"	実行中であることを示します。
実行終了	0～255	実行結果のメッセージ	実行が終了したことを示します。コードとして実行したスクリプトの終了コードが返ります。メッセージとして、実行結果のメッセージが返ります。
タイムアウト	261	"timeout"	実行中のまま一定時間経過した（タイムアウトした）ため、強制終了が試みられたことを示します。
エラー発生	262	"failed"	リソース不足などによるエラーが発生したことを示します。
パラメータ不正	263	"invalid"	実行要求で指定されたリクエストパラメータに、問題があったことを示します。

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

curl -u user:password http://10.0.0.1:29009/api/v1/mirrors/backup/status
curl -u user:password http://10.0.0.1:29009/api/v1/mirrors/restore/status

レスポンス(JSON)例

正常（実行結果を取得した場合の例）

{
    "result": {
        "code": 0,
        "message": ""
    },
    "detail": {
        "code": 0,
        "status": "clpbackup.sh : Command succeeded."
    }
}

正常（実行可能な状態の場合の例）

{
    "result": {
        "code": 0,
        "message": ""
    },
    "detail": {
        "code": 257,
        "status": "ready"
    }
}

正常（実行中の場合の例）

{
    "result": {
        "code": 0,
        "message": ""
    },
    "detail": {
        "code": 259,
        "status": "running"
    }
}

異常（backup用処理実行の API 実行後に restore用処理の状況取得 API を実行した場合など、取得対象の指定が誤っている場合の例）
```
{
    "result": {
        "code": 28,
        "message": "API is busy. Cannot be accepted."
    }
}
```

異常（その他の異常）

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

注意事項

実行状況や実行結果の情報は、OSやAPIサービスの再起動等をおこなうとクリアされます。
処理実行要求の API を複数回実行した場合、最後に実行した処理実行要求の API による処理の実行状況や実行結果の情報のみが残ります。例えば、backup用処理実行要求の API を実行後に、backup や restore用処理の実行要求の API を実行して、本 API で実行状況や実行結果を取得すると、前者の実行結果の情報は消えて取得できず、後者の実行情報のみが取得されます。
バックアップ/リストア作業前後の処理実行要求の API にて、OSシャットダウンやOS再起動を伴う処理要求をおこなった場合には、シャットダウンによりAPIサービスに接続できずに実行状況や実行結果の情報を取得できない場合があります。

3.13.4. 使用例

使用順序

以下のような順序で使用することを想定しています。

バックアップ/リストア作業前におこなう処理を起動

「3.13.1. バックアップ作業前後におこなう処理の実行」や「3.13.2. リストア作業前後におこなう処理の実行」に記載している、バックアップ/リストア作業の前におこなう処理実行用の API を使って、 clpbackup.{sh|bat} や clprestore.{sh|bat} を起動します。

これらの API は、起動した処理の完了を待たずに、すぐに応答が返ります。
バックアップ/リストア作業前におこなう処理の実行状況を取得
起動した clpbackup.{sh|bat} や clprestore.{sh|bat} の実行状況を、「3.13.3. バックアップ/リストア用処理の実行状況取得」に記載している、実行状況取得用 API を使って取得して、確認します。
- 状態が実行中（259, "running"）の場合は、時間をおいて再度、実行状況取得用の API を使って、実行状態を確認します。
- 実行が終了した場合には、終了コードと、最後に出力されたメッセージが、応答として返ります。
  
  なお、その後、実行状態の情報はリセットされます。そのため実行状況取得用の API をもう一度使うと、実行可能（257, "ready"）が返ります。
- また、その他の異常（261 "timeout"、262 "failed"、263 "invalid"）が応答として返った場合にも、その後情報はリセットされ、実行状況取得用の API をもう一度使うと、実行可能（257, "ready"）が返ります。
なお、clpbackup.{sh|bat} や clprestore.{sh|bat} の実行によってサーバがシャットダウンした場合には、この状況取得はおこなえません。
バックアップ/リストアの実行

ミラーディスクリソースやハイブリッドディスクリソース用に使用している、クラスタパーティションとデータパーティションを含んだボリュームを、バックアップまたはリストアします。
バックアップ/リストア作業後におこなう処理を起動

「3.13.1. バックアップ作業前後におこなう処理の実行」や「3.13.2. リストア作業前後におこなう処理の実行」に記載している、バックアップ/リストア作業の後におこなう処理実行用の API を使って、 clpbackup.{sh|bat} や clprestore.{sh|bat} を起動します。

これらの API は、起動した処理の完了を待たずに、すぐに応答が返ります。
バックアップ/リストア作業後におこなう処理の実行状況を取得
起動した clpbackup.{sh|bat} や clprestore.{sh|bat} の実行状況を、「3.13.3. バックアップ/リストア用処理の実行状況取得」に記載している、実行状況取得用 API を使って取得して、確認します。
- 状態が実行中（259, "running"）の場合は、時間をおいて再度、実行状況取得用の API を使って、実行状態を確認します。
- 実行が終了した場合には、終了コードと、最後に出力されたメッセージが、応答として返ります。
  
  なお、その後、実行状態の情報はリセットされます。そのため実行状況取得用の API をもう一度使うと、実行可能（257, "ready"）が返ります。
- また、その他の異常（261 "timeout"、262 "failed"、263 "invalid"）が応答として返った場合にも、その後情報はリセットされ、実行状況取得用の API をもう一度使うと、実行可能（257, "ready"）が返ります。
なお、clpbackup.{sh|bat} や clprestore.{sh|bat} の実行によってサーバがリブートした場合には、この状況取得はおこなえません。

使用例

事前の状況確認（実行要求が可能な場合は、"ready" が返る）

curl -u user:password http://10.0.0.1:29009/api/v1/mirrors/backup/status

{
    "result": {
        "code": 0,
        "message": ""
    },
    "detail": {
        "code": 257,
        "status": "ready"
    }
}

clpbackup.sh --pre --online の実行要求（実行要求が受け付けられると、0 が返る）

curl -u user:password -X POST http://10.0.0.1:29009/api/v1/mirrors/backup/preaction -d '{ "online" : true }'

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

実行状況確認（まだ clpbackup.sh が実行中の場合の例）

curl -u user:password http://10.0.0.1:29009/api/v1/mirrors/backup/status

{
    "result": {
        "code": 0,
        "message": ""
    },
    "detail": {
        "code": 259,
        "status": "running"
    }
}

実行状況確認（実行していた clpbackup.sh が、正常終了していた場合の例）

curl -u user:password http://10.0.0.1:29009/api/v1/mirrors/backup/status

{
    "result": {
        "code": 0,
        "message": ""
    },
    "detail": {
        "code": 0,
        "status": "clpbackup.sh : Command succeeded."
    }
}

状況確認（clpbackup.sh の実行結果を既に取得済みの場合には、再度取得すると "ready" が返る）

curl -u user:password http://10.0.0.1:29009/api/v1/mirrors/backup/status

{
    "result": {
        "code": 0,
        "message": ""
    },
    "detail": {
        "code": 257,
        "status": "ready"
    }
}

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を実行してください。