Ruby用Vonageビデオ移行ガイド

からの移行 OpenTok-Ruby-SDK への vonage-ruby-sdk

はじめに

目的

このドキュメントの目的は、OpenTok Ruby Server SDK から Vonage Ruby Server SDK への移行の出発点を提供することです。

スコープ

この文書では、少なくともバージョン4.9.0以降を使用していることを前提としています。 OpenTok Ruby SDK.Video API の初期実装が Ruby Server SDK に追加されました。 バージョン7.19.0に追加機能が実装されている。 バージョン7.24.0.しかし、移行には 現在の最新 Vonage Ruby SDKのバージョンは、次のサイトでご覧いただけます。 ギットハブ または ルビー宝石.

前提条件

本ガイドは、プロのソフトウェア・エンジニアを対象としています。少なくとも、Ruby、一般的なRuby開発ツール、Git（またはその他のバージョン管理システム）の基本的な能力があることを前提としています。Ruby コードの読み書き、プロジェクトの依存関係の管理、Ruby プロジェクトのデプロイと実行に慣れている必要があります。Ruby言語、プラットフォーム、関連ツールの紹介は、このドキュメントの範囲を超えています。

リソース

以下のリンクは、この文書に付随するさらなる読み物や、この文書でカバーされていないことを参照するのに便利です：

ボネージ

• Vonage ビデオ・ドキュメント
• Vonage Video API 仕様
• Vonage Ruby Server SDK ビデオ使用ガイド
• Vonage Ruby Server SDK Rubydocs
• Vonage Ruby Server SDK 動画ソースコード
• Vonage Ruby Server SDK GitHub リポジトリ
• Vonage Ruby Server SDKがRubyGemsで成果物を公開

トクボックス

• OpenTok API REST リファレンス
• OpenTok Ruby Server SDK ドキュメント
• OpenTok Ruby Server SDKソースコード
• OpenTok Ruby Server SDK GitHub リポジトリ
• OpenTok Ruby Server SDKがRubyGemsで成果物を公開

移行計画

OpenTokからVonage Videoに移行する前に、現実的な期待値を設定するために、タスクの規模を考慮する必要があります。

影響を評価する

マイグレーションがあなたのアプリケーションに与える影響を評価するために、検討する必要がある質問がいくつかあります。

1. いくら アプリケーションのコードのうち、OpenTok SDK に依存していますか？SDKが直接使用されているすべてのファイルのリストを作成してください。これを決定するひとつの方法は .rb ファイルには require 'opentok' を参照してください。例えば、プロジェクト内のファイルを検索して、次のステートメントを見つけることができます。 require 'opentok' コードエディター、IDE、コマンドラインツールを使用して、影響を受けるファイルを特定する。

2. 何人 あなたのアプリケーションは OpenTok SDK のどの機能を使用していますか？例えば、ビデオセッションの作成と Client トークンの生成にのみ SDK を使用しているアプリケーションは、アーカイブ、ブロードキャスト、モデレーション、その他の機能も使用しているアプリケーションよりも移行が簡単である可能性が高いです。

3. どれ あなたのアプリケーションはOpenTok SDKのどの機能を利用していますか？機能によっては、他の機能よりも移行に手間がかかる場合があります。詳細は 主な変更点と考慮事項 2つのSDKの実装間の変更の詳細については、こちらをご覧ください。

4. どのように 密結合 アプリケーション・コードに OpenTok SDK を使用していますか？例えばRuby on Railsアプリケーションの場合、SDKのメソッドをコントローラ・アクションで直接呼び出していますか、それとも何らかの方法で（例えばGatewayパターンやAdapterパターンを使って）メソッド呼び出しを抽象化していますか？

また、あなたの特定のプロジェクトには、上記以外の考慮事項があるかもしれません。

タイムライン

移行を完了するために必要な時間を考慮してください。これは、プロジェクトに精通しているか、プロジェクトを移行することによる影響など、さまざまな要因によって異なります。 上記).OpenTokとVonage Videoの実装間の同等性を検証できるように、優れたテスト・スイートを用意することが重要です。移行完了までにかかる時間は おおよそ OpenTok SDK があなたのコードで使用されている場所の数と、使用されている機能の多様性に比例しますが、前述のように、いくつかの API 呼び出しは、他の API 呼び出しよりも簡単に置き換えることができます。

バージョニング

OpenTokとVonage Videoは2つの異なる製品です。このため、段階的な移行は不可能です。

移行用の一時的なブランチをバージョン管理システム上に作っておくと、 既存のプロジェクトを壊すことなく、少しずつ頻繁に変更を加えることができます。既存のプロジェクトのテストを、正しさを確認するためのオラクルとして使うこともできます。移行用ブランチをメインブランチにマージするのは、変換が完了してからにするのが理想的です。

主な変更点と考察

Vonage Video APIはOpenTokと同等の機能を持ち、Ruby SDKはAPI仕様に沿うよう積極的にメンテナンスされています。しかし、2つのSDKの間には、いくつか注意すべき違いがあります。

新機能と規格

パッケージ構造

OpenTok Ruby SDK と Vonage Ruby SDK はどちらも Bundlerが推奨するRuby gemsの構造化アプローチというように、高いレベルでは構造が似ている。しかし、いくつかの重要な違いがある：

1. Vonage Ruby SDK は ツァイトワーク ライブラリをコード自動ロードのために使用しているため、ファイルやディレクトリの構造や命名についてはzeitwerkの規約に従っています。Ruby on Railsアプリケーションがどのような構造になっているかご存じであれば、これらの規約はすでにご存知でしょう。そうでない場合は、数分費やしてみる価値があるかもしれません。 慣れ親しむ.この構造をVideo APIの実装という観点から考えてみる：

• 主要な Video クラスは このファイル
• で名前空間化されたクラスは、すべて Video など Video::Broadcasts そして Video::Archivesの下で定義される。 このディレクトリ.

2. Vonage Ruby SDK は Video API 以外にも Vonage API を実装しています。SDK はこれらの API 製品を表すクラスを実装しています。 Client クラスは、これらのクラスのオブジェクトに対するアクセサを提供します。

上記の1と2を念頭に置き、Vonageから出発する。 Client オブジェクトを呼び出すには、呼び出したい特定の Video API エンドポイントを表すメソッドにたどり着くまでに、1 つ以上の追加のメソッド呼び出しが必要になるかもしれない。

例1：セッションの作成

OpenTok Ruby SDKを使用すると、次のようになります：

# 1: instantiate an `OpenTok` object (assuming credentials stored as environment variables)
opentok = OpenTok::OpenTok.new(
  ENV['OPENTOK_API_KEY'],
  ENV['OPENTOK_API_SECRET']
)

# 2: invoke the `create_session` method on the `OpenTok` object
session = opentok.create_session

Vonage Ruby SDKを使用する場合は、次のようになります：

# 1: instantiate a Vonage `Client` object (assuming credentials stored as environment variables)
client = Vonage::Client.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)

# 2: access the `Video` object
video = client.video

# 3: invoke the `create_session` method on the `Video` object
session = video.create_session

Rubyで期待されるように、メソッドチェイニングによってステップ2と3を組み合わせることができる：

session = client.video.create_session

例2：アーカイブ録画のリストを取得する

OpenTok Ruby SDKを使用すると、次のようになります：

# 1: instantiate an `OpenTok` object
opentok = OpenTok::OpenTok.new(
  ENV['OPENTOK_API_KEY'],
  ENV['OPENTOK_API_SECRET']
)

# 2: access the `Archives` object
archives = opentok.archives

# 3: invoke the `all` method on the `Archives` object
archive_list = archives.all

Vonage Ruby SDKを使用する場合は、次のようになります：

# 1: instantiate a Vonage `Client` object
client = Vonage::Client.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)

# 2: access the `Video` object
video = client.video

# 3: access the `Archives` object
archives = video.archives

# 4: invoke the `list` method on the `Archives` object
archive_list = archives.list

ここでも、メソッドチェイニングによってステップを組み合わせることができる：

archive_list = client.video.archives.list

タイピングについて

Vonage Ruby SDK は ソルベ を使用して静的型チェックを行います。OpenTok Ruby SDK から Vonage Ruby SDK への移行を簡素化するため、Video API 実装のメソッドの型シグネチャは現在定義されていません。型シグネチャは将来のリリースの一部としてこれらのメソッドに定義される予定です。

フロントエンドの変更について

あなたのアプリケーションに使用されるフロントエンド・ライブラリは、OpenTokライブラリと同じです。ただし、使い方の点で1つだけ小さな変更があります。

SDKはセッションを作成し、フロントエンド・クライアント・ライブラリがそれらのセッションにアクセスするためのトークンを生成します。OpenTokの実装と同じように、フロントエンドクライアントライブラリはバックエンドサーバに セッションID そして トークン.しかし、Vonageの実装では、サーバーもまた アプリケーションID.このアプリケーションIDは、実質的に APIキー OpenTokの実装で使用されるフロントエンド・クライアント・ライブラリは、OpenTokの実装で使用されます。 ラベル をAPIキーとして使用します。アプリケーションIDの詳細については、以下のセクションを参照してください。 認証の変更.

フロントエンドとバックエンドの相互作用におけるこの小さな変更は、例えば、ビューテンプレートや、それらのビューテンプレートにデータを渡すロジックにおいて、あなたの実装にいくつかの小さな更新を必要とするかもしれません。

パッケージ・アップデート

Vonage Ruby SDKを使用するには、プロジェクトの依存関係を更新して vonage の代わりに opentok Ruby gemです。これを行うには Gemfile を含める。 vonage 宝石だ：

gem "vonage"

そして bundle install.

認証の変更

一方 opentok ジェムは api_key そして api_secret の Video API 実装は、Authorization のためのものです。 vonage gemはJWTを使用します。SDKはJWTの生成をバックグラウンドで処理しますが、JWTの生成には application_id そして private_key を認証情報として使用してトークンを生成します。Vonageアプリケーションをセットアップし、そのアプリケーション用のアプリケーションIDと秘密鍵を生成することで、これらを取得することができます。Vonageアプリケーションは、アプリケーションがどのAPI製品で有効になっているか、コールバックURL、ストレージ設定など、その他の設定を行う場所でもあります。

Vonageアプリケーションを作成する方法はいくつかあります：

• を経由する。 開発者ダッシュボード
• を経由する。 アプリケーションAPI
• を使用する。 Vonage CLI

あなたの application_id そして private_key クレデンシャルが渡される。 Client オブジェクトを作成します（以下の例では、環境変数として設定されていることを前提としています）：

client = Vonage::Client.new(
	application_id: ENV['VONAGE_APPLICATION_ID'],
	private_key: ENV['VONAGE_PRIVATE_KEY']
)

上記の例のように環境変数に名前を付けておけば、実際には new メソッド呼び出し。SDKは自動的に ENV ハッシュでその名前の変数を探し、見つかったらその値を使う。この場合、次の例は Vonage::Client オブジェクトは、機能的には前のものと同等である：

client = Vonage::Client.new

の値であることに注意してください。 VONAGE_PRIVATE_KEY の場所へのパスを指定します。 private.key ファイルへのパスを指定します。このパスの値をどのように決定するかは、アプリケーションをどのようにデプロイするかによって異なります。アプリケーションをローカルにデプロイする場合は private.key ファイルをプロジェクトのルートに置き、パスを private.key.例えば ドットエンブ を使用して環境変数を管理します。 VONAGE_PRIVATE_KEY を定義する。 .env ファイルは次のようになる：

VONAGE_PRIVATE_KEY=private.key

などのサービスを使用して本番環境にデプロイする場合、次のようになる。 レンダーこの種のサービスは通常、秘密鍵などのファイルを安全に保管する方法を提供 している。その正確な方法は、使用するサービスによって異なり、本文書の範囲外である。

メソッドの変更

OpenTok Ruby SDK と Vonage Ruby SDK の Video API 実装の間には、いくつかのメソッドの変更があります。

メソッド・パラメータ

Vonage SDKでは、メソッド・シグネチャの位置パラメータはすべてキーワード・パラメータに置き換えられました。

メソッド名の変更

いくつかのメソッドは、わかりやすくするため、あるいはそのメソッドが何をするのかをよりよく反映させるために、名前が変更されたり、移動されたりしている。以下に列挙する：

応答オブジェクト

OpenTok Ruby SDKとは異なり、Vonage Ruby SDKはHTTPレスポンスのJSONペイロードをデシリアライズする際に特定のオブジェクトクラスを使用しません。

単一リソース・レスポンス・オブジェクト

JSONペイロードが単一のリソースを表すレスポンスは、Vonage Ruby SDKによって一般的な Vonage::Response オブジェクトがある。

一般的なレベルでは、次のように使用できます。 Vonage::Response オブジェクトを作成するのと同じ方法で OpenTok::Archive, OpenTok::Broadcast, OpenTok::Streamなどのオブジェクトと同じように、プロパティ名と同じ名前を持つオブジェクトのメソッドを呼び出すことで、レスポンスのペイロードからプロパティにアクセスすることができます。たとえば、新しいアーカイブ録画を開始し、そのIDをレスポンスから取得したい場合、これを行うためのアプローチは、2つのSDKでほぼ同じになります。

例OpenTok Ruby SDK

opentok = OpenTok::OpenTok.new(
  ENV['OPENTOK_API_KEY'],
  ENV['OPENTOK_API_SECRET']
)
session = opentok.create_session
archive = opentok.archives.create(session.session_id) # => returns a OpenTok::Archive object

# calling the `id` method on the object returns the value of the `id` property in the JSON payload
archive.id

例Vonage Ruby SDK

client = Vonage::Client.new.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)
session = client.video.create_session
archive = client.video.archives.start(session_id: session.session_id) # => returns a Vonage::Response object

# calling the `id` method on the object returns the value of the `id` property in the JSON payload
archive.id

2つのSDKのレスポンス・オブジェクトの実装における重要な違いの1つは、OpenTok Ruby SDKのレスポンス・オブジェクトにおけるファサード・パターンの使用です。OpenTok SDKのレスポンス・オブジェクトは、それを生成したメソッドを呼び出したオブジェクトへの参照で初期化されます。このオブジェクトは OpenTok::Client オブジェクトを直接呼び出すことができます。これは、Video API エンドポイントの一部と相互作用するメソッドを、これらのオブジェクトで直接呼び出せることを意味します。Vonage Ruby SDK のレスポンスオブジェクトは、Video API エンドポイントをラップするメソッドを直接呼び出す方法を提供していないため、メソッドの呼び出し元として特定の機能クラスを表すオブジェクトを使用する必要があります。

例えば、現在進行中のアーカイブ録画を停止したいとします。

例OpenTok Ruby SDK

OpenTok SDKでは、次のように呼び出すことができます。 stop メソッドを直接 Archive オブジェクトが返す Archives#create メソッドを呼び出す。

opentok = OpenTok::OpenTok.new(
  ENV['OPENTOK_API_KEY'],
  ENV['OPENTOK_API_SECRET']
)
session = opentok.create_session
archives = opentok.archives
archive_1 = archives.create(session.session_id) # => returns a OpenTok::Archive object

# calling the `stop` method directly on the returned OpenTok::Archive object stops the archive recording
archive_1.stop

例Vonage Ruby SDK

Vonage SDKでは stop メソッドを Video::Archives オブジェクトに関連する archive_id を引数に取る。

client = Vonage::Client.new.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)
session = client.video.create_session
archives = client.video.archives
archive_1 = archives.start(session_id: session.session_id) # => returns a Vonage::Response object

# calling the `stop` method on a Video::Archives object, passing in the `id` of the archive you want to stop
archives.stop(archive_id: archive_1.id)

マルチ・リソース・レスポンス・オブジェクト

JSONペイロードが1つ以上のリソースのコレクションを表すレスポンスは、Vonage Ruby SDKによってデシリアライズされて ListResponse オブジェクトの名前空間がproductの下にあり、次にリクエストを行ったオブジェクトタイプ、例えば Vonage::Video::Broadcasts::ListResponse.

基本的には、OpenTok Ruby SDK のリストレスポンスオブジェクトタイプと同じ機能を提供します。実装はSDKによって若干異なりますが、一般的には、これらのオブジェクトを操作する方法に影響を与えることはありません：

• について ListResponse オブジェクトを実装しています。 each メソッドを使用し、Rubyの Enumerable モジュールである。
• OpenTok Ruby SDK のリスト型レスポンス (たとえば ArchiveList, BroadcastListなど）サブクラスは、Rubyの Array クラスである。

エラー応答オブジェクト

どちらのSDKも、Rubyの StandardError クラスがあり、その汎用クラスをサブクラス化したより特殊なエラークラスがある。

OpenTok Ruby SDK は OpenTok::OpenTokError クラスからサブクラス化された機能タイプごとに特定のエラークラスが作成される。 OpenTokErrorなど。 OpenTokArchiveError, OpenTokBroadcastError, OpenTokAuthenticationErrorなど。これらのエラー・タイプは、いずれも StandardError を提供する。

Vonage Ruby SDK は汎用的な Vonage::Error クラスと Vonage::APIError をサブクラス化したクラスです。 Vonage::Error.その APIError クラスは Vonage API エンドポイントへの HTTP リクエストに起因するエラーを表します。SDKは次に、受信したレスポンスの性質に応じて、より具体的なエラークラスを定義します。 APIError.これらのクラスには以下が含まれる。 Vonage::ClientError (に対して 4xx 回答）、 Vonage::ServerError (に対して 5xx 反応）、そして Vonage::AuthenticationError (のサブクラス）。 Vonage::ClientError特に次のような用途に使用される。 401 回答）。

について APIError クラスのゲッターメソッドを提供する追加ロジックを実装しています。 Net:HTTPResponse オブジェクトと、レスポンスコード、ヘッダ、ボディです。これらのプロパティにアクセスするには、例外をレスキューします。

例

client = Vonage::Client.new.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)

begin
  session = client.video.create_session
rescue Vonage::APIError => error
  if error.http_response
    error.http_response # => #<Net::HTTPUnauthorized 401 Unauthorized readbody=true>
    error.http_response_code # => "401"
    error.http_response_headers # => {"date"=>["Sun, 24 Sep 2023 11:08:47 GMT"], ...rest of headers}
    error.http_response_body # => {"title"=>"Unauthorized", ...rest of body}
  end
end

マイグレーション戦略

インクリメンタル・マイグレーション

あるユースケースから別のユースケースへ移行し、「安定」状態になるたびにコミットする、インクリメンタルな移行をお勧めします。もちろん、OpenTokとVonage Video APIの両方を一時的に共存させる必要があります。

OpenTokとVonage Video APIは完全に異なる2つのシステムであるため、このようなインクリメンタル・プロセスの間、アプリケーション全体が完全に機能しなくなることにご注意ください。

インクリメンタル・アプローチの正確な計画は、使用している Video API 機能の数や種類、またそれらの機能をアプリケーションにどのように統合しているかによって異なります。この領域で実装固有のガイダンスを提供することはできませんが、一般的なアプローチとしては、機能ごとにコードを更新し、各機能のメソッドごとにコードを更新することが考えられます。

をインスタンス化するコードから始めるのがよいでしょう。 OpenTok::OpenTok オブジェクトをインスタンス化するコードに置き換える。 Vonage::Client で示した両者の比較に続く。 パッケージ構造 セクションを参照されたい。

次のステップは、セッションの作成、クライアント・トークンの生成、フロントエンドのクライアント・ライブラリへのデータの受け渡しを扱うコードを更新することだ。

その後、Video API の特定の機能を実装するコードを順番に更新していくことができます。アーカイブを例に挙げると

• 以下のコードを特定する。 Archives が作成されたり、相互作用されたりする。
• でメソッドが呼び出されるように、メソッドの呼び出しを更新する。 client.video の代わりに opentok オブジェクトがある。
• メソッド名の更新 変わったこと.
• メソッド呼び出しが引数を渡す場合は、正しいキーワードパラメータを使用するように更新する。
• メソッドが Archive レスポンスオブジェクトを修正する。 応答オブジェクト セクションを参照されたい。

各フィーチャーとメソッドについて、このプロセスを繰り返す。

また、次のような追加ステップが必要な場合もあります。 特定エラーの救済.上記のステップリストはすべてを網羅しているわけではありませんが、移行計画を定義するための良い出発点となることを願っています。

ゲートウェイ／アダプター・パターン

もしあなたがまだ実装の一部として何らかのゲートウェイやアダプター・パターンを使っていないのであれば、この移行はそうする良い機会になるだろう。これは移行を容易にするだけでなく、一般的な使用方法として、アプリケーション・コードとSDKコードとの緊密な結合が少なくなることを意味する。

これらのパターンを実装するには、アプリケーションの構造や使用しているフレームワークによって、さまざまなアプローチがあります。この分野で具体的なガイダンスを提供することは、このドキュメントの範囲を超えています。

テストに関する推奨事項

移行中も移行後も、スムーズな移行には徹底したテストが欠かせない。これには単体テストだけでなく、統合テストや回帰テストも含まれます。また、自動化されたテストがあなたが考えているとおりに実行されていることを確認するため、あるいはテストが検出できなかったかもしれない問題を検出するために、移行前と移行後に少なくとも1回はアプリケーションフローを手動でテストする価値があります。等価テストを作成することを検討してもよいでしょう。これは、OpenTok と Vonage Video の両方のバージョンのアプリケーションが同じことを行うことを保証するスイートを作成することです。移行が完了し、OpenTok バージョンのアプリケーションが削除されたら、これらのテストは破棄することができます。

トラブルシューティング＆サポート

サポート・チャンネル

Vonage Videoへの移行に関する一般的なヘルプやディスカッションについては、以下をご覧ください。 コミュニティSlackの#Video-APIチャンネルここでは、Vonageスタッフや他のユーザーから回答を得ることができます。また X VonageDev.

Video API自体に問題がある場合の主な連絡先は以下の通りです。 support@api.vonage.com.

SDKのバグを発見した場合は、以下の連絡先までご連絡ください。 GitHubにissueを提出する。.

その他のリソース

コードサンプル

• Sinatraを使った基本的なマルチパーティービデオ通話