クラスター API

注意

この API は 実験的機能 のため、正式版では仕様が変更される可能性があります。

InitCluster

x-sora-target:

Sora_20221221.InitCluster

クラスターを初期化する際に実行する必要がある API です。

クラスター初期化時に、参加させるいずれかのノードに対して行ってください。

node_name_list にはクラスターに参加するノードのリストを指定してください。 API が成功すると、そのリストのノードで構成されるクラスターが構築されます。

Tip

InitCluster API の実行はひとつのクラスターにつき一度だけ必要です。 InitCluster API 後に、そのクラスターにノードを追加する場合には RegisterClusterNode API を使います。

InitCluster API が次に必要になるのはクラスターが破綻した場合です。 詳細は クラスター破綻からの再構築手順 を参照してください。

キー	型
node_name_list	array of string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20221221.InitCluster \
    node_name_list:='["[email protected]", "[email protected]", "[email protected]"]'

RegisterClusterNode

x-sora-target:

Sora_20211215.RegisterClusterNode

指定したクラスターにノードを登録します。

登録したいクラスターに属するノードのいずれかを contact_node_name で指定してください。 クラスターに属していれば、どのノードでもかまいません。

• 登録したいクラスターがすでに初期化されている必要があります。

• クラスターに登録するためには、登録したいクラスターの過半数のノードが正常に稼働している必要があります

注釈

新規にクラスターを作成する場合には、まず InitCluster API を使用してください。

キー	型
contact_node_name	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.RegisterClusterNode \
    contact_node_name=[email protected] \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 42
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.RegisterClusterNode

{
    "contact_node_name": "[email protected]"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 116
content-type: application/json
date: Tue, 16 Nov 2021 09:28:11 GMT
server: Cowboy

{
    "node_name_list": [
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ]
}

ListClusterNodes

x-sora-target:

Sora_20211215.ListClusterNodes

クラスターのノード一覧を表示します。

キー	型	デフォルト
include_all_known_nodes (オプション)	boolean	true

警告

include_all_known_nodes は 2024 年 12 月リリースの Sora にて廃止されます。 今後はそのクラスターへ登録されている全てのノード情報が常に含まれるようになります。

include_all_known_nodes を false に指定することで、そのクラスターに登録はされているが、一時的に離脱しているノードが結果に含まれなくなります。 一時的に離脱しているノードの場合は 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)

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.ListClusterNodes \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ListClusterNodes



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 1554
content-type: application/json
date: Tue, 16 Nov 2021 09:22:16 GMT
server: Cowboy

[
    {
        "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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 実行ノードと正常に接続できているかどうか

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.ListClusterChannels \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ListClusterChannels



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 341
content-type: application/json
date: Tue, 16 Nov 2021 08:42:25 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "lemon",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "hisui",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "zakuro",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    }
]

PurgeClusterNode

x-sora-target:

Sora_20220629.PurgeClusterNode

復旧がすぐには難しい障害が発生したノードや、縮退し再参加する予定が無いノードの情報をクラスターから完全に消去します。

この API は 1 クラスターにつき 1 回実行すればすべての参加ノードから指定したノード情報が完全に消去されます。

• この API の実行時には、消去対象のノードは停止している必要があります

• この API が正常に完了するためには、過半数のノードが正常に稼働している必要があります

• API を実行するノードは、クラスターに参加していて、正常に稼働しているノードであればどのノードでもかまいません

警告

PurgeClusterNode API はクラスターからノードを完全に消去するための API です。 再参加するノードに対しては基本的に使用しないでください。 この API を含めた運用の手順は クラスター機能運用 をご確認ください。

キー	型
target_node_name	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20220629.PurgeClusterNode \
    target_node_name=[email protected] \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 39
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.1
x-sora-target: Sora_20220629.PurgeClusterNode

{
    "target_node_name": "[email protected]"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:3000
access-control-max-age: 1000
content-length: 38
content-type: application/json
date: Sun, 12 Jun 2022 03:13:42 GMT
server: Cowboy

{
    "target_node_name": "[email protected]"
}

$ http POST 127.0.0.1:3001/ x-sora-target:Sora_20220629.PurgeClusterNode \
    target_node_name=[email protected] \
        -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 39
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.1
x-sora-target: Sora_20220629.PurgeClusterNode

{
    "target_node_name": "[email protected]"
}


HTTP/1.1 400 Bad Request
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:3000
access-control-max-age: 1000
content-length: 79
content-type: application/json
date: Sun, 12 Jun 2022 03:13:29 GMT
server: Cowboy

{
    "error_reason": {
        "target_node": "[email protected]"
    },
    "error_type": "NODE-IS-ALIVE"
}

コンテンツ

• クラスター API
  • InitCluster
  • RegisterClusterNode
  • ListClusterNodes
  • ListClusterChannels
  • PurgeClusterNode