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

Tl;dr : La v3.0.0 du SDK Python est disponible! La plupart des PR sont des refontes internes pour préparer le terrain pour de futures améliorations, mais nous avons également ajouté quelques nouvelles fonctionnalités pour vous aider à tirer le meilleur parti de l'utilisation du SDK.

Depuis que j'ai (Max) rejoint Vonage il y a 4 mois, j'ai passé une grande partie de mon temps à refaire le SDK Python de base de Vonage. Dans cette version, je me suis concentré sur les améliorations visant à réduire la dette technique et à améliorer la lisibilité. En conséquence, les changements apportés dans la version 3.0.0 préparent principalement le terrain pour que de nouvelles fonctionnalités intéressantes puissent être ajoutées plus tard.

Dans ce billet, j'expliquerai certains des changements que j'ai apportés à la v3.0.0, et ce qui a motivé chacun d'entre eux.

Une vue d'ensemble

Le principal changement structurel a consisté à organiser les méthodes de chaque API dans des classes et des modules distincts. Cela permet de savoir plus clairement quelle API vous appelez et de définir le type d'authentification pour chaque API lorsque vous effectuez une demande par l'intermédiaire du SDK.

Il y avait également beaucoup de doublons. Par exemple, il y avait cinq méthodes distinctes, réparties sur trois fichiers différents, pour effectuer la même requête POST de base avec quelques variations. J'ai consolidé toutes ces méthodes en une seule fonction qui fait un appel REST avec le paquetage requests en tenant compte des différentes méthodes d'authentification et des types de corps attendus par chaque API.

La principale différence entre la v2 et la v3 est qu'une grande partie du code obsolète a été supprimée, ce qui entraîne un certain nombre de changements radicaux. Toutes les méthodes de classe Client qui appelaient une API spécifique ont été supprimées, car elles sont désormais accessibles depuis le module spécifique de cette API. Il y avait également des méthodes qui auraient dû être dépréciées et supprimées il y a longtemps, ou qui n'ont jamais été ajoutées, que nous avons maintenant dépréciées et que nous supprimerons dans une version ultérieure.

Nous avons ajouté des paramètres optionnels à la classe Client pour vous permettre de personnaliser le délai d'attente, les nouvelles tentatives et les options de regroupement pour l'ensemble de la session avec un client Vonage. Nous avons également apporté quelques améliorations à l'API de tarification, avec une nouvelle méthode et la possibilité d'effectuer des requêtes basées sur le trafic SMS ou vocal.

Jetons un coup d'œil !

Obtenir la nouvelle version

Pour télécharger la nouvelle version v3.0.0, il suffit de lancer la commande suivante (il est conseillé d'effectuer cette opération dans un environnement virtuel !)

Cette opération permet de télécharger la nouvelle version à partir de zéro ou de mettre à jour une version existante du SDK.

Une petite note

Dans les versions précédentes, j'ai ajouté une classe Messages et j'ai modifié la façon dont les méthodes pouvaient être appelées. Par exemple, pour envoyer un SMS, il fallait auparavant procéder comme suit :

client = vonage.Client(key='my_key', secret='my_secret')
sms = vonage.Sms(client)
sms.send_message([message_details_go_here])

Alors que maintenant vous pouvez le faire pour tous les appels d'API :

client = vonage.Client(key='my_key', secret='my_secret')
client.sms.send_message([message_details_go_here])

Les exemples présentés dans ce billet suivront ce dernier modèle.

Nouvelles classes

Initialement, tout le code se trouvait dans une seule Client classe. C'est-à-dire chaque méthode, pour chaque type de requête pouvant être effectuée avec le SDK. Il y a quelques années, un remaniement a été entrepris pour modulariser ces demandes dans des classes basées sur les API qu'elles appellent : Voice, Sms, Verify et ainsi de suite. Ce refactor n'a jamais été achevé, donc au cours des derniers mois, j'ai déprécié les méthodes de la classe Client et j'ai ajouté de nouveaux modules comme number_insight, messages, account, etc. Désormais, les méthodes liées à une API spécifique sont appelées à partir de ce module particulier.

Par exemple, vous pouvez désormais faire une demande de recherche de numéro de base :

client = vonage.Client(key='my_key', secret='my_secret')
client.number_insight.get_basic_number_insight(number=MY_NUMBER)

Le code est désormais modulaire, mais il est accessible à partir d'une seule classe de client. La version 3.0.0 supprime les méthodes qui se trouvaient à l'origine dans la classe Client elles doivent donc être appelées comme décrit ci-dessus.

Nouvelles options de connexion du client

Lorsque vous instanciez un objet Client vous pouvez maintenant spécifier l'option max_retries, timeout, pool_connections et pool_maxsize qui seront utilisés pour chaque requête effectuée avec cet objet. Client avec cet objet. Les options peuvent être spécifiées de la manière suivante :

client = vonage.client(
key='my_key',
secret='my_secret',
timeout=10,  # timeout in seconds
pool_connections=10,
pool_maxsize=10,
max_retries=5
)

Ces options sont utiles si vous envoyez de nombreuses requêtes en même temps ou si vous souhaitez autoriser les requêtes à dépasser le délai d'attente et à être relancées.

Par défaut, la demande n'est pas interrompue, mais toute valeur en secondes peut être spécifiée. Le nombre maximal de tentatives par défaut est de 3, mais toute valeur entière est valable. De même, vous pouvez spécifier n'importe quelle valeur entière pour le nombre de connexions au pool et la taille maximale du pool (bien que ces deux valeurs soient fixées par défaut à 10).

Nouveaux arguments pour le mot-clé "pricing" dans les appels à l'API "Pricing".

Il est désormais possible de spécifier si vous voulez voir les prix pour les SMS ou la voix dans les appels à l'API de tarification. Le SMS est la valeur par défaut et le prix de la voix peut être demandé de la manière suivante :

client.account.get_country_pricing(country_code='GB', type='voice')

Ajout d'une méthode pour obtenir les prix pour tous les pays

Nous avons ajouté une méthode get_all_countries_pricing à la classe Account Nous avons ajouté une méthode à la classe Elle vous permet de voir les prix pour tous les pays pris en charge pour les SMS ou la Voice.

client.account.get_all_countries_pricing() # returns sms pricing for all countries
client.account.get_all_countries_pricing(type='voice') # returns voice pricing for all countries

Suppression des méthodes de l'API de recherche de messages

L'API de recherche de messages a été supprimée par Vonage, j'ai donc supprimé les méthodes qui l'appelaient. Voir cet avis de spécification de l'API pour plus d'informations.

Vonage recommande de migrer tous les appels vers l'API Reports. Comme il s'agit d'une fonction bêta, elle n'est pas prise en charge dans le SDK Python, mais ce guide ne contient pas d'informations sur la migration. ce guide explique comment migrer vers l'API Reports.

Suppression de la création automatique de clients

Auparavant, il était possible d'instancier une classe d'API (par ex. Sms) directement, en transmettant des informations d'identification, car un client était créé à cette occasion. Cette possibilité a été supprimée, car nous voulons que tout le monde utilise les classes en créant un client et en l'utilisant pour appeler les méthodes de l'API.

Suppression des méthodes obsolètes des classes Voice et NumberInsight

La classe Voice contient des méthodes (initiate_call, initiate_tts_call et initiate_tts_prompt_call) qui exposaient des points d'extrémité qui ont été dépréciés par Vonage en 2017 ! Ces méthodes ont été retirées du SDK. De même, la méthode request_number_insight a été supprimée car elle a été remplacée par les méthodes et les points de terminaison get_{basic/standard/advanced}_number_insight et les points de terminaison.

Renommer une méthode de secrets

La méthode Account.delete_secret a été renommée en revoke_secret pour l'aligner sur la documentation. Il n'y a pas grand-chose à dire ici, il s'agissait d'une simple erreur de correspondance que nous avons corrigée.

Dépréciations

Nous avons supprimé la classe ApplicationV2 et avons créé une classe Application afin d'harmoniser la dénomination avec celle des autres méthodes. Le changement est simple :

ApplicationV2.list_applications() # Old class
Application.list_applications() # New class

Deux anciennes méthodes de l'API Pricing (get_sms_pricing et get_voice_pricing) ont été supprimées car elles appelaient des points de terminaison obsolètes.

Enfin, la méthode appelant l'API Redact (redact_transaction) a été supprimée car il s'agit d'un produit de prévisualisation de développement qui n'est pas pris en charge par les SDK de serveur de Vonage.

Ils seront tous supprimés dans une version ultérieure.

Mise à jour à partir de la version 2.x

Si vous passez de la version 2.x à la nouvelle version, assurez-vous que si vous utilisez des méthodes de l'API directement à partir de la classe client, utilisez plutôt les méthodes de la classe API correspondante.

Par exemple

client.get_basic_number_insight(number=MY_NUMBER) # API methods have been removed from the client class - this won't work
client.number_insight.get_basic_number_insight(number=MY_NUMBER) # Call the methods using the relevant API classes instead

Où allons-nous ?

Comme vous pouvez le constater, nous avons apporté quelques modifications à la façon dont les API sont appelées dans cette version. Dans les prochaines versions, nous ajouterons des fonctionnalités vidéo au SDK. Nous prévoyons également de supprimer les méthodes obsolètes, d'ajouter la prise en charge de asyncio et éventuellement de faire plus pour valider les entrées, en utilisant un outil tel que Pydantic.

N'hésitez pas à télécharger la nouvelle version et à nous dire ce que vous en pensez ! S'il y a autre chose que vous voulez voir, ou si vous voulez contribuer, l'ensemble du SDK est open-source et consultable sur GitHub. Vous pouvez commencer dès aujourd'hui avec des crédits gratuits sur le site Web de Vonage Developer.