Guía de transición a Vonage Video para Ruby

Transición de OpenTok-Ruby-SDK a vonage-ruby-sdk

Introducción

Propósito

El objetivo de este documento es brindar un punto de partida para la transición de OpenTok Ruby Server SDK a Vonage Ruby Server SDK.

Ámbito de aplicación

En este documento se da por hecho que estás utilizando, como mínimo, la versión 4.9.0 o posterior del SDK de OpenTok para Ruby. Se añadió una implementación inicial de la Video API al SDK del servidor Ruby en versión 7.19.0con funciones adicionales implementadas en versión 7.24.0. Sin embargo, para su migración le recomendamos que utilice el lo último versión del SDK de Vonage Ruby, que se puede encontrar en GitHub o RubyGems.

Supuestos

Esta guía está dirigida a ingenieros de software profesionales. Se da por supuesto que el lector cuenta, como mínimo, con un nivel básico de conocimientos de Ruby, de las herramientas habituales para desarrolladores de Ruby y de Git (u otro sistema de control de versiones). El lector debe sentirse cómodo leyendo y escribiendo código Ruby, gestionando las dependencias de un proyecto, así como implementando y ejecutando un proyecto en Ruby. Una introducción al lenguaje Ruby, a la plataforma y a las herramientas asociadas queda fuera del alcance de este documento.

Recursos

Los siguientes enlaces son útiles como lecturas complementarias de este documento y como referencia para todo lo que no se haya tratado en él:

Vonage

• Documentación de vídeo de Vonage
• Especificación de la API de Video de Vonage
• Vonage Ruby Server SDK Guía de uso en video
• Rubydocs del SDK para servidores de Vonage Ruby
• Código fuente de vídeo del SDK de servidor Ruby de Vonage
• Repositorio de GitHub del SDK para servidores Ruby de Vonage
• Artifactos del SDK para servidores de Vonage Ruby publicados en RubyGems

TokBox

• Referencia REST de la API de OpenTok
• Documentación del SDK del servidor Ruby de OpenTok
• Código fuente del SDK para servidor de OpenTok en Ruby
• OpenTok Ruby Server SDK GitHub repo
• Artefactos publicados del SDK del servidor Ruby de OpenTok en RubyGems

Planificación de la migración

Antes de realizar la transición de OpenTok a Vonage Video, debes tener en cuenta la magnitud de la tarea para establecer expectativas realistas.

Evaluar el impacto

Para evaluar el impacto de la migración en tu aplicación, hay algunas cuestiones que deberás tener en cuenta.

1. ¿Cuánto? del código de tu aplicación depende del SDK de OpenTok? Haz una lista de todos los archivos en los que se utiliza directamente el SDK. Una forma de determinar esto podría ser identificar cualquier archivo .rb archivo que contiene un require 'opentok' referencia. Por ejemplo, puede buscar en los archivos de su proyecto la sentencia require 'opentok' utilizando un editor de código, un IDE o una herramienta de línea de comandos para identificar los archivos afectados.

2. ¿Cuántos de las funciones del SDK de OpenTok utiliza tu aplicación? Por ejemplo, una aplicación que utilice el SDK únicamente para crear sesiones de vídeo y generar tokens de cliente probablemente será más sencilla de migrar que una que también utilice funciones de archivo, difusión, moderación y otras.

3. Qué de las funciones del SDK de OpenTok utiliza tu aplicación? Algunas funciones pueden requerir más esfuerzo de migración que otras. Consulte la Cambios y consideraciones clave para más detalles sobre los cambios entre la implementación de los dos SDK.

4. Cómo estrechamente acoplado ¿es el código de tu aplicación con el SDK de OpenTok? En el contexto de una aplicación Ruby on Rails, por ejemplo, ¿estás invocando métodos del SDK directamente en las acciones de tu controlador, o has abstraído esas llamadas a métodos de alguna manera (por ejemplo, mediante el uso del Patrón Gateway o el Patrón Adapter)?

Es posible que haya otras consideraciones relacionadas con tu proyecto concreto que no se hayan mencionado anteriormente.

Cronología

Tenga en cuenta el tiempo necesario para completar la transición. Esto dependerá de una serie de factores, como su familiaridad con el proyecto y el impacto de la migración del proyecto (como se describe a continuación). arriba). Es fundamental contar con un buen conjunto de pruebas para poder verificar la equivalencia entre las implementaciones de OpenTok y Vonage Video. El tiempo que llevará completar la transición es aproximadamente proporcional al número de lugares en los que se utiliza el SDK de OpenTok en tu código, así como a la variedad de funciones utilizadas, pero, como ya se ha mencionado, algunas llamadas a la API serán más sencillas de sustituir que otras.

Versionado

OpenTok y Vonage Video son dos productos diferentes. Esto hace imposible una migración progresiva.

Deberías crear una rama temporal en tu sistema de control de versiones para la transición, de forma que puedas hacer cambios gradualmente y con frecuencia sin romper el proyecto existente. También puede utilizar las pruebas del proyecto existente como un oráculo para la corrección. Lo ideal sería fusionar la rama de transición con la rama principal una vez completada la conversión.

Cambios y consideraciones clave

La Video API de Vonage ofrece las mismas funciones que OpenTok, y el SDK de Ruby se mantiene de forma activa para que se ajuste a la especificación de la API. Sin embargo, existen algunas diferencias entre ambos SDK que debes tener en cuenta.

Nuevas funciones y normas

Estructura del paquete

Tanto el SDK Ruby de OpenTok como el SDK Ruby de Vonage siguen la norma Enfoque para estructurar las gemas de Ruby recomendadas por Bundler, por lo que, a grandes rasgos, tienen una estructura similar. Sin embargo, hay un par de diferencias clave:

1. El SDK de Vonage Ruby utiliza el zeitwerk para la autocarga de código, por lo que sigue las convenciones de zeitwerk en cuanto a estructura y nomenclatura de archivos y directorios. Si sabes cómo se estructuran las aplicaciones Ruby on Rails, entonces ya estarás familiarizado con estas convenciones. Si no, puede que merezca la pena dedicar unos minutos a familiarizarse con ellos. Considerando esta estructura en términos de implementación de la Video API:

• El principal Video se define en este archivo
• Cualquier clase que pertenezca al espacio de nombres Video (como Video::Broadcasts y Video::Archives) se definen en este directorio.

2. El SDK Ruby de Vonage implementa otras API de Vonage además de la Video API. El SDK implementa clases que representan cada uno de estos productos de API, y la clase Client proporciona accesores para los objetos de estas clases.

Teniendo en cuenta los puntos 1 y 2 anteriores, partiendo de Vonage Client pueden ser necesarias una o más invocaciones de métodos adicionales antes de llegar al método que representa el punto final específico de la Video API al que desea llamar.

Ejemplo 1: Creación de una sesión

Usando el SDK Ruby de OpenTok podría verse algo como esto:

# 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

Mientras que usando el SDK Ruby de Vonage podría verse algo como esto:

# 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

Como es de esperar en Ruby, puedes combinar los pasos 2 y 3 mediante el encadenamiento de métodos:

session = client.video.create_session

Ejemplo 2: Obtener una lista de grabaciones de archivo

Usando el SDK Ruby de OpenTok podría verse algo como esto:

# 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

Mientras que usando el SDK Ruby de Vonage podría verse algo como esto:

# 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

Una vez más, los pasos se pueden combinar mediante el encadenamiento de métodos:

archive_list = client.video.archives.list

Nota sobre la escritura

El SDK de Vonage Ruby utiliza Sorbete para la comprobación estática de tipos. Para facilitar la migración de OpenTok Ruby SDK a Vonage Ruby SDK, actualmente no se han definido firmas de tipos para ninguno de los métodos de la implementación de Video API. Las firmas de tipo se definirán para estos métodos como parte de una futura versión.

Nota sobre los cambios en la interfaz de usuario

Las bibliotecas de front-end que se utilizan en tu aplicación serán las mismas que las de OpenTok. Sin embargo, hay un pequeño cambio en cuanto a su uso.

La interacción entre el back-end y el front-end será la misma: el SDK creará sesiones y también generará tokens para que las bibliotecas de cliente del front-end puedan acceder a dichas sesiones. Al igual que en una implementación de OpenTok, las bibliotecas de cliente del front-end esperarán que el servidor de back-end proporcione un ID de sesión y un ficha. Sin embargo, con una implementación de Vonage, el servidor también tendrá que proporcionar un ID de la solicitud. Este identificador de aplicación sustituye al identificador Clave API que se utilizarían en una implementación de OpenTok, aunque las bibliotecas de cliente front-end seguirán siendo etiqueta como Clave API. Para obtener más información sobre los ID de Aplicaciones, consulte la sección sobre Cambios en la autenticación.

Este pequeño cambio en la interacción entre el front-end y el back-end puede requerir algunas actualizaciones menores en tu implementación, por ejemplo, en tus plantillas de vista o en la lógica que pasa datos a dichas plantillas.

Actualización del paquete

Para utilizar el SDK Ruby de Vonage, deberás actualizar las dependencias de tu proyecto para que utilicen el módulo vonage Ruby en lugar de la gema opentok Gema de Ruby. Para ello, actualiza tu Gemfile para incluir el vonage joya:

gem "vonage"

y luego ejecutar bundle install.

Cambios en la autenticación

Considerando que el opentok utiliza una gema api_key y api_secret Para la autorización, la implementación de la Video API en el vonage gem utiliza un JWT. El SDK se encarga de generar el JWT en segundo plano por ti, pero necesitará un application_id y private_key como credenciales para generar el token. Puedes obtenerlas configurando una aplicación de Vonage y generando un ID de aplicación y una clave privada para esa aplicación. La aplicación de Vonage también es donde puedes establecer otras configuraciones, como los productos de API para los que está habilitada la aplicación, las URL de devolución de llamada, las preferencias de almacenamiento, etc.

Hay varias formas de crear una aplicación de Vonage:

• A través de la Panel de control para desarrolladores
• A través de la API de la aplicación
• Utilizando el CLI de Vonage

Tu application_id y private_key se introducen al crear una instancia de Client objeto (en el ejemplo siguiente se da por hecho que las tienes configuradas como variables de entorno):

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

Si tiene sus variables de entorno nombradas como se muestra en el ejemplo anterior, puede omitir los argumentos del comando new a la invocación del método. El SDK buscará automáticamente el ENV en busca de variables con esos nombres y utiliza sus valores si los encuentra. En este caso, el siguiente ejemplo de instanciación de una variable Vonage::Client es funcionalmente equivalente al anterior:

client = Vonage::Client.new

Tenga en cuenta que el valor de VONAGE_PRIVATE_KEY puede ser la ruta a la ubicación de su private.key archivo. La forma de determinar el valor de esta ruta dependerá de cómo esté desplegando su aplicación. Si está desplegando su aplicación localmente, puede almacenar su archivo private.key en la raíz de su proyecto y establezca la ruta como private.key. Por ejemplo, si se utiliza dotenv para gestionar sus variables de entorno, su VONAGE_PRIVATE_KEY definición en tu .env tendría el siguiente aspecto:

VONAGE_PRIVATE_KEY=private.key

Si se despliega en producción utilizando un servicio como RenderPor lo general, este tipo de servicios ofrecen formas de almacenar de forma segura archivos como claves privadas. El método exacto para hacerlo dependerá del servicio que se utilice y queda fuera del alcance de este documento.

Cambios de método

Hay algunos cambios en los métodos entre OpenTok Ruby SDK y la implementación de Video API en Vonage Ruby SDK.

Parámetros del método

Cualquier parámetro posicional en las firmas de métodos ha sido reemplazado por parámetros de palabras clave en el SDK de Vonage.

Cambios en los nombres de los métodos

Se han renombrado y/o reubicado algunos métodos, en aras de la claridad y/o para reflejar mejor la función de cada uno. A continuación se enumeran:

Objetos de respuesta

A diferencia del SDK de OpenTok para Ruby, el SDK de Vonage para Ruby no utiliza clases de objetos específicas al deserializar la carga útil JSON de una respuesta HTTP, sino que deserializa las respuestas en objetos de respuesta genéricos.

Objetos de respuesta de recurso único

Las respuestas en las que la carga útil JSON representa un único recurso son deserializadas por el SDK Ruby de Vonage a un archivo genérico Vonage::Response objeto.

A nivel general, puede utilizar lo siguiente Vonage::Response de la misma forma que lo haría con el objeto OpenTok::Archive, OpenTok::Broadcast, OpenTok::Stream, etc., objetos en los que se puede acceder a las propiedades de la carga útil de la respuesta llamando a métodos del objeto cuyos nombres son equivalentes a los de las propiedades. Por ejemplo, si quisieras iniciar una nueva grabación de archivo y obtener su ID de la respuesta, el procedimiento para hacerlo sería, en líneas generales, similar en ambos SDK.

Ejemplo: SDK Ruby de OpenTok

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

Ejemplo: SDK Ruby de Vonage

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

Una diferencia clave en la implementación de los objetos de respuesta entre los dos SDK radica en el uso del patrón «fachada» en los objetos de respuesta del SDK de Ruby de OpenTok. Los objetos de respuesta del SDK de OpenTok se inicializan con una referencia al objeto que invocó el método que los creó. Ese objeto, a su vez, contiene una referencia a un OpenTok::Client objeto. Esto significa que puedes invocar métodos que interactúan con algunos de los puntos finales de la Video API directamente en esos objetos. Los objetos de respuesta en el SDK Ruby de Vonage no proporcionan una forma directa de llamar a los métodos que envuelven los puntos finales de la Video API, por lo que tendrás que usar objetos que representen la clase de función específica como la persona que llama al método.

Digamos, por ejemplo, que quieres detener una grabación de archivo que está en curso.

Ejemplo: SDK Ruby de OpenTok

En el SDK de OpenTok se puede llamar a la función stop directamente en el Archive devuelto por el objeto Archives#create invocación del método.

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

Ejemplo: SDK Ruby de Vonage

En el SDK de Vonage tendrías que llamar a la función stop en un Video::Archives objeto y pasar los datos pertinentes archive_id como argumento.

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)

Objetos de respuesta con múltiples recursos

Las respuestas en las que la carga útil JSON representa una colección de uno o más recursos son deserializadas por el SDK Ruby de Vonage a un archivo ListResponse los nombres de los objetos que pertenecen al espacio de nombres «product» y, a continuación, el tipo de objeto que realizó la solicitud; por ejemplo: Vonage::Video::Broadcasts::ListResponse.

Básicamente, ofrecen la misma funcionalidad que los tipos de objetos de respuesta de lista del SDK de Ruby de OpenTok, ya que son colecciones iterables de objetos de recursos individuales. La implementación difiere ligeramente entre los distintos SDK, pero, en general, esto no debería afectar a la forma en que se puede interactuar con estos objetos; a continuación se describe con más detalle, más bien por motivos de exhaustividad:

• El ListResponse Los objetos del SDK de Ruby de Vonage implementan un each e incluir el método Enumerable módulo.
• Las respuestas de tipo lista en el SDK de Ruby de OpenTok (por ejemplo, ArchiveList, BroadcastListetc) de la subclase de Ruby Array clase.

Objetos de respuesta de error

Ambos SDKs definen una clase de error genérico que subclase de Ruby's StandardError clase, con clases de error más específicas que son subclases de esa clase genérica.

El SDK Ruby de OpenTok define un módulo OpenTok::OpenTokError clase y, a continuación, clases de error específicas por tipo de característica que son subclases de OpenTokError, como OpenTokArchiveError, OpenTokBroadcastError, OpenTokAuthenticationError, etc. Ninguno de estos tipos de error implementa ninguna funcionalidad adicional más allá de lo que StandardError establece.

El SDK de Vonage Ruby define un Vonage::Error clase y también un Vonage::APIError clase que hereda de Vonage::Error. En APIError La clase representa los errores que se producen como resultado de una solicitud HTTP a un punto final de la API de Vonage. A continuación, el SDK define varias clases de error más específicas, según la naturaleza de la respuesta recibida, que son subclases de APIError. Entre estas clases se incluyen Vonage::ClientError (para 4xx respuestas), Vonage::ServerError (para 5xx respuestas), y Vonage::AuthenticationError (que es una subclase de Vonage::ClientErrory se utiliza específicamente para 401 respuestas).

El APIError implementa cierta lógica adicional que proporciona métodos getter para la clase Net:HTTPResponse así como el código de respuesta, las cabeceras y el cuerpo. Puedes rescatar la excepción para acceder a estas propiedades.

Ejemplo

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

Estrategias de migración

Migración incremental

Recomendaríamos una migración incremental, pasando de un caso de uso a otro, comprometiéndose cada vez que se llegue a un estado "estable". Por supuesto, esto requeriría que OpenTok y Vonage Video API coexistieran temporalmente.

Ten en cuenta que, durante este proceso incremental, tu aplicación en su conjunto dejará de ser completamente funcional, ya que OpenTok y Vonage Video API son dos sistemas completamente diferentes.

El plan concreto para un enfoque gradual dependerá del número y del tipo de funciones de la Video API que utilices, así como de cómo hayas integrado dichas funciones en tu aplicación. Aunque no es posible ofrecer orientaciones específicas sobre la implementación en este ámbito, en términos de enfoque general, un posible plan consiste en actualizar el código función por función y, dentro de cada función, método por método.

Un buen punto de partida sería cualquier código que instancie un archivo OpenTok::OpenTok objeto y sustitúyelo por código que instancie un Vonage::Client objeto, tras la comparación entre ambos que se muestra en el Estructura del paquete sección.

El siguiente paso podría ser actualizar cualquier código que se ocupe de crear sesiones, generar tokens de cliente y pasar datos a las bibliotecas de cliente front-end.

A continuación, podría pasar a actualizar a su vez cualquier código que implemente características específicas de la Video API. Para usar Archivos como ejemplo:

• Identifica cualquier código en el que Archives se crean o con los que se interactúa.
• Actualizar las invocaciones de métodos para que los métodos se invoquen en client.video en lugar de opentok objetos.
• Actualizar los nombres de los métodos que han cambiado.
• Si una llamada a un método pasa algún argumento, actualícela para utilizar los parámetros de palabra clave correctos.
• Identifica cualquier código en el que se llame directamente a un método en un Archive objeto de respuesta y modifícalo tal y como se indica en el Objetos de respuesta sección.

Repita este proceso para cada característica y método.

Es posible que tengas que seguir algunos pasos adicionales, como actualizar cualquier código en el que rescatar errores específicos. La lista de pasos anterior no es exhaustiva, pero esperamos que sirva de buen punto de partida para definir su plan de migración.

Patrón de pasarela/adaptador

Si aún no estás utilizando algún tipo de patrón de pasarela o adaptador como parte de tu implementación, esta migración sería una buena oportunidad para hacerlo. Esto no solo facilitaría la migración, sino que también significaría que, en el uso habitual, el código de tu aplicación estaría menos acoplado al código del SDK.

Existen muchos enfoques diferentes para implementar estos patrones, dependiendo de cómo esté estructurada tu aplicación y/o del marco de trabajo que utilices. Queda fuera del alcance de este documento ofrecer orientación específica al respecto.

Recomendaciones para las pruebas

Para que la transición sea fluida, tanto durante como después de la migración, es esencial realizar pruebas exhaustivas. Esto incluye no sólo las pruebas unitarias, sino también las de integración y regresión. También merece la pena probar manualmente el flujo de la aplicación al menos una vez antes y después de la migración para asegurarse de que las pruebas automatizadas hacen lo que usted cree que hacen, o para detectar cualquier problema que las pruebas no hayan detectado. Incluso puede plantearse crear pruebas de equivalencia. La idea es crear un conjunto que afirme que las versiones de OpenTok y Vonage Video de tu aplicación hacen lo mismo. Estas pruebas pueden descartarse una vez finalizada la transición y eliminada la versión de OpenTok de tu aplicación.

Resolución de problemas y asistencia técnica

Canales de asistencia

Para obtener ayuda general y debatir sobre la transición a Vonage Video, consulta la sección Canal #Video API en nuestro Slack de la comunidad, donde podrás obtener respuestas del personal de Vonage y de otros usuarios. También puedes ponerte en contacto con nosotros a través de X @VonageDev.

El contacto principal para cualquier problema con la propia Video API es support@api.vonage.com.

Si encuentra un error en el SDK, por favor abrir un ticket en GitHub, indicando los pasos para reproducir el error.

Recursos adicionales

Muestras de código

• Videollamada multipartita básica con Sinatra