# 2023.1.x から 2023.2.x への移行 ## 概要 2023.1.x から 2023.2.x への移行について注意点をまとめています。 もし不明点がある場合はサポートまでお問い合わせください。 ## 2023.1.x へのローリングアップデートによるクラスター切り戻しはできません 2023.1.x から 2023.2.0 に切り替えた後、 2023.1.x へローリングアップデートによるクラスターの切り戻しは行えません。 切り戻しを行いたい場合はクラスターの再構築が必要になります。 不明点などはサポートまでお問い合わせください。 ## クラスター関連ログの出力先を `cluster.jsonl` へ変更 2023.2.0 からクラスター関連ログ出力を `sora.jsonl` から `cluster.jsonl` に変更しました。 Sora は 2023.2.0 から、クラスターをベースとする仕組みに変更しました。 そのため、クラスターを無効にした状態でも、内部的にはクラスターを前提とする仕組みで動作するようになりました。 これにより、 `sora.conf` の `cluster` が `false` でも `cluster.jsonl` が出力されるようになりました。 ログローテーションなどは `sora.jsonl` と同様に扱っていただくようお願いします。 詳細については [ログファイル](LOG.html) をご確認ください。 ## `sora.conf` の `signaling_notify_metadata` を `false` に設定した場合の挙動の変更 `sora.conf` のシグナリング通知メタデータを含めないようにする設定の `signaling_notify_metadata を false にした` 際の挙動を変更しました。 今までは `signaling_notify_metadata` を `false` に設定した場合、 `data` 自体が含まれなくなっていましたが、 今回の変更から、 `data` はシグナリング通知が有効であれば含まれるようになりました。 `signaling_notify_metadata` を `false` にした場合、 `data` に含まれる `metadata` や `authn_metadata` や `authz_metadata` は含まれなくなります。 ### 2023.1.x まで `signaling_notify_metadata` を `false` にした場合、 `data` は含まれません。 ``` { "type": "notify", "event_type": "connection.created", } ``` ### 2023.2.0 から `signaling_notify_metadata` を `false` にした場合、 `data` は含まれます。 ただし、その中の `metadata` や `authn_metadata` や `authz_metadata` は含まれません。 ``` { "type": "notify", "event_type": "connection.created", "data": [ { "client_id": "4D40YWH56N5S99QHJV6GAPNHB0", "bundle_id": "4D40YWH56N5S99QHJV6GAPNHB0", "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0", }, { "client_id": "FCX8X05SJS3Y18RD5MYFZS62RR", "bundle_id": "FCX8X05SJS3Y18RD5MYFZS62RR", "connection_id": "FCX8X05SJS3Y18RD5MYFZS62RR", } ] } ``` ### シグナリング通知の `data` が含まれなくなる設定 `sora.conf` の以下の設定を全て `false` にした場合、シグナリング通知の `data` が含まれなくなりました - [signaling_notify_metadata](SORA_CONF.html#2d9340) - [signaling_notify_client_id](SORA_CONF.html#fc78ca) - [signaling_notify_bundle_id](SORA_CONF.html#f2a58f) - [signaling_notify_connection_id](SORA_CONF.html#7882d6) - [signaling_notify_connection_created_timestamp](SORA_CONF.html#7fe7b3) ## セッションウェブフック `session.updated` の送信 2023.2.x から `session.updated` ウェブフックを送信するようになりました。 [session_updated_webhook_interval](SORA_CONF.html#4612dc) の設定値の間隔でセッションの状態が通知されるようになります。 もし `session.updated` ウェブフックを受け取る必要がない場合は、 `sora.conf` の `ignore_session_updated_webhook` を `true` に設定してください。 ## ウェブフックなどに利用する信頼された CA 証明書のインストール Sora 2023.2.x から Sora に組み込んでいる CA 証明書ではなく、OS 組み込みの CA 証明書を利用するよう変更しました。 そのため Ubuntu と RHEL (または CentOS) では OS 組み込みの証明書が必要になります。 - Ubuntu の場合は `apt install ca-certificates` で証明書をインストールする必要があります - RHEL (または CentOS) では `dnf install ca-certificates` で証明書をインストールする必要があります ### 影響を受ける機能 - 認証ウェブフック - セッションウェブフック - イベントウェブフック - 音声ストリーミング機能 - 統計エクスポーター機能 ただし、以下の設定で cacert_file を指定している場合は、この影響を受けません。 - [webhook_tls_verify_cacert_file](SORA_CONF.html#7036dc) - [audio_streaming_tls_verify_cacert_file](SORA_CONF.html#feef99) - [stats_exporter_tls_verify_cacert_file](SORA_CONF.html#bcd961) ## ログ出力を JSONL 形式に変更 `sora.log` と `internal.log` のログ出力形式を [JSONL](https://jsonlines.org/) 形式に変更しました。 これは `sora.conf` の `legacy_log_format` を廃止したためです。 2023 年 12 月リリースの Sora にて `legacy_log_format` の設定を廃止しました。 ## ログ出力ファイルの拡張子を `jsonl` に変更 すべての JSONL 形式のログファイルの拡張子を `jsonl` に変更しました。 これは `sora.conf` の `legacy_log_extension` を廃止したためです。 2023 年 12 月リリースの Sora にて `sora_conf-legacy_log_extension` の設定を廃止しました。 ## ウェブフックの audio と video 項目の JSON をフラット構造に変更 ウェブフックで利用する audio と video 項目の JSON 構造を `{"audio": true, "audio_codec_type": "OPUS"}` のようなフラット構造に変更しました。 これは `sora.conf` の `legacy_webhook_audio_video_json_structure` を廃止したためです。 2023 年 12 月リリースの Sora にて `legacy_webhook_audio_video_json_structure` の設定を廃止しました。 以下は変更内容です。 ### ウェブフックリクエスト audio / video #### audio - `{"audio": false}` は変わりません - `{"audio": {"codec_type": "OPUS"}}` は `{"audio": true, "audio_codec_type": "OPUS"}` へフラット化しました - `{"audio": {"bit_rate": 32}}` は `{"audio": true, "audio_bit_rate": 32}` へフラット化しました #### video - `{"video": false}` は変わりません - `{"video": {"codec_type": "VP8"}}` は `{"video": true, "video_codec_type": "VP8"}` へフラット化しました - `{"video": {"bit_rate": 500}}` は `{"video": true, "video_bit_rate": 500}` へフラット化しました ### 認証ウェブフック成功時 audio / video 認証ウェブフック成功時の戻り値に指定する audio と video もフラット化する必要があります。 #### audio - `{"audio": false}` は変わりません - `{"audio": {"codec_type": "OPUS"}}` は `{"audio": true, "audio_codec_type": "OPUS"}` へフラット化して指定する必要があります - `{"audio": {"bit_rate": 32}}` は `{"audio": true, "audio_bit_rate": 32}` へフラット化して指定する必要があります - `{"audio": true, "audio_codec_type": "OPUS", "audio_opus_params": {"useinbandfec": true}}` のように `audio_opus_params` が指定できるようになりました - `{"audio": true, "audio_codec_type": "LYRA", "audio_lyra_params": {"version": "1.3.0"}}` のように `audio_lyra_params` が指定できるようになりました #### video - `{"video": false}` は変わりません - `{"video": {"codec_type": "VP8"}}` は `{"video": true, "video_codec_type": "VP8"}` へフラット化して指定する必要があります - `{"video": {"bit_rate": 500}}` は `{"video": true, "video_bit_rate": 500}` へフラット化して指定する必要があります ### 録画メタデータファイル audio / video 録画メタデータファイルのフラット化の内容はウェブフック audio / video と同様です。 - `{"audio": {"codec_type": "OPUS"}}` は `{"audio": true, "audio_codec_type": "OPUS"}` へフラット化しました - `{"video": {"bit_rate": 1000, "codec_type": "VP9", "height": 480, "width": 640}` は `{"video": true, "video_bit_rate": 1000, "video_codec_type": "VP9", "video_height": 480, "video_width": 640}` へフラット化しました ## レガシー録画から新しい録画への移行 **レガシー録画は 2025 年 12 月リリースの Sora にて廃止します。それまでに移行をお願いします** Sora 2023.2.x から新しくセッション単位の録画機能を追加し、既存の録画機能をレガシー録画機能としました。 - セッション生成ウェブフックの戻り値に `“recording”: true` を含めることで、チャネル開始前に録画開始 API を実行することなく、録画を開始できるようになりました - チャネル終了後に録画終了 API を実行しなくても、セッションの終了時に録画が終了するようになりました - 分割録画で `expire_time` が指定できるようになりました - 接続単位で録画をブロックし、録画ファイルの出力を拒否できるようになりました 詳細は [レガシー録画機能から新しい録画機能 (セッション単位) への移行](LEGACY_RECORDING_TO_RECORDING.html) をご確認ください。 ## クラスターを構成する Sora ノードの `data/` ディレクトリが消えた場合の挙動の変更 [contact_node_name_list](CLUSTER.html#a3d0fd) 設定でクラスターのノードを指定していない場合、 2023.2.0 よりも前は `data/` ディレクトリが消えたノードは、再起動後に [JoinCluster](EXPERIMENTAL_API_CLUSTER.html#17f3f5) API を使って クラスターに再参加させる必要がありました。 2023.2.0 からは `data/` ディレクトリが消えた場合でも、 [JoinCluster](EXPERIMENTAL_API_CLUSTER.html#17f3f5) API の実行は不要になります。 もしこのケースで [JoinCluster](EXPERIMENTAL_API_CLUSTER.html#17f3f5) API を使用した場合には、既に参加済みとしてエラー応答が返されるようになります。 そのため、 2023.2.0 以降の Sora クラスターでは、ローリングアップデート時の [JoinCluster](EXPERIMENTAL_API_CLUSTER.html#17f3f5) API 呼び出しが不要になります。