1. はじめに

1.1. 対象読者と目的

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

1.2. 本書の構成

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.認証方法」を参照してください。

  1. エンドポイント

    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 リファレンス」に記載の各リソースの操作をおこないます。

  2. 認証方法

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