Room API ／ Channel API

Channel APIからRoom APIへの移行

Channel APIからRoom APIへの移行

この度、SkyWay Channel API をより便利に拡張したサーバーサイド向け API として、SkyWay Room API をリリースしました。

Room API のリリースに伴い、Channel API は非推奨とさせていただきました。今後は Room API をご利用いただくようお願い致します。

本ドキュメントでは、既に Channel API をご利用いただいている場合における Room API へ移行する手順を、JavaScript のコード例を交えながら説明します。

Channel API と Room API の違い

Channel API と Room API には、以下のような違いがあります。

API エンドポイントの違い

Channel API のエンドポイント

https://channel.skyway.ntt.com/v1/json-rpc

Room API のエンドポイント

https://room.skyway.ntt.com/v1/json-rpc

機能の違い

機能	Channel API	Room API
Room / Channel の作成	○	○
Room / Channel の取得	○	○
Room / Channel の削除	×	○
Room / Channel 失効時刻の取得	×	○
Room / Channel から Member を退出させる	×	○

メソッド名の違い

機能	Channel API	Room API
Room / Channel の作成	`createChannel`	`createRoom`
Room / Channel の取得	`findChannel`	`findRoom`
Room / Channel の作成および取得	`findOrCreateChannel`	`findOrCreateRoom`
Room / Channel の削除	※	`closeRoom`
Room / Channel から Member を退出させる	※	`removeMember`

※当該機能は提供されておりません

レスポンスの違い

レスポンスの内容	Channel API	Room API
Member 情報	`type` や `subtype` を用いた Bot 判定処理などを自前で実装する必要がある	SDK を利用している Member のみが含まれるため、直感的に利用できる
Publication 情報	`originId` などの SFU サーバーに関する情報を考慮する必要がある	SFU サーバーに関する複雑な情報が隠蔽され、直感的に利用できる

移行手順

1. API エンドポイントを変更する

まず、アプリケーションサーバー側で呼び出している API エンドポイントを、Channel API　のものから Room API のものに変更します。

- const url = "https://channel.skyway.ntt.com/v1/json-rpc"
+ const url = "https://room.skyway.ntt.com/v1/json-rpc"

2. メソッド名を変更する

リクエストに含める method パラメータを変更します。たとえば、Channel API の findOrCreateChannel メソッドを利用していた箇所は、findOrCreateRoom メソッドを利用するようにします。

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${createSkyWayAdminAuthToken()}`,
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: uuidV4(),
      // メソッド名を変更する
-     method: "findOrCreateChannel",
+     method: "findOrCreateRoom",
      params: {
        name: roomName,
      },
    }),
  });

3. レスポンスの参照先を変更する

Channel API は result.channel を返しますが、Room API は result.room を返します。そのため、取得したレスポンスの参照先を変更します。

  const {
    result: {
      // レスポンスの参照先を変更する
-     channel: {
+     room: {
        id: roomId
      },
    },
  } = await response.json();

4. SFU Bot を前提とした処理を見直す

SFU サーバーもメディア通信を実施するため、SkyWay では 1 つの Member とみなして通信します。そのため、SkyWay Core ライブラリでは、SFU Bot という特殊な Member を Channel 内に Join させることによって SFU サーバーを利用します。

Room API のレスポンスでは、この SFU Bot が隠蔽されているため、Channel API より直感的にご利用いただけます。

Member に対する処理

Channel API のレスポンスでは、Members オブジェクトに SFU Bot が含まれます。したがって、Member から SDK を利用しているクライアントのみ抽出する場合などにおいて、SFU Bot を Member.type プロパティで判定して除外するといった特別な考慮が必要でした。

// `fetchedChannel` には Channel API レスポンスから取得した Channel 情報が代入されている
const persons = fetchedChannel.members.filter(
	(member) => member.type !== "Bot",
);

Room API のレスポンスでは SFU Bot が隠蔽されているため、上記のような処理を自前で実装する必要がありません。

// `fetchedRoom` には Room API レスポンスから取得した Room 情報が代入されている
const persons = fetchedRoom.members;

Publication に対する処理

SFU を利用する場合、通常多くのアプリケーションでは中継後の Publication に関心があります。しかし、Channel API のレスポンスは以下に示すオブジェクトのような構造になっており、SFU サーバーに中継される前後の Publication が両方含まれます。

// fetchedChannel.publications
[
  {
    id: '8fd19070-3dfb-4840-aaa8-d967a8c196dd',
    publisherId: 'cccccf82-fa06-4d59-b80e-ef07200b6bf4',
    contentType: 'VIDEO',
    isEnabled: true,
    type: 'SFU'
  },
  {
    id: '53af7758-64dc-4238-a79c-5a69bb3cded8',
    publisherId: '212548ac-af5b-41b1-ac1e-c44288c2bcc9',
    contentType: 'VIDEO',
    originId: '8fd19070-3dfb-4840-aaa8-d967a8c196dd',
    originPublisherId: 'cccccf82-fa06-4d59-b80e-ef07200b6bf4',
    isEnabled: true,
    type: 'SFU'
  }
]

したがって、中継後の Publication を抽出する場合などでは、処理を自前で実装する必要がありました。

const sfuPublications = fetchedChannel.publications.filter(
	(publication) => publication.type === "SFU" && publication.originId != null,
);

一方で、Room API のレスポンスでは SFU サーバーによる中継前の Publication が隠蔽されます。そのため、SFU 経由の Publication を容易に扱うことが可能です。

const sfuPublications = fetchedRoom.publications.filter(
  (publication) => publication.type === "SFU"
);

Room API の新機能を活用する

Room API には Channel API で提供されていない機能も存在します。ぜひご活用ください。

Room を削除する

Room API では、closeRoom メソッドが提供されています。 Webhook 機能と連携し、Member が 0 人になったことを契機として Room を削除するなどの用途でご活用いただけます。

指定した Member を強制的に退出させる

removeMember メソッドは、アプリケーション側の退出処理と連動して SkyWay の Room からもメンバーを強制退出させたい場合に有効です。退出済みユーザーの残留を防ぎ、盗聴リスクを低減したい場合などにご活用いただけます。

Room の失効時刻を取得する

findRoom メソッドのレスポンスに含まれる result.room.expiresAt プロパティは、Room の失効時刻を ISO 8601 形式で表しています。失効が迫っている Room に代わる新しい Room を createRoom メソッドで作成する場合などにご活用いただけます。