Guide de transition vidéo de Vonage pour Python

Transition de Opentok-Python-SDK à vonage-python-sdk

Introduction

Objectif

L'objectif de ce document est de fournir un point de départ pour passer du SDK OpenTok Python Server au SDK Vonage Python Server. Il existe un guide de migration plus spécifique et détaillé est disponible sur ce lien.

Champ d'application

Ce document suppose que vous utilisez au moins la version version 3.9.0 ou plus tard le OpenTok Python SDK.

L'API Video est entièrement prise en charge dans le SDK Python de Vonage. Vous devez utiliser la dernière version complète du SDK, qui peut être trouvée sur le site suivant GitHub ou PyPI.

Hypothèses

Ce guide est destiné à être suivi par un ingénieur logiciel professionnel. Il suppose au moins un niveau de compétence de base avec Python, les outils de développement Python courants, les systèmes de construction et Git (ou un autre système de contrôle de version).

Vous devez être à l'aise pour lire et écrire du code Python, gérer les dépendances du projet et déployer et exécuter un projet Python. Il est recommandé d'utiliser un environnement Python virtuel.

Une introduction au langage Python et aux outils associés dépasse largement le cadre de ce document.

Ressources

Les liens suivants sont utiles pour compléter le présent document et pour se référer à tout ce qui n'est pas couvert dans le présent document :

Vonage

TokBox

Planifier votre migration

Avant de passer d'OpenTok à Vonage Video, vous devez prendre en compte l'ampleur de la tâche afin de fixer des attentes réalistes.

Évaluer l'impact

La première question à se poser est la suivante : quelle est la part du code de votre application qui dépend du SDK OpenTok ?

Dressez une liste de tous les fichiers dans lesquels le SDK est directement utilisé. En d'autres termes, tous les fichiers .py qui contient un fichier import opentok ou from opentok import... déclaration. Vous pouvez rechercher les fichiers de votre projet à l'aide d'un IDE ou d'un outil de ligne de commande pour identifier les fichiers concernés.

Chronologie

Tenez compte du temps nécessaire pour mener à bien la transition. Cela dépendra de votre expérience du projet et de son impact, ainsi que des tests. Il est essentiel de disposer d'une bonne suite de tests afin de pouvoir vérifier l'équivalence entre les SDK OpenTok et Vonage Video. Le temps nécessaire pour effectuer la transition est à peu près proportionnel au nombre d'endroits où le SDK OpenTok est utilisé dans votre code, ainsi qu'à la variété des fonctionnalités utilisées. Certains appels API seront plus simples à remplacer que d'autres.

Versionnement

OpenTok et Vonage Video sont deux produits différents, ce qui rend impossible une migration progressive.

Vous devriez créer une nouvelle branche dans votre système de contrôle de version pour la transition, afin de pouvoir apporter des modifications progressivement et fréquemment sans casser le projet existant. Vous pouvez également utiliser les tests du projet existant en tant qu'oracle de correction, s'ils sont complets. Idéalement, vous ne devriez fusionner la branche de transition avec la branche principale qu'une fois la conversion terminée.

Principaux changements et considérations

Mise à jour du paquet

Tout d'abord, vous devez installer ou mettre à jour le SDK Python de Vonage dans votre projet. Vous pouvez le faire en exécutant pip install -U vonage.

Pour une migration progressive, vous pouvez inclure les dépendances d'OpenTok et de Vonage dans votre projet, mais nous vous recommandons fortement de ne le faire que pour des tests et non pour des déploiements en production.

Modifications de l'authentification

L'authentification dans les SDK OpenTok et Vonage Python Server est gérée pour vous, de sorte que vous ne devez fournir les informations d'identification de votre compte qu'une seule fois lors de l'initialisation. La différence est qu'OpenTok requiert une clé API et un secret, tandis que pour le SDK Python de Vonage, vous devez fournir un identifiant d'application et sa clé privée. Vonage et OpenTok utilisent tous deux une authentification par jeton, mais les jetons de Vonage sont les suivants JWTs tandis qu'OpenTok utilise un format personnalisé. Bien que vous puissiez fournir une clé API et un secret à la fonction vonage.Client Tout comme pour OpenTok, cet objet est utilisé pour d'autres API de Vonage, et non pour Video. Par conséquent, vous devrez créer ou utiliser une application Vonage existante.

Vous pouvez créer une application à partir de l'application Tableau de bord Vonage. Assurez-vous que la fonction vidéo est activée dans votre application. Cliquez sur "Modifier" pour une application existante afin d'afficher ses capacités et ses informations d'identification. Cliquez ensuite sur "Générer une clé publique et privée". Cette opération ne doit être effectuée qu'une seule fois, car à chaque fois que vous effectuez cette opération, les informations d'identification changent et la paire de clés existante est rompue. En cliquant sur ce bouton, vous déclencherez le téléchargement de votre clé privée. Vous devez placer ce fichier dans un endroit sûr pour le tester. NE JAMAIS PARTAGER OU EXPOSER SA CLÉ PRIVÉE !

La clé privée est en fait le "mot de passe" de votre application et doit donc être traitée avec soin. Il est recommandé de stocker votre clé privée dans un fichier sécurisé. Utilisez un paquetage tel que dotenv pour créer un .env puis stockez le chemin d'accès à votre fichier de clé privée dans une variable d'environnement afin de pouvoir vous y référer lors de la configuration du client, en appelant la variable de la manière suivante VONAGE_PRIVATE_KEY_PATH. Il convient de faire de même pour l'identifiant de votre application (qui se trouve sur le tableau de bord ou dans l'URL lors de son édition).

Pour plus d'informations sur la création d'une application, voir le guide de démarrage.

Utilisation des modèles pydantiques

Le SDK Python de Vonage utilise Modèles de données pydantiques pour prendre en compte les options de l'utilisateur et renvoyer les données de l'API. La plupart des demandes d'API avec l'API Video nécessitent un modèle Pydantic en entrée.

Vous pouvez accéder aux modèles de données de l'API Video, par exemple en tant qu'arguments pour les méthodes du paquet Video, en les important à partir du fichier vonage_video.models par exemple.

from vonage_video.models import SessionOptions

session_options = SessionOptions(...)

vonage_client.video.create_session(session_options)

Utilisation

Instauration d'un client

Voir le README du SDK Python pour obtenir des instructions sur l'utilisation de ce SDK.

Remplacer les références aux opentok.Client et opentok.OpenTok avec le Video accessible par l'intermédiaire de la classe vonage.Vonage.video.

Au lieu de cela, avec OpenTok :

client = opentok.Client(api_key, api_secret)

Procédez comme suit :

from vonage import Auth, Vonage

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

Une fois que vous avez accès à un vonage.Vonage vous pouvez utiliser la fonction Video API. Pour appeler des méthodes liées à l'API Video, utilisez cette syntaxe :

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

Pour des instructions d'utilisation plus détaillées, voir le Guide vidéo du SDK serveur Python.

Changements de méthode entre les SDK OpenTok et Vonage

Certaines méthodes ont été modifiées entre le OpenTok et la mise en œuvre de l'API Video dans le Vonage SDK.

  • Tous les paramètres positionnés dans les signatures de méthodes en opentok ont été remplacés par des paramètres de type clé-valeur dans la rubrique vonage l'emballage.
  • Les méthodes renvoient désormais la réponse sous la forme d'un dictionnaire Python.
  • Certaines méthodes ont été renommées, par souci de clarté et/ou pour mieux refléter ce qu'elles font. Elles sont énumérées ci-dessous :
Nom de la méthode OpenTok Nom de la méthode vidéo 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

Stratégies de migration

Migration incrémentale

Nous recommandons une migration incrémentale, en passant d'un cas d'utilisation à un autre, en s'engageant à chaque fois que vous arrivez à un état "stable". Notez que cette approche nécessiterait la coexistence temporaire d'OpenTok et de Vonage Video API.

Veuillez noter que, pendant ce processus incrémentiel, votre application dans son ensemble ne sera plus entièrement fonctionnelle, car OpenTok et Vonage Video API sont deux systèmes totalement différents.

Vous devriez commencer par créer un "adaptateur vidéo" spécifique qui regrouperait toutes les interactions actuelles avec OpenTok. regrouper toutes les interactions actuelles avec OpenTok, puis remplacer une à une l'utilisation d'OpenTok par l'API Video de Vonage.

Une autre approche pourrait consister à dupliquer cet "adaptateur vidéo" dans un nouvel "adaptateur vidéo Vonage", dédié à cette migration, avant d'intervertir ces deux adaptateurs. Pour en savoir plus, consultez le site Modèle de figue étrangleuse.

Recommandations pour les tests

Des tests approfondis sont essentiels pour assurer une transition en douceur, tant pendant qu'après la migration. Il s'agit non seulement de tests unitaires, mais aussi de tests d'intégration et de régression. Il est également utile de tester manuellement le flux de votre application au moins une fois avant et après la migration pour s'assurer que vos tests automatisés font ce que vous pensez qu'ils font, ou pour détecter tout problème que les tests n'auraient pas décelé. Vous pouvez même envisager de créer des tests d'équivalence.

L'idée est de créer une suite qui affirme que les versions OpenTok et Vonage Video de votre application font la même chose. Ces applications peuvent ensuite être éliminées une fois que la transition est terminée et que la version OpenTok de votre application est supprimée.

Dépannage et assistance

Le SDK du serveur Python de Vonage s'efforce de fournir des messages d'exception utiles dans les traces de pile si vous rencontrez des erreurs d'exécution. Examinez-les attentivement pour en déterminer la cause.

Canaux de soutien

Pour obtenir de l'aide générale et discuter de la transition vers Vonage Video, consultez les sites suivants le Canal #video-api sur notre communauté Slackoù vous pourrez obtenir des réponses du personnel de Vonage et d'autres utilisateurs. Vous pouvez également nous contacter sur X @VonageDev.

La personne à contacter en cas de problème avec l'API Video est la suivante support@api.vonage.com. Si vous trouvez un bogue avec le SDK, veuillez déposer un problème avec les étapes à suivre pour le reproduire sur GitHub.