# クラスター API ## InitCluster *バージョン 2022.2.0 で追加。* **x-sora-target**: Sora_20221221.InitCluster クラスターを初期化する際に実行する必要がある API です。 クラスター初期化時に、参加させるいずれかのノードに対して行ってください。 `node_name_list` にはクラスターに参加するノードのリストを指定してください。 API が成功すると、そのリストのノードで構成されるクラスターが構築されます。 > **ヒント** > > InitCluster API の実行はひとつのクラスターにつき一度だけ必要です。 > InitCluster API 後に、そのクラスターにノードを追加する場合には [RegisterClusterNode](API_CLUSTER.html#09ed96) API を使います。 > > InitCluster API が次に必要になるのはクラスターが破綻した場合です。 > 詳細は [クラスター破綻からの再構築手順](CLUSTER_OPS.html#7c3099) を参照してください。 * - キー - 型 * - node_name_list - array of string ```console $ curl -sS \ -X POST \ http://127.0.0.1:3000/ \ -H "x-sora-target: Sora_20221221.InitCluster" \ --json '{"node_name_list":["node-02@192.0.2.7","node-03@192.0.2.8","node-01@192.0.2.5"]}' \ | jq . { "node_name_list": [ "node-02@192.0.2.7", "node-03@192.0.2.8", "node-01@192.0.2.5" ] } ``` ## RegisterClusterNode **x-sora-target**: Sora_20211215.RegisterClusterNode 指定したクラスターにノードを登録します。 登録したいクラスターに属するノードのいずれかを `contact_node_name` で指定してください。 クラスターに属していれば、どのノードでもかまいません。 - 登録したいクラスターがすでに初期化されている必要があります。 - クラスターに登録するためには、登録したいクラスターの過半数のノードが正常に稼働している必要があります > **注釈** > > 新規にクラスターを作成する場合には、まず [InitCluster](API_CLUSTER.html#621990) API を使用してください。 * - キー - 型 * - contact_node_name - string ```console $ curl -sS \ -X POST \ http://127.0.0.1:3000/ \ -H "x-sora-target: Sora_20211215.RegisterClusterNode" \ --json '{"contact_node_name":"node-03@192.0.2.8"}' \ | jq . { "node_name_list": [ "node-01@192.0.2.5", "node-02@192.0.2.7", "node-03@192.0.2.8", "node-04@192.0.2.9", "node-05@192.0.2.10" ] } ``` ## ListClusterNodes **x-sora-target**: Sora_20211215.ListClusterNodes クラスターのノード一覧を表示します。 一時的に離脱しているノードの場合は `connected` が `false` になります。 出力対象のノードが離脱中、またはノードの情報取得に失敗した場合には以下の項目は出力されません。 - external_api_url - external_signaling_url - version - mode **レスポンス JSON** * - キー - 型 - 内容 * - external_api_url - string - ``sora.conf`` の ``external_api_url`` * - license_max_nodes - integer - ライセンスの最大ノード数 * - license_max_connections - integer - ライセンスの最大同時接続数 * - license_serial_code - string - ライセンスのシリアルコード * - license_type - string - ライセンスのタイプ * - node_name - string - ``sora.conf`` の ``node_name`` * - error - string - API 実行ノードと正常に接続はできているが、情報の取得に失敗した際のエラー理由 * - connected - boolean - API 実行ノードと正常に接続できているかどうか * - external_signaling_url - string - ``sora.conf`` の ``external_signaling_url`` * - temporary_node - boolean - テンポラリーノードかどうか * - version - string - Sora のバージョン * - mode - string - モード (normal / block_new_session / block_new_connection) ```console $ curl -sS \ -X POST \ http://127.0.0.1:3000/ \ -H "x-sora-target: Sora_20211215.ListClusterNodes" \ | jq . [ { "external_api_url": "http://192.0.2.5:3000/", "license_max_connections": 500, "license_max_nodes": 10, "license_serial_code": "ABCDEF-SRA-E001-203801-N3-100", "license_type": "Experimental", "node_name": "node-01@192.0.2.5", "mode": "normal", "connected": true, "external_signaling_url": "wss://node-01.example.com/signaling", "version": "2024.1.0", "temporary_node": false }, { "api_url": "http://192.0.2.7:3000/", "license_max_connections": 500, "license_max_nodes": 10, "license_serial_code": "ABCDEF-SRA-E002-203801-N3-100", "license_type": "Experimental", "node_name": "node-02@192.0.2.7", "mode": "normal", "connected": true, "external_signaling_url": "wss://node-02.example.com/signaling", "version": "2024.1.0", "temporary_node": false }, { "license_max_connections": 500, "license_max_nodes": 10, "license_serial_code": "ABCDEF-SRA-E003-203801-N3-100", "license_type": "Experimental", "node_name": "node-03@192.0.2.11", "connected": false, "temporary_node": false }, { "error": "{error,{erpc,timeout}}", "license_max_connections": 500, "license_max_nodes": 10, "license_serial_code": "ABCDEF-SRA-E004-203801-N3-100", "license_type": "Experimental", "node_name": "node-04@192.0.2.9", "connected": false, "temporary_node": false } ] ``` ## ListClusterChannels **x-sora-target**: Sora_20211215.ListClusterChannels クラスターチャネル割り当て一覧を表示します。 * - キー - 型 - 内容 * - channel_id - string - チャネル ID * - owners - string - 担当ノード owners には以下が含まれます。 * - キー - 型 - 内容 * - node_name - string - ノード名 * - connected - boolean - 担当ノードが API 実行ノードと正常に接続できているかどうか ```console $ curl -sS \ -X POST \ http://127.0.0.1:3000/ \ -H "x-sora-target: Sora_20211215.ListClusterChannels" \ | jq . [ { "channel_id": "sora", "owners": [ { "node_name": "node-01@192.0.2.5", "connected": true } ] }, { "channel_id": "lemon", "owners": [ { "node_name": "node-01@192.0.2.5", "connected": true } ] }, { "channel_id": "hisui", "owners": [ { "node_name": "node-03@192.0.2.8", "connected": true } ] }, { "channel_id": "zakuro", "owners": [ { "node_name": "node-03@192.0.2.8", "connected": true } ] } ] ``` ## PurgeClusterNode **x-sora-target**: Sora_20220629.PurgeClusterNode 復旧がすぐには難しい障害が発生したノードや、縮退し再参加する予定が無いノードの情報をクラスターから完全に消去します。 この API は 1 クラスターにつき 1 回実行すればすべての参加ノードから指定したノード情報が完全に消去されます。 - この API の実行時には、消去対象のノードは停止している必要があります - この API が正常に完了するためには、過半数のノードが正常に稼働している必要があります - API を実行するノードは、クラスターに参加していて、正常に稼働しているノードであればどのノードでもかまいません > **警告** > > PurgeClusterNode API はクラスターからノードを完全に消去するための API です。 > 再参加するノードに対しては基本的に使用しないでください。 > この API を含めた運用の手順は [クラスター機能運用](CLUSTER_OPS.html) をご確認ください。 * - キー - 型 * - target_node_name - string ```console $ curl -sS \ -X POST \ http://127.0.0.1:3000/ \ -H "x-sora-target: Sora_20220629.PurgeClusterNode" \ --json '{"target_node_name":"node-03@192.0.2.8"}' \ | jq . { "target_node_name": "node-03@192.0.2.8" } ``` ```console $ curl -sS \ -X POST \ http://127.0.0.1:3001/ \ -H "x-sora-target: Sora_20220629.PurgeClusterNode" \ --json '{"target_node_name":"node-03@192.0.2.8"}' \ | jq . { "error_reason": { "target_node": "node-03@192.0.2.8" }, "error_type": "NODE-IS-ALIVE" } ```