Vonage Python SDK v4 ist jetzt live!

Nach einer kompletten Überarbeitung ist Version 4 des Vonage Python SDK jetzt verfügbar. Es ist eine komplette Überarbeitung des vorherigen SDKs, die Verbesserungen und Erweiterungen für alle Benutzer bietet.

In diesem Beitrag stellen wir Ihnen die wichtigsten Funktionen vor und zeigen Ihnen, wie Sie mit dem neuen Python-SDK von Vonage APIs aufrufen können.

Von v3 migrieren

Wenn Sie derzeit SDK v3 verwenden und ein Upgrade durchführen möchten, finden Sie in dieser Anleitung zur Migration von v3 auf v4 hilfreich sein.

Wesentliche Merkmale

Eine grundlegende Neufassung gab uns die Möglichkeit, einige wichtige strukturelle Verbesserungen vorzunehmen und zu entscheiden, wie der Benutzer mit dem SDK interagieren sollte.

Im Folgenden finden Sie eine Liste der wichtigsten Änderungen:

1. Eine neue Monorepo-Struktur

2. Pydantische Datenmodelle in Anfragen und Antworten

3. Verbesserte Inline-Dokumentation

4. Verbesserte Fehlerbehandlung und mehr Informationen

5. Volle Unterstützung für die Vonage Video API

Eine neue Monorepo-Struktur

v4 des Vonage Python SDKs verwendet nun eine Monorepo-Struktur, wobei verschiedene Pakete für den Aufruf verschiedener Vonage APIs alle einen gemeinsamen Code verwenden. Die Installation nur des Top-Level vonage Pakets zieht alle Pakete, die Sie benötigen, mit sich, so dass Sie nichts anderes direkt installieren müssen. Dies gibt uns mehr Flexibilität, was und wann veröffentlicht wird, so dass wir neue APIs früher unterstützen und die verschiedenen Pakete klarer versionieren können.

Pydantische Datenmodelle in Anträgen und Antworten

Das v4 SDK nutzt in hohem Maße die Pydantic-Datenmodelle um den Aufruf von Vonage-APIs und das Parsen der Ergebnisse zu erleichtern.

Die Verwendung von Pydantic-Modellen zur Formulierung von Anfragen erzwingt eine korrekte Typisierung und macht es einfacher, die richtigen Objekte an Vonage zu übergeben. Antworten werden jetzt in vollständig dokumentierte Pydantic-Modelle deserialisiert, was mehr Konsistenz bietet als die Rückgabe von Wörterbüchern wie in v3. Sie können Pydantic-Modelle immer noch in Wörterbücher oder JSON-Strings umwandeln mit model.model_dump und model.model_dump_json umwandeln.

Verbesserte Inline-Dokumentation

Docstrings wurden zu Methoden und Datenmodellen im gesamten SDK hinzugefügt, um die Erfahrung der Entwickler zu verbessern und die Entwicklung in der IDE zu erleichtern. Wenn Sie mit der Maus über ein neues Objekt/eine neue Methode in Ihrer IDE fahren, erhalten Sie Informationen darüber, was es tut und wie es aufgerufen werden kann.

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

Verbesserte Fehlerbehandlung und mehr Informationen

In v3 lösten die meisten HTTP-Client-Fehler eine allgemeine HttpClientError Ausnahme. Die Fehler in v4 sind nun feiner gegliedert und die Fehlermeldungen enthalten mehr Informationen und Kontext.

Zum Beispiel wurde ein neuer HttpRequestError erstellt, mit unterschiedlichen Subtypen wie AuthenticationError, ForbiddenError, NotFoundError usw. Sie können auf die HTTP-Antwort zugreifen, indem Sie einen HTTP-Fehler abfangen und dessen self.response Attribut verwenden.

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

Einige API-Pakete haben auch ihre eigenen Fehler für bestimmte Fälle.

Für ältere Vonage-APIs, die immer ein HTTP 200 zurückgeben, wurde eine Fehlerbehandlungslogik eingebaut, um eine ähnliche Erfahrung wie bei den neueren APIs zu ermöglichen.

Sie können nun auch auf jede HTTP-Antwort mit vonage.Vonage.http_client.last_response und die entsprechende HTTP-Anfrage mit vonage.Vonage.http_client.last_requestzugreifen, auch wenn kein Fehler aufgetreten ist, um einen besseren Einblick in die Vorgänge zu erhalten.

Volle Unterstützung für die Vonage Video API

Die Unterstützung wurde für alle Vonage Video API Funktionen. Zusätzlich zu den in Version 3 hinzugefügten Funktionen wurden neue Methoden hinzugefügt, die Ihnen die Arbeit mit den APIs Live Captions, Audio Connector und Experience Composer erleichtern.

Dies bringt das SDK auf Funktionsgleichheit mit dem OpenTok-Paket. Wenn Sie OpenTok verwenden, ist eine Migration auf v4 des Vonage Python SDK anstelle des opentok Python-Paket wird dringend empfohlen. Siehe den OpenTok -> Vonage Video Migrationsleitfaden für Hilfe bei diesem Vorgang.

Einrichtung

Das neue SDK sollte in einer neuen virtuellen Umgebung installiert werden. Öffnen Sie eine Konsole, erstellen Sie eine neue Umgebung und installieren Sie das neue SDK mit pip unter Verwendung der folgenden Befehle:

# 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

Sie werden feststellen, dass andere abhängige Vonage-Pakete, wie z.B. vonage-http-client ebenfalls installiert worden sind.

Wenn Sie bereits eine frühere Version des SDKs besitzen, verwenden Sie die --upgrade Option, um die neueste Version zu erhalten:

pip install vonage --upgrade

Erste Schritte

Um mit dem v4 SDK zu beginnen, müssen Sie eine Instanz der vonage.Vonage Klasse initialisieren, die für den Zugriff auf API-Methoden verwendet werden kann. Anschließend müssen Sie Authentifizierungsinformationen bereitstellen. Bevor wir dies näher erläutern, finden Sie hier ein vollständiges Beispiel, das Ihnen zeigt, wie Sie eine neue Vonage-Anwendung mit dem v4 SDK erstellt:

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)

Schauen wir uns das mal genauer an.

Authentifizierung

Abhängig von der Vonage-API, die Sie verwenden möchten, werden Sie verschiedene Formen der Authentifizierung verwenden. Sie müssen entweder einen API-Schlüssel und ein Geheimnis oder die ID einer Vonage-Anwendung und den entsprechenden privaten Schlüssel bereitstellen. Dies geschieht durch die Initialisierung einer Instanz von 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'
)

Diese auth kann dann beim Initialisieren einer Instanz von vonage.Vonage. Zum Einrichten einer Instanz der vonage.Vonage Klasse für den Aufruf von Vonage-APIs einzurichten, gehen Sie folgendermaßen vor:

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)

Zugriff auf API-Methoden

Um auf Methoden zuzugreifen, die sich auf Vonage-APIs beziehen, erstellen Sie eine Instanz der vonage.Vonage Klasse und greifen über benannte Attribute auf sie zu, z. B. wenn Sie eine Instanz von vonage.Vonage namens vonage_clienthaben, verwenden Sie diese Syntax:

vonage_client.vonage_api.api_method(...)

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

Dies ist der vorherigen Version 3 sehr ähnlich.

Zugriff auf API-Datenmodelle

Im Gegensatz zu den Methoden zum Aufrufen der einzelnen Vonage-APIs erfolgt der Zugriff auf die für die einzelnen APIs spezifischen Datenmodelle und Fehler nicht über das vonage Paket, sondern über das spezifische API-Paket zugegriffen.

Bei den meisten APIs kann von der obersten Ebene des API-Pakets aus auf Datenmodelle und Fehler zugegriffen werden, z. B. um eine Verify-Anfrage zu senden, tun Sie dies:

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)

Bei einigen APIs mit vielen Modellen befinden sich diese jedoch unter dem <vonage_api_package>.models Paket, z.B. vonage-messages, vonage-voice und vonage-video. Um auf diese zuzugreifen, importieren Sie einfach von <vonage_api_package>.modelsimportieren, z. B. um ein Bild über den Facebook Messenger zu versenden, tun Sie dies:

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)

Kehren wir zu unserem vollständigen Codebeispiel von vorhin zurück, können wir nun sehen, wie die einzelnen Teile funktionieren.

# 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)

Zusammenfassung

Dies war ein kurzer Überblick über die neuen Funktionen, Änderungen und Verbesserungen, die wir in v4 des Vonage Python SDK eingebracht haben. Hier ist ein Link zum v3 -> v4 Migrationsleitfaden für weitere Details zu den API-Änderungen.

Bitte probieren Sie das neue SDK aus und teilen Sie uns Ihre Meinung mit. Wir würden uns freuen, von Ihnen zu hören und können es kaum erwarten, zu sehen, was Sie mit Vonage aufbauen!

Zusätzliche Ressourcen

• Link zum Leitfaden für die Migration v3 -> v4

• Link zum Vonage Python SDK

• Werden Sie Mitglied der Vonage Entwickler-Community Slack

• Vonage Support-Anfrage einreichen