RPC 機能¶

Added in version 2025.2.0.

警告

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

概要¶

Sora では、 DataChannel 経由のシグナリング利用時に、 JSON-RPC 2.0 over DataChannel で一部の HTTP API をクライアントから直接呼び出すことができます。

この RPC 機能を利用することで、アプリケーションサーバー経由で Sora の HTTP API を呼び出す場合と比べて、より低遅延に同等の操作を行えます。

RPC 機能を利用する条件¶

sora.conf で data_channel_rpc が true に設定されていること
コネクションが DataChannel 経由のシグナリングを利用していること
認証成功時に rpc_methods の払い出しで利用できる RPC メソッド名一覧が払い出されていること

JSON-RPC 2.0 仕様¶

JSON-RPC 2.0 の仕様に準拠しています
- https://www.jsonrpc.org/specification
method には HTTP API で指定するヘッダー名とは異なる形式で指定する必要があります
- 2025.2.0/RequestSimulcastRid のように {RPC 経由での HTTP API の呼出が導入された Sora のバージョン}/{HTTP API 名} の形式で指定します
params には HTTP API 利用時の JSON を指定します
- params に不要なな項目が含まれている場合はエラーになります
- channel_id と connection_id は Sora 側で現在接続しているコネクションの値を利用するため指定不要です
- receiver_connection_id も同様に Sora 側で現在接続しているコネクションの値を利用するため指定不要です
id を付けないことでレスポンスを返さない Notification として利用できます
- これは Sora 側がレスポンスを返さないことを意味します

RPC の型定義¶

/* 
data_channel_rpc = true の場合に送信される RPC の型定義
JSON-RPC 2.0 準拠
https://www.jsonrpc.org/specification
DataChannel シグナリング
label: "rpc"
*/

// 2025.2.0 以降で利用可能な RPC メソッド
type rpcMethod =
  | "2025.2.0/RequestSimulcastRid"
  | "2025.2.0/RequestSpotlightRid"
  | "2025.2.0/ResetSpotlightRid"
  | "2025.2.0/PutSignalingNotifyMetadata"
  | "2025.2.0/PutSignalingNotifyMetadataItem";

type JSONRPCRequest = {
  jsonrpc: "2.0";
  // null 非推奨
  id?: number | string;
  method: rpcMethod;
  params?: Record<string, unknown> | unknown[];
};

type JSONRPCSuccess = {
  jsonrpc: "2.0";
  id: number | string;
  result: unknown;
};

// 予約済みエラーコード
type JSONRPCErrorCode =
  // JSON パースエラー
  | -32700
  // 不正なリクエスト
  | -32600
  // メソッドが見つからない
  | -32601
  // 不正なパラメータ
  | -32602
  // 内部エラー
  | -32603
  // -32000 ~ -32099: サーバーエラー、その他: アプリケーション定義
  | number;

type JSONRPCError = {
  jsonrpc: "2.0";
  id: number | string | null;
  error: {
    code: number;
    message: string;
    data?: unknown;
  };
};

メソッド一覧¶

注釈

method は {RPC 経由での HTTP API の呼出が導入された Sora のバージョン}/{HTTP API 名} という形式になります。

2025.2.0/RequestSimulcastRid¶

RequestSimulcastRid API

{
   "jsonrpc": "2.0",
   "method": "2025.2.0/RequestSimulcastRid",
   "params": {
      "sender_connection_id": "example_sender_connection_id",
      "rid": "r1"
   },
   "id": 1
}

channel_id と receiver_connection_id は Sora 側で設定するため指定不要です。また sender_connection_id はオプションです。

このメソッドを利用するには認証時の払い出しで simulcast と simulcast_rpc_rids を指定する必要があります。 RPC 経由で切り替えられる rid を simulcast_rpc_rids で指定してください。

{
  "type": "offer",
  "simulcast": true,
  "simulcast_rpc_rids": ["none", "r0", "r1"],
  "rpc_methods": [
     "2025.2.0/RequestSimulcastRid"
  ]
}

2025.2.0/RequestSpotlightRid¶

RequestSpotlightRid API

{
   "jsonrpc": "2.0",
   "method": "2025.2.0/RequestSpotlightRid",
   "params": {
      "send_connection_id": "example_send_connection_id",
      "spotlight_focus_rid": "r1",
      "spotlight_unfocus_rid": "none"
   },
   "id": 1
}

channel_id と recv_connection_id は Sora 側で設定するため指定不要です。また send_connection_id はオプションです。

2025.2.0/ResetSpotlightRid¶

ResetSpotlightRid API

{
   "jsonrpc": "2.0",
   "method": "2025.2.0/ResetSpotlightRid",
   "params": {
      "send_connection_id": "example_send_connection_id"
   },
   "id": 1
}

channel_id と recv_connection_id は Sora 側で設定するため指定不要です。また send_connection_id はオプションです。

2025.2.0/PutSignalingNotifyMetadata¶

PutSignalingNotifyMetadata API

{
  "jsonrpc": "2.0",
  "method": "2025.2.0/PutSignalingNotifyMetadata",
  "params": {
    "push": true,
    "metadata": {
      "example_key_1": "example_value_1",
      "example_key_2": "example_value_2"
    }
  },
  "id": 1
}

channel_id と connection_id は Sora 側で設定するため指定不要です。また、 push はオプションです。

2025.2.0/PutSignalingNotifyMetadataItem¶

PutSignalingNotifyMetadataItem API

{
  "jsonrpc": "2.0",
  "method": "2025.2.0/PutSignalingNotifyMetadataItem",
  "params": {
     "push": true,
     "key": "example_key",
     "value": "example_value"
  },
  "id": 1
}

channel_id と connection_id は Sora 側で設定するため指定不要です。また、 push はオプションです。

利用できる RPC の指定¶

この機能を利用するには認証時の払い出しで RPC 機能で利用できるメソッド一覧を指定する必要があります。

{
  "allowed": true,
  "rpc_methods": [
     "2025.2.0/RequestSpotlightRid",
     "2025.2.0/ResetSpotlightRid"
  ]
}

"type": "offer" シグナリングメッセージでの確認¶

クライアントから利用できる RPC メソッド一覧は "type": "offer" のシグナリングメッセージの rpc_methods で確認することができます。

{
  "type": "offer",
  "rpc_methods": [
     "2025.2.0/RequestSpotlightRid",
     "2025.2.0/ResetSpotlightRid"
  ]
}

シーケンス図¶

        sequenceDiagram
   participant C1 as Client1
   participant C2 as Client2
   participant S as Sora
   note over C1,S: C1, C2 共にWebRTC 確立済み
   C1 ->> S: JSON-RPC 2.0 Request<br>PutSignalingNotifyMetadataItem<br>push: true<br>over DataChannel
   note over S: シグナリング通知メタデータ拡張に項目を追加
   S ->> C1: JSON-RPC 2.0 Success Response<br>over DataChannel
   note over S: シグナリング通知メタデータ拡張によるプッシュ通知が発生
   S ->> C1: type: push<br>over DataChannel
   S ->> C2: type: push<br>over DataChannel