La version 4 du SDK Python de Vonage est maintenant disponible !

Après une réécriture complète, la version 4 du SDK Python de Vonage est maintenant disponible. Il s'agit d'une refonte complète du SDK précédent qui offre des améliorations à tous les utilisateurs.

Dans ce billet, nous passerons en revue les principales caractéristiques et nous vous montrerons comment commencer à utiliser le nouveau SDK Python de Vonage pour appeler les API de Vonage.

Migrer de la v3

Si vous utilisez actuellement le SDK v3 et que vous souhaitez le mettre à jour, ce guide sur la migration de la v3 à la v4 vous sera utile.

Caractéristiques principales

Une réécriture complète nous a permis d'apporter des améliorations structurelles essentielles et de décider de la manière dont l'utilisateur devrait interagir avec le SDK.

Voici une liste des changements les plus importants :

1. Une nouvelle structure monorepo

2. Modèles de données pydantiques dans les demandes et les réponses

3. Amélioration de la documentation en ligne

4. Amélioration de la gestion des erreurs et plus d'informations

5. Prise en charge complète de l'API Video de Vonage

Une nouvelle structure monorepo

La v4 du SDK Python de Vonage utilise maintenant une structure monorepo, avec différents paquets pour appeler les différentes API de Vonage, tout en utilisant un code commun. L'installation du paquetage de premier niveau vonage de niveau supérieur permet d'obtenir tous les paquets dont vous avez besoin, de sorte qu'il n'est pas nécessaire d'installer quoi que ce soit d'autre directement. Cela nous donne plus de flexibilité dans ce qui est publié, et quand, de sorte que nous pouvons prendre en charge de nouvelles API plus tôt et plus clairement versionner les différents paquets.

Modèles de données pydantiques dans les demandes et les réponses

Le SDK v4 fait un usage intensif des modèles de données pydantiques pour faciliter l'appel aux API de Vonage et l'analyse des résultats.

L'utilisation de modèles pydantiques pour formuler des requêtes permet d'appliquer un typage correct et facilite la transmission des bons objets à Vonage. Les réponses sont maintenant désérialisées en modèles Pydantique entièrement documentés, ce qui donne plus de cohérence que de retourner des dictionnaires comme nous le faisions dans la v3. Vous pouvez toujours transformer les modèles Pydantique en dictionnaires ou en chaînes JSON avec les commandes model.model_dump et model.model_dump_json respectivement.

Amélioration de la documentation en ligne

Des docstrings ont été ajoutés aux méthodes et aux modèles de données dans l'ensemble du SDK afin d'améliorer l'expérience du développeur et de faciliter le développement dans l'IDE. En passant la souris sur un nouvel objet/méthode dans votre IDE, vous obtiendrez des informations sur ce qu'il fait et sur la manière de l'appeler.

The help you now get in your IDE when using the new SDK

Amélioration de la gestion des erreurs et plus d'informations

Dans la v3, la plupart des erreurs du client HTTP soulevaient une HttpClientError générale. Dans la version 4, les erreurs sont désormais plus fines et les messages d'erreur donnent plus d'informations et de contexte.

Par exemple, un nouveau HttpRequestError a été créé, avec des sous-types distincts tels que AuthenticationError, ForbiddenError, NotFoundError etc. Vous pouvez accéder à la réponse HTTP en attrapant une erreur HTTP et en utilisant son attribut self.response et en utilisant son attribut

from vonage_http_client import HttpRequestError

try:
    response = client.application.create_application(params)

except HttpRequestError as e:
    print(e.message)  # Prints error message
    print(e.response.text)  # Prints the HTTP response text

Certains paquets d'API ont également leurs propres erreurs pour des cas spécifiques.

Pour les anciennes API de Vonage qui renvoient toujours un HTTP 200, une logique de gestion des erreurs a été incluse afin d'offrir une expérience similaire à celle des API plus récentes.

Vous pouvez désormais accéder à n'importe quelle réponse HTTP avec vonage.Vonage.http_client.last_response et à la requête HTTP correspondante avec vonage.Vonage.http_client.last_requestmême en l'absence d'erreur, afin de mieux comprendre ce qui se passe.

Prise en charge complète de l'API Video de Vonage

Le support a été ajouté pour tous les Video API de Vonage de Vonage. En plus des fonctionnalités ajoutées à la v3, de nouvelles méthodes ont été ajoutées pour vous aider à travailler avec les API Live Captions, Audio Connector et Experience Composer.

Cela permet au SDK d'atteindre la parité avec le paquet OpenTok. Si vous utilisez OpenTok, il est fortement recommandé de migrer vers la version 4 du SDK Python de Vonage plutôt que vers le paquetage Python. opentok Il est fortement recommandé d'utiliser la version 4 du SDK Python de Vonage plutôt que le paquetage Python de Vonage. Voir le guide de migration OpenTok -> Vonage Video pour obtenir de l'aide à ce sujet.

Installation

Le nouveau SDK doit être installé dans un nouvel environnement virtuel. Ouvrez une console, créez un nouvel environnement et installez le nouveau SDK avec pip en utilisant les commandes suivantes :

# Create the virtual environment
python3 -m venv venv

# Activate the virtual environment in Mac/Linux
. ./venv/bin/activate

# Or on Windows Command Prompt
venv\Scripts\activate

# Install the package
pip install vonage

Vous remarquerez que d'autres paquets dépendants de Vonage, tels que vonage-http-client ont également été installés.

Si vous possédez déjà une version antérieure du SDK, utilisez l'option --upgrade pour obtenir la dernière version :

pip install vonage --upgrade

Pour commencer

Pour commencer à utiliser le SDK v4, vous devez initialiser une instance de la classe vonage.Vonage qui peut être utilisée pour accéder aux méthodes de l'API. Vous devrez ensuite fournir des informations d'authentification. Avant de passer à l'étape suivante, voici un exemple complet qui vous montre comment créer une nouvelle application Vonage avec le SDK v4 :

from vonage import Vonage, Auth
from vonage_application import ApplicationConfig

vonage_client = Vonage(auth=Auth(api_key='your_api_key', api_secret='your_api_secret'))

application_data = vonage_client.application.create_application(
    ApplicationConfig(name='My Basic Application')
)

print(application_data)

Voyons maintenant ce qu'il en est.

Authentification

Selon l'API de Vonage que vous souhaitez utiliser, vous utiliserez différentes formes d'authentification. Vous devrez fournir soit une clé API et un secret, soit l'ID d'une Applications Vonage et sa clé privée correspondante. Pour ce faire, vous devez initialiser une instance de vonage.Auth.

from vonage import Auth

# API key/secret authentication
auth = Auth(
    api_key='your_api_key', api_secret='your_api_secret'
)

# Application ID/private key authentication
auth = Auth(
    application_id='your_vonage_application_id', private_key='your_application_private_key'
)

Il peut alors être utilisé lors de l'initialisation d'une instance de auth peut alors être utilisé lors de l'initialisation d'une instance de vonage.Vonage. Pour configurer une instance de la classe vonage.Vonage pour appeler les API de Vonage, procédez comme suit :

from vonage import Vonage, Auth

# Create an Auth instance
auth = Auth(
    api_key='your_api_key', api_secret='your_api_secret'
)

# Create a Vonage client instance
vonage_client = Vonage(auth=auth)

Accès aux méthodes de l'API

Pour accéder aux méthodes relatives aux API de Vonage, vous créerez une instance de la classe vonage.Vonage et y accéder par le biais d'attributs nommés, par exemple si vous avez une instance de vonage.Vonage appelée vonage_clientutilisez la syntaxe suivante :

vonage_client.vonage_api.api_method(...)

# For example:
vonage_client.video.create_session(...)

Cette version est très similaire à la précédente v3.

Accès aux modèles de données de l'API

Contrairement aux méthodes d'appel de chaque API de Vonage, les modèles de données et les erreurs spécifiques à chaque API ne sont pas accessibles via le package vonage mais plutôt par le biais du paquetage spécifique de l'API.

Pour la plupart des API, il est possible d'accéder aux modèles de données et aux erreurs à partir du niveau supérieur du paquetage de l'API, par exemple pour envoyer une requête Verify :

from vonage_verify import VerifyRequest, SmsChannel

sms_channel = SmsChannel(to='1234567890')
verify_request = VerifyRequest(
    brand='Vonage', workflow=[sms_channel]
)

response = vonage_client.verify.start_verification(
    verify_request
)
print(response)

Toutefois, certaines API comportant un grand nombre de modèles les placent sous le paquetage <vonage_api_package>.models par exemple. vonage-messages, vonage-voice et vonage-video. Pour y accéder, il suffit d'importer de <vonage_api_package>.modelsPour envoyer une image via Facebook Messenger, par exemple, procédez comme suit :

from vonage_messages.models import ( 
    MessengerImage, 
    MessengerOptions, 
    MessengerResource,
)

messenger_image_model = MessengerImage(
    to='messenger_id_to',
    from_='messenger_id_from',
    image=MessengerResource(
        url='https://example.com/image.jpg'
    ),
    messenger=MessengerOptions(
        category='message_tag', tag='my_message_tag'
    ),
)

vonage_client.messages.send(message)

Revenons à notre exemple de code complet de tout à l'heure, nous pouvons maintenant voir comment chaque partie fonctionne.

# Import objects for the Vonage client
from vonage import Vonage, Auth

# Import a data model
from vonage_application import ApplicationConfig

# Create a Vonage client instance
vonage_client = Vonage(auth=Auth(api_key='your_api_key', api_secret='your_api_secret'))

# Make the request using the ApplicationConfig data model
application_data = vonage_client.application.create_application(
    ApplicationConfig(name='My Basic Application')
)

# Print the response
print(application_data)

Résumé

Voici un bref aperçu des nouvelles fonctionnalités, des changements et des améliorations que nous avons apportés à la version 4 du SDK Python de Vonage. Voici un lien vers le guide de migration v3 -> v4 pour plus de détails sur les changements de l'API.

N'hésitez pas à essayer le nouveau SDK et à nous faire part de vos commentaires. Nous aimerions avoir de vos nouvelles et avons hâte de voir ce que vous allez créer avec Vonage !

Ressources complémentaires

• Lien vers le guide de migration v3 -> v4

• Lien vers le SDK Python de Vonage

• Rejoindre la communauté des développeurs de Vonage sur Slack

• Soumettre une demande de soutien à Vonage