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

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

Introducción

Propósito

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

Alcance

Este documento presupone que está utilizando al menos la versión 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 debes hacerte es: ¿qué parte del código de tu aplicación depende 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 diferentes - Esto 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.

Principales cambios y consideraciones

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 dependencias tanto de OpenTok como de Vonage en tu proyecto, sin embargo, recomendamos encarecidamente que esto sea sólo para pruebas 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 JWTs 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.

Puede crear una aplicación desde la sección 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. Lo mismo debe hacerse con el ID de su aplicación (que puede encontrarse en el panel de control o en la URL al editarla).

Para más información sobre la creación de 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 recibir las opciones del usuario y devolver los datos de la API. La mayoría de las solicitudes de API con la Video API requieren un modelo Pydantic como entrada.

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

from vonage_video.models import SessionOptions

session_options = SessionOptions(...)

vonage_client.video.create_session(session_options)

Utilización

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 tenga acceso a un vonage.Vonage puede utilizar la función Video API. Para llamar a métodos relacionados con la Video API, utilice 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.
  • Los métodos ahora devuelven la respuesta como un diccionario Python.
  • Se ha cambiado el nombre de algunos métodos, para mayor claridad y/o para reflejar mejor lo que hace el método. Se enumeran a continuación:
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

Recomendaríamos una migración incremental, pasando de un caso de uso a otro, comprometiéndote cada vez que llegues a un estado "estable". Ten en cuenta que este enfoque requeriría la coexistencia temporal de OpenTok y Vonage Video API.

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 comenzar por crear un "Adaptador de video" específico que reagrupe todas las interacciones actuales con OpenTok, y luego reemplace una por una el uso de OpenTok con 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 higo estrangulador.

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 pueden descartarse una vez que la transición se haya completado y se haya eliminado la versión OpenTok de tu aplicación.

Solución de problemas y asistencia

El SDK del servidor Python de Vonage se esfuerza por proporcionar mensajes de excepción útiles en los rastros de pila en caso de que encuentres errores de ejecución. Examínalos cuidadosamente para determinar la causa.

Canales de apoyo

Para obtener ayuda general y debatir sobre la transición a Vonage Video, consulta el sitio 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 Presentar un problema con los pasos para reproducir en GitHub.