Version 3.0.0 des Vonage Python SDK ist jetzt verfügbar!

Tl;dr: v3.0.0 des Python SDK ist erschienen! Der größte Teil der PR ist internes Refactoring, um die Grundlage für zukünftige Verbesserungen zu schaffen, aber wir fügen auch ein paar neue Funktionen hinzu, die Ihnen helfen, das SDK optimal zu nutzen.

Seit ich (Max) vor 4 Monaten zu Vonage gestoßen bin, habe ich viel Zeit damit verbracht, das Python-SDK von Vonage zu überarbeiten. Kern-Python-SDK. In dieser Version habe ich mich auf Verbesserungen konzentriert, um technische Schulden zu reduzieren und die Lesbarkeit zu erhöhen. Das Ergebnis ist, dass die Änderungen in der Version 3.0.0 vor allem die Grundlage dafür bilden, dass später coole neue Funktionen hinzugefügt werden können.

In diesem Beitrag erkläre ich einige der Änderungen, die ich für v3.0.0 vorgenommen habe, und was die Motivation für jede dieser Änderungen war.

Ein Überblick

Die wichtigste strukturelle Änderung bestand darin, die Methoden für jede API in separaten Klassen und Modulen zu organisieren. Dadurch wird klarer, welche API Sie aufrufen, und wir können den Authentifizierungstyp für jede API festlegen, wenn Sie eine Anforderung über das SDK stellen.

Außerdem gab es eine Menge Doppelarbeit. Zum Beispiel gab es fünf verschiedene Methoden, die sich über drei verschiedene Dateien erstreckten, um dieselbe grundlegende POST-Anfrage mit ein paar Variationen zu stellen. Ich habe alle diese Methoden in einer einzigen Funktion zusammengefasst, die einen REST-Aufruf mit dem requests Paket aufruft, wobei die verschiedenen Authentifizierungsmethoden und Body-Typen berücksichtigt werden, die von jeder API erwartet werden.

Der Hauptunterschied zwischen v2 und v3 besteht darin, dass eine Menge veralteter Code entfernt wurde, so dass es eine Reihe von Änderungen gibt. Alle Client Klassenmethoden, die eine bestimmte API aufriefen, wurden entfernt, da der Zugriff auf sie nun über das spezifische Modul für diese API erfolgt. Es gab auch einige Methoden, die schon vor langer Zeit veraltet waren und entfernt werden sollten oder nie hinzugefügt wurden, die jetzt veraltet sind und in einer späteren Version entfernt werden.

Wir haben optionale Parameter zur Client Klasse hinzugefügt, mit denen Sie Timeout, Wiederholungen und Pooling-Optionen für die gesamte Sitzung mit einem Vonage-Client anpassen können. Außerdem haben wir die Preis-API mit einer neuen Methode und der Möglichkeit, Abfragen auf Basis von SMS- oder Voice-Verkehr durchzuführen, verbessert.

Schauen wir uns das mal an!

Holen Sie sich die neue Version

Um die neue Version 3.0.0 herunterzuladen, führen Sie einfach diesen Befehl aus (Sie sollten dies in einer virtuellen Umgebung tun!):

Dadurch wird die neue Version von Grund auf heruntergeladen oder eine bestehende Version des SDK auf die neueste Version aktualisiert.

Eine kurze Anmerkung

In früheren Versionen habe ich eine Messages Klasse hinzugefügt und die Art und Weise geändert, wie die Methoden aufgerufen werden können. Um zum Beispiel eine SMS zu senden, musste man früher Folgendes tun:

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

Jetzt hingegen können Sie dies für alle API-Aufrufe tun:

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

Meine Beispiele in diesem Beitrag folgen dem letztgenannten Muster.

Neue Klassen

Ursprünglich befand sich der gesamte Code in einer einzigen Client Klasse. Das heißt, jede Methode, für jede Art von Anfrage, die mit dem SDK durchgeführt werden kann. Vor ein paar Jahren wurde mit einer Umstrukturierung begonnen, um diese Anfragen in Klassen zu modularisieren, die auf den APIs basieren, die sie aufrufen: Voice, Sms, Verify und so weiter. Dieser Refactor wurde nie abgeschlossen, also habe ich in den letzten Monaten die Methoden in der Client Klasse veraltet und fügte neue Module wie number_insight, messages, accountusw. Jetzt werden Methoden, die sich auf eine bestimmte API beziehen, von diesem speziellen Modul aufgerufen.

Um z. B. einen einfachen Antrag auf Nummerneinsicht zu stellen, können Sie jetzt Folgendes tun:

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

Der Code ist nun modularisiert, kann aber von einer einzigen Client-Klasse aus aufgerufen werden. V3.0.0 entfernt die Methoden, die ursprünglich in der Client Klasse waren, entfernt, so dass sie nun wie oben beschrieben aufgerufen werden müssen.

Neue Client-Verbindungsoptionen

Bei der Instanziierung eines Client Objekts können Sie jetzt die optionale Angabe max_retries, timeout, pool_connections und pool_maxsize optionale Schlüsselwortargumente angeben, die für jede mit diesem Objekt gestellte Anfrage verwendet werden. Client Objekt verwendet werden. Die Optionen können auf diese Weise angegeben werden:

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

Diese Optionen sind nützlich, wenn Sie viele Anfragen auf einmal senden oder zulassen möchten, dass Anfragen eine Zeitüberschreitung erleiden und erneut versucht werden.

Standardmäßig wird die Anfrage nicht unterbrochen, aber es kann ein beliebiger Wert in Sekunden angegeben werden. Die maximale Anzahl der Wiederholungen ist standardmäßig 3, aber jeder ganzzahlige Wert ist zulässig. Ebenso können Sie einen beliebigen ganzzahligen Wert für die Anzahl der Pool-Verbindungen und die maximale Pool-Größe angeben (beide haben jedoch einen Standardwert von 10).

Neue Schlüsselwortargumente für die Preisgestaltung in Aufrufen der Pricing API

Es ist jetzt möglich, bei Aufrufen der Preis-API anzugeben, ob Sie die Preise für SMS oder Voice sehen möchten. SMS ist die Standardeinstellung und Voice-Preise können wie folgt angefordert werden:

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

Eine Methode zum Abrufen von Preisen für alle Länder wurde hinzugefügt

Wir haben eine get_all_countries_pricing Methode zu der Account Klasse hinzugefügt. Damit können Sie die Preise für alle unterstützten Länder für SMS oder Voice sehen.

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

Entfernte Methoden der Nachrichtensuche API

Die API für die Nachrichtensuche wurde von Vonage entfernt, daher habe ich die Methoden, die sie aufrufen, entfernt. Siehe diesen Hinweis zur API-Spezifikation für weitere Informationen.

Vonage empfiehlt, alle Aufrufe zur Reports API zu migrieren. Da es sich hierbei um eine Beta-Funktion handelt, wird sie im Python-SDK nicht unterstützt, aber dieser Leitfaden erklärt jedoch, wie die Migration zur Reports API durchgeführt werden kann.

Automatische Client-Erstellung entfernt

Zuvor war es möglich, eine API-Klasse (z. B. Sms) direkt zu instanziieren, indem man die Anmeldeinformationen übergibt, da dabei ein Client erstellt wurde. Dies wurde nun entfernt, da wir möchten, dass jeder die Klassen verwendet, indem er einen Client erstellt und diesen zum Aufrufen von API-Methoden verwendet.

Entfernte veraltete Methoden aus den Klassen Voice und NumberInsight

Die Voice Klasse enthält Methoden (initiate_call, initiate_tts_call und initiate_tts_prompt_call), die Endpunkte enthielten, die 2017 von Vonage veraltet wurden! Diese sind nun aus dem SDK entfernt worden. In ähnlicher Weise wurde die request_number_insight Methode entfernt worden, da sie durch die get_{basic/standard/advanced}_number_insight Methoden und Endpunkte ersetzt wurde.

Umbenennung einer Geheimhaltungsmethode

Die Methode Account.delete_secret Methode wurde umbenannt in revoke_secret um sie in Einklang mit der Dokumentation zu bringen. Hier gibt es nicht viel zu sagen, es gab eine einfache Unstimmigkeit, die wir jetzt korrigiert haben.

Verwerfungen

Wir verwerfen die ApplicationV2 Klasse veraltet und haben eine Application Klasse geschaffen, um die Benennung mit anderen Methoden in Einklang zu bringen. Die Umstellung ist einfach:

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

Zwei alte Pricing-API-Methoden (get_sms_pricing und get_voice_pricing) wurden veraltet, da sie veraltete Endpunkte aufrufen.

Schließlich wurde die Methode zum Aufrufen der Redact API (redact_transaction) veraltet, da es sich um ein Entwicklungsvorschau-Produkt handelt, das in den Vonage Server-SDKs nicht unterstützt wird.

Sie werden alle in einer späteren Version entfernt werden.

Aufrüstung von 2.x

Wenn Sie von v2.x auf die neue Version aktualisieren, stellen Sie sicher, dass Sie, wenn Sie API-Methoden direkt von der Client-Klasse verwenden, stattdessen die Methoden der entsprechenden API-Klasse verwenden.

z.B.

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

Wohin gehen wir?

Wie Sie sehen können, haben wir in dieser Version einige Änderungen am Aufruf der APIs vorgenommen. In zukünftigen Versionen werden wir Video-Funktionalität in das SDK einbauen. Wir planen auch, die veralteten Methoden zu entfernen, Unterstützung für asyncio hinzuzufügen und schließlich mehr für die Validierung von Eingaben zu tun, indem wir ein Tool wie Pydantic verwenden.

Laden Sie sich die neue Version herunter und lassen Sie uns wissen, was Sie davon halten! Wenn Sie noch etwas sehen wollen oder etwas beitragen möchten, ist das gesamte SDK als Open-Source und einsehbar auf GitHub. Sie können noch heute mit kostenlosen Credits auf der Vonage Entwickler-Website.