¡Vonage Python SDK v4 ya está disponible!

Después de una reescritura completa, la versión 4 del SDK Python de Vonage ya está disponible. Es un rediseño completo del SDK anterior que ofrece mejoras para todos los usuarios.

En esta publicación, recorreremos las funciones clave y te mostraremos cómo comenzar a usar el nuevo SDK Python de Vonage para llamar a las API de Vonage.

Migrar desde v3

Si actualmente utiliza SDK v3 y desea actualizarlo, esta guía sobre la migración de v3 a v4 le resultará útil.

Características principales

La reescritura desde cero nos dio la oportunidad de introducir algunas mejoras estructurales fundamentales y decidir cómo debía interactuar el usuario con el SDK.

He aquí una lista de algunos de los cambios más significativos:

1. Una nueva estructura monorrepo

2. Modelos de datos pydánticos en solicitudes y respuestas

3. Documentación en línea mejorada

4. Mejor gestión de errores y más información

5. Compatibilidad total con la API de Video de Vonage

Una nueva estructura monorrepo

v4 del SDK de Python de Vonage ahora utiliza una estructura monorepo, con diferentes paquetes para llamar a diferentes API de Vonage, todos utilizando código común. La instalación del paquete vonage incluye todos los paquetes necesarios, por lo que no es necesario instalar nada más directamente. Esto nos da más flexibilidad en lo que se publica y cuándo, por lo que podemos soportar nuevas API antes y versionar más claramente los diferentes paquetes.

Modelos de datos pydánticos en solicitudes y respuestas

El SDK v4 hace un uso intensivo de modelos de datos Pydantic para facilitar la llamada a las API de Vonage y analizar los resultados.

El uso de modelos Pydantic para formar las solicitudes refuerza la tipificación correcta y hace que sea más fácil pasar los objetos correctos a Vonage. Las respuestas ahora se deserializan en modelos Pydantic completamente documentados, lo que da más consistencia que devolver diccionarios como hacíamos en la v3. Todavía puedes convertir modelos Pydantic en diccionarios o cadenas JSON con model.model_dump y model.model_dump_json respectivamente.

Documentación en línea mejorada

Se han añadido docstrings a los métodos y modelos de datos de todo el SDK para mejorar la experiencia del desarrollador y facilitar el desarrollo dentro del IDE. Al pasar el ratón por encima de un nuevo objeto/método en su IDE, obtendrá información sobre lo que hace y cómo llamarlo.

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

Gestión de errores mejorada y más información

En la v3, la mayoría de los errores de cliente HTTP lanzaban una excepción general HttpClientError general. En la versión 4, los errores son más precisos y los mensajes de error ofrecen más información y contexto.

Por ejemplo, se ha creado un nuevo HttpRequestError con subtipos distintos como AuthenticationError, ForbiddenError, NotFoundError etc. Puede acceder a la respuesta HTTP capturando un error HTTP y utilizando su atributo self.response del error.

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

Algunos paquetes de API también tienen sus propios errores para casos específicos.

Para las API más antiguas de Vonage que siempre devuelven un HTTP 200, se ha incluido una lógica de manejo de errores para brindar una experiencia similar a la de las API más nuevas.

Ahora también puede acceder a cualquier respuesta HTTP con vonage.Vonage.http_client.last_response y su correspondiente petición HTTP con vonage.Vonage.http_client.last_requestincluso si no se ha producido ningún error, para poder saber mejor qué está ocurriendo.

Compatibilidad total con la API de Video de Vonage

Se ha añadido compatibilidad con todas las API de Video de Vonage de Vonage. Además de las funciones añadidas a la v3, se han añadido nuevos métodos para ayudarte a trabajar con las API Live Captions, Audio Connector y Experience Composer.

Esto lleva al SDK a la paridad de características con el paquete OpenTok. Si utilizas OpenTok, se recomienda encarecidamente migrar a la versión 4 del SDK de Python de Vonage en lugar del paquete Python. opentok paquete Python. Consulta la guía de migración OpenTok -> Vonage Video para obtener ayuda.

Instalación

El nuevo SDK debe instalarse en un nuevo entorno virtual. Abra una consola, cree un nuevo entorno e instale el nuevo SDK con pip utilizando los siguientes comandos:

# 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

Observarás que otros paquetes dependientes de Vonage, como vonage-http-client también se han instalado.

Si ya dispone de una versión anterior del SDK, utilice la opción --upgrade para obtener la última versión:

pip install vonage --upgrade

Primeros pasos

Para empezar a utilizar el SDK v4, deberá inicializar una instancia de la clase vonage.Vonage que puede utilizarse para acceder a los métodos de la API. A continuación, tendrás que proporcionar información de autenticación. Antes de desglosar esto, aquí hay un ejemplo completo que muestra cómo crear una nueva aplicación de aplicación de Vonage con el 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)

Ahora, vamos a desglosar esto.

Autenticación

Según la API de Vonage que quieras usar, utilizarás diferentes formas de autenticación. Deberás proporcionar una clave y un secreto de API o el ID de una aplicación de Vonage y su clave privada correspondiente. Esto se hace inicializando una instancia 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'
)

Este auth se puede utilizar para inicializar una instancia de vonage.Vonage. Para configurar una instancia de la clase vonage.Vonage para llamar a las API de Vonage, haz esto:

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)

Acceso a los métodos de la API

Para acceder a los métodos relacionados con las API de Vonage, crearás una instancia de la clase vonage.Vonage y accederás a ellos a través de atributos con nombre, por ejemplo, si tienes una instancia de vonage.Vonage llamada vonage_clientutiliza esta sintaxis:

vonage_client.vonage_api.api_method(...)

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

Es muy similar a la anterior v3.

Acceso a los modelos de datos de la API

A diferencia de los métodos para llamar a cada API de Vonage, no se accede a los modelos de datos y errores específicos de cada API a través del paquete vonage sino a través del paquete específico de la API.

Para la mayoría de las APIs, se puede acceder a los modelos de datos y errores desde el nivel superior del paquete API, por ejemplo, para enviar una solicitud Verify, haga esto:

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)

Sin embargo, algunas API con muchos modelos los tienen ubicados bajo el paquete <vonage_api_package>.models por ejemplo vonage-messages, vonage-voice y vonage-video. Para acceder a ellas, basta con importar de <vonage_api_package>.modelspor ejemplo, para enviar una imagen a través de Facebook Messenger, haga lo siguiente:

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)

Volviendo a nuestro ejemplo de código completo de antes, ahora podemos ver cómo funciona cada parte.

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

Resumen

Este ha sido un breve resumen de las nuevas funciones, cambios y mejoras que hemos traído en la v4 del SDK Python de Vonage. Aquí hay un enlace a la guía de migración v3 -> v4 para obtener detalles más específicos sobre los cambios en la API.

Prueba el nuevo SDK y cuéntanos lo que piensas. Nos encantaría saber de ti y ¡no podemos esperar a ver lo que construyes con Vonage!

Recursos adicionales

• Enlace a la guía de migración v3 -> v4

• Enlace al SDK Python de Vonage

• Únete a la comunidad de desarrolladores de Vonage en Slack

• Enviar una solicitud de soporte de Vonage