Guía de transición de video de Vonage 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.

Alcance

Este documento presupone que está utilizando al menos la versión 4.9.0 o posterior de la aplicación SDK Ruby de OpenTok. 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 actual último de Vonage Ruby SDK, que se puede encontrar en GitHub o RubyGems.

Supuestos

Esta guía está pensada para ser seguida por un ingeniero de software profesional. Se asume al menos un nivel básico de competencia con Ruby, herramientas comunes para desarrolladores Ruby y Git (u otro sistema de control de versiones). Deberías sentirte cómodo leyendo y escribiendo código Ruby, gestionando las dependencias del proyecto, desplegando y ejecutando un proyecto Ruby. Una introducción al lenguaje Ruby, la plataforma y las herramientas asociadas va mucho más allá 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
• SDK de servidor Ruby de Vonage Rubydocs
• Código fuente de vídeo del SDK de servidor Ruby de Vonage
• Depósito de GitHub del SDK de servidor Ruby de Vonage
• Artefactos publicados del SDK del servidor Ruby de Vonage en RubyGems

TokBox

• Referencia REST de la API de OpenTok
• Documentación del SDK del servidor Ruby de OpenTok
• Código fuente del SDK del servidor Ruby de OpenTok
• 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 su aplicación, hay algunas cuestiones que deberá 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 que contiene un archivo 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)?

También puede haber otras consideraciones para su proyecto específico que no se hayan enumerado 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). sobre). Es crucial contar con un buen conjunto de pruebas para poder verificar la equivalencia entre las implementaciones de OpenTok y Vonage Video. El tiempo que tomará 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.

Principales cambios y consideraciones

La Video API de Vonage tiene paridad de funciones con OpenTok, y el SDK de Ruby se mantiene activamente en línea con la especificación de la API. Sin embargo, existen algunas diferencias entre los dos SDK que debes conocer.

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 una gema Ruby recomendado por Bundlerpor lo que, a grandes rasgos, tienen una estructura similar. Sin embargo, hay un par de diferencias clave:

1. El SDK Ruby de Vonage 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 cuyo nombre esté bajo 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:

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

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

Ejemplo 2: Obtener una lista de grabaciones de archivo

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

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

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

Nota sobre mecanografía

El SDK Ruby de Vonage 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.

Cambios en el front-end

Las librerías front-end utilizadas para 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 cliente del front-end accedan a esas sesiones. Al igual que con una implementación de OpenTok, las bibliotecas cliente del front-end esperarán que el servidor 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 aplicación. 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 su implementación, por ejemplo en sus plantillas de vista o en la lógica que pasa datos a esas plantillas de vista.

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 Ruby. Puede hacerlo actualizando su Gemfile para incluir el vonage joya:

y luego ejecutar bundle install.

Cambios en la autenticación

Considerando que la opentok utiliza una gema api_key y api_secret para Autorización, la implementación de la Video API en el vonage utiliza un JWT. El SDK se encarga de la generación de JWT en segundo plano para usted, pero requerirá 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.

Existen varias maneras de crear una aplicación de Vonage:

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

Su application_id y private_key se introducen al crear una instancia de Client (en el ejemplo siguiente se supone que se han establecido como variables de entorno):

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:

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 utiliza dotenv para gestionar sus variables de entorno, su VONAGE_PRIVATE_KEY definición en su .env tendría el siguiente aspecto:

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 de nombre de los métodos

Algunos métodos se han renombrado y/o desplazado, para mayor claridad y/o para reflejar mejor lo que hace el método. Se enumeran a continuación:

Objetos de respuesta

A diferencia del SDK Ruby de OpenTok, el SDK Ruby de Vonage no utiliza clases de objetos específicas al deserializar la carga útil JSON de una respuesta HTTP, sino que deserializa las respuestas a 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::Streamen el sentido de que se puede acceder a las propiedades desde la carga útil de la respuesta llamando a métodos del objeto con nombres equivalentes al nombre de la propiedad. Por ejemplo, si desea iniciar una nueva grabación de archivo y obtener su ID de la respuesta, el enfoque para hacer esto sería muy similar para los dos SDK.

Ejemplo: SDK Ruby de OpenTok

Ejemplo: SDK Ruby de Vonage

Una diferencia clave en la implementación de los objetos de respuesta entre los dos SDK está en el uso del patrón de fachada dentro de los objetos de respuesta del SDK 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 lleva 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 puedes llamar a la función stop directamente en el Archive devuelto por el objeto Archives#create invocación del método.

Ejemplo: SDK Ruby de Vonage

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

Objetos de respuesta multirecurso

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 con el nombre del producto y, a continuación, el tipo de objeto que realizó la solicitud, por ejemplo Vonage::Video::Broadcasts::ListResponse.

Básicamente, proporcionan la misma funcionalidad que los tipos de objetos de respuesta de lista del SDK de Ruby de OpenTok, en el sentido de que son colecciones iterables de objetos de recursos individuales. La implementación difiere ligeramente entre los SDK, pero en general esto no debería afectar a la forma en que se puede interactuar con estos objetos, y se describe a continuación más para completar:

• En ListResponse en el SDK Ruby de Vonage implementan un each e incluir el método Enumerable módulo.
• Las respuestas de tipo lista en el SDK Ruby de OpenTok (p. ej. ArchiveList, BroadcastListetc) de la subclase de Ruby Array clase.

Objetos de respuesta a errores

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

El SDK Ruby de OpenTok define un módulo OpenTok::OpenTokError y luego clases de error específicas por tipo de característica que subclase de OpenTokErrorcomo OpenTokArchiveError, OpenTokBroadcastError, OpenTokAuthenticationErroretc. Ninguno de estos tipos de error implementa ninguna funcionalidad adicional más allá de lo que StandardError proporciona.

El SDK Ruby de Vonage define un módulo genérico Vonage::Error y también una clase Vonage::APIError que subclase de Vonage::Error. En APIError representa los errores que resultan de una solicitud HTTP a un punto final de la API de Vonage. A continuación, el SDK define una serie de clases de error más específicas, según la naturaleza de la respuesta recibida, que subclase de APIError. Estas clases incluyen Vonage::ClientError (para 4xx respuestas), Vonage::ServerError (para 5xx respuestas), y Vonage::AuthenticationError (que subclase de Vonage::ClientErrory se utiliza específicamente para 401 respuestas).

En 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

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 exacto para un enfoque incremental dependerá de cuántas y cuáles funciones de la Video API esté utilizando y de cómo haya integrado esas funciones en su aplicación. Aunque no es posible proporcionar una guía específica de implementación en esta área, en términos de enfoque general un posible plan es actualizar su código característica por característica, y dentro de cada característica método por método.

Un buen punto de partida sería cualquier código que instancie un archivo OpenTok::OpenTok y sustituirlo por código que instancie un objeto Vonage::Client objeto, tras la comparación entre ambos demostrada 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:

• Identifique cualquier código en el que Archives se crean o se interactúa con ellas.
• 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.
• Identifique cualquier código en el que se llame a un método directamente en un Archive y modifíquelo como se indica en la sección Objetos de respuesta sección.

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

Es posible que tenga que tomar medidas adicionales, como actualizar el código en los casos en los que rescatar errores específicos. La lista de pasos anterior no es exhaustiva, pero esperamos que constituya un buen punto de partida para definir su plan de migración.

Modelo de puerta de enlace/adaptador

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

Hay muchos enfoques diferentes para implementar estos patrones dependiendo de cómo esté estructurada tu aplicación y/o el framework que estés utilizando. Está fuera del alcance de este documento proporcionar cualquier orientación específica en esta área.

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.

Solución de problemas y asistencia

Canales de apoyo

Para obtener ayuda general y debatir sobre la transición a Vonage Video, consulta la sección Canal #video-api en nuestra comunidad Slackdonde podrás obtener respuestas del personal de Vonage y de otros usuarios. También puedes ponerte en contacto con nosotros en 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 presente una incidencia, con los pasos para reproducirla, en GitHub.

Recursos adicionales

Muestras de código

• Videollamada multipartita básica con Sinatra