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

Transición de `Opentok-Python-SDK` a `vonage-python-sdk`

Introducción

Propósito

El objetivo de este documento es ofrecer un punto de partida para la transición del SDK de servidor de OpenTok para Python al SDK de servidor de Vonage para Python. Hay una guía de migración más específica y detallada disponible en este enlace.

Ámbito de aplicación

En este documento se da por hecho que estás utilizando, como mínimo, la versión 3.9.0 o más tarde de la dirección SDK de OpenTok para Python.

La Video API es totalmente compatible con el SDK Python de Vonage. Debes usar la última versión completa del SDK, que se encuentra en GitHub o PyPI.

Supuestos

Esta guía está pensada para ser seguida por un ingeniero de software profesional. Se presupone al menos un nivel básico de competencia con Python, herramientas de desarrollo comunes de Python, sistemas de compilación y Git (u otro sistema de control de versiones).

Debes sentirte cómodo leyendo y escribiendo código Python, gestionando las dependencias del proyecto y desplegando y ejecutando un proyecto Python. Se recomienda utilizar un entorno virtual de Python.

Una introducción al lenguaje Python y a 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

TokBox

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

La primera pregunta que hay que plantearse es: ¿en qué medida depende el código de tu aplicación del SDK de OpenTok?

Haga una lista de todos los archivos en los que se utiliza directamente el SDK. Es decir, cualquier .py que contiene un archivo import opentok o from opentok import... declaración. Puede buscar en los archivos de su proyecto utilizando un IDE o una herramienta de línea de comandos para identificar los archivos afectados.

Cronología

Account the time required to complete the transition. Esto dependerá de tu experiencia con el proyecto y su impacto, así como de las pruebas. Es crucial contar con un buen conjunto de pruebas para poder verificar la equivalencia entre los SDK de OpenTok y Vonage Video. El tiempo que tomará completar la transición es aproximadamente proporcional a la cantidad de lugares donde se utiliza el SDK de OpenTok en tu código, así como a la variedad de funciones utilizadas. Algunas llamadas API serán más simples de reemplazar que otras.

Versionado

OpenTok y Vonage Video son dos productos distintos, lo que hace imposible una migración progresiva.

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

Cambios y consideraciones clave

Actualización del paquete

En primer lugar, necesitarás instalar o actualizar el SDK Python de Vonage en tu proyecto. Puedes hacerlo ejecutando pip install -U vonage.

Para una migración gradual, puedes incluir en tu proyecto tanto las dependencias de OpenTok como las de Vonage; sin embargo, te recomendamos encarecidamente que esto se haga únicamente con fines de prueba y no para implementaciones en producción.

Cambios en la autenticación

La autenticación tanto en OpenTok como en Vonage Python Server SDK se maneja por ti, por lo que solo tienes que proporcionar las credenciales de tu Account una vez durante la inicialización. La diferencia es que OpenTok requiere una clave de API y un secreto, mientras que para el SDK Python de Vonage, debes proporcionar un ID de aplicación y su clave privada. Si bien tanto Vonage como OpenTok utilizan autenticación basada en tokens, los tokens de Vonage son JWT mientras que OpenTok utiliza un formato personalizado. Aunque puede proporcionar una clave de API y un secreto a la aplicación vonage.Client al igual que con OpenTok, se utiliza para otras API de Vonage, no para Video. Por lo tanto, deberás crear o utilizar una aplicación de Vonage existente.

Puedes crear una aplicación desde el Panel de Vonage. Asegúrese de que su aplicación tiene activada la función de vídeo. Haga clic en "Editar" en una aplicación existente para ver sus capacidades y credenciales. Desde aquí, haz clic en "Generar clave pública y privada". Esto sólo debe hacerse una vez, ya que cada vez que lo hagas, las credenciales cambiarán y se romperá el par de claves existente. Al hacer clic, se descargará tu clave privada. Coloca este archivo en un lugar seguro para realizar pruebas. NO COMPARTA NI EXPONGA NUNCA SU CLAVE PRIVADA.

La clave privada es en realidad la "contraseña" de su aplicación, por lo que debe ser tratada con cuidado. Se recomienda guardar la clave privada en un archivo seguro. Utilice un paquete como dotenv para crear un .env guarde la ruta a su archivo de clave privada como una variable de entorno para que pueda hacer referencia a ella cuando configure el cliente, llamando a la variable algo como VONAGE_PRIVATE_KEY_PATH. Haz lo mismo con el ID de tu aplicación (que puedes encontrar en el panel de control o en la URL al editarla).

Para obtener más información sobre cómo configurar una aplicación, consulte la guía de introducción.

Utilización de modelos pydánticos

El SDK Python de Vonage utiliza Modelos de datos pydánticos para aceptar las opciones del usuario y devolver datos de la Video API. La mayoría de las solicitudes a la Video API requieren un modelo Pydantic como entrada.

Puedes acceder a los modelos de datos de la Video API —por ejemplo, como argumentos para los métodos del paquete «Video»— importándolos desde el vonage_video.models por ejemplo

from vonage_video.models import SessionOptions

session_options = SessionOptions(...)

vonage_client.video.create_session(session_options)

Uso

Instanciar un cliente

Véase el LÉEME del SDK de Python para obtener instrucciones sobre cómo utilizar este SDK.

Sustituir las referencias a opentok.Client y opentok.OpenTok con el Video a la que se accede mediante vonage.Vonage.video.

En lugar de esto, con OpenTok:

client = opentok.Client(api_key, api_secret)

Haz lo siguiente:

from vonage import Auth, Vonage

client = Vonage(Auth(
		application_id='VONAGE_APPLICATION_ID',
		private_key='VONAGE_PRIVATE_KEY_PATH',
	)
)

Una vez que tengas acceso a un vonage.Vonage Por ejemplo, puedes utilizar el Video API. Para llamar a métodos relacionados con la Video API, utiliza esta sintaxis:

vonage.Vonage.video.video_api_method(...)

Para obtener instrucciones de uso más detalladas, consulte el sitio Guía en vídeo del SDK del servidor Python.

Cambios de método entre los SDK de OpenTok y Vonage

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

Cualquier parámetro posicional en las firmas de métodos en opentok se han sustituido por parámetros de clave-valor en la función vonage paquete.
Ahora los métodos devuelven la respuesta en forma de diccionario de Python.
Se han cambiado los nombres de algunos métodos, en aras de la claridad y/o para reflejar mejor su función. A continuación se enumeran dichos métodos:

Nombre del método OpenTok	Nombre del método de vídeo de Vonage
`opentok.generate_token`	`video.generate_client_token`
`opentok.add_archive_stream`	`video.add_stream_to_archive`
`opentok.remove_archive_stream`	`video.remove_stream_from_archive`
`opentok.set_archive_layout`	`video.change_archive_layout`
`opentok.add_broadcast_stream`	`video.add_stream_to_broadcast`
`opentok.remove_broadcast_stream`	`video.remove_stream_from_broadcast`
`opentok.set_broadcast_layout`	`video.change_broadcast_layout`
`opentok.set_stream_class_lists`	`video.change_stream_layout`
`opentok.force_disconnect`	`video.disconnect_client`
`opentok.mute_all`	`video.mute_all_streams`
`opentok.disable_force_mute`	`video.disable_mute_all_streams`
`opentok.dial`	`video.initiate_sip_call`
`opentok.start_render`	`video.start_experience_composer`
`opentok.list_renders`	`video.list_experience_composers`
`opentok.get_render`	`video.get_experience_composer`
`opentok.stop_render`	`video.stop_experience_composer`
`opentok.connect_audio_to_websocket`	`video.start_audio_connector`

Estrategias de migración

Migración incremental

Recomendamos realizar una migración gradual, pasando de un caso de uso a otro y confirmando los cambios cada vez que se alcance un estado «estable». Ten en cuenta que este enfoque requeriría que OpenTok y la Video API de Vonage 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.

Deberías empezar por crear un «adaptador de vídeo» específico que agrupe todas las interacciones actuales con OpenTok y, a continuación, sustituir una a una las llamadas a OpenTok por la Video API de Vonage.

Otro enfoque podría ser duplicar ese "Adaptador de video" en un nuevo "Adaptador de video de Vonage", dedicado a esa migración, antes de intercambiar esos dos adaptadores. Ver más con el Patrón de la higuera estranguladora.

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 de pruebas que confirme que tanto la versión de tu aplicación basada en OpenTok como la basada en Vonage Video realizan las mismas funciones. Estas pruebas podrán descartarse una vez que se haya completado la transición y se haya eliminado la versión de tu aplicación basada en OpenTok.

Resolución de problemas y asistencia técnica

El SDK para servidores de Python de Vonage tiene como objetivo proporcionar mensajes de excepción útiles en los rastros de pila en caso de que se produzcan errores en tiempo de ejecución. Examina estos mensajes detenidamente para determinar la causa.

Canales de asistencia

Si necesitas ayuda general o quieres participar en debates sobre la transición a Vonage Video, echa un vistazo a el Canal #Video API en nuestro Slack de la comunidaddonde 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 detectas un error en el SDK, por favor, Presentar un problema con los pasos para reproducir en GitHub.