O SDK do Vonage para Python v4 já está disponível!

Após uma reescrita completa, do zero, a Versão 4 do SDK do Vonage para Python já está disponível. Trata-se de uma reformulação completa do SDK anterior, que oferece melhorias e aprimoramentos para todos os usuários. 

Nesta postagem, vamos apresentar os principais recursos e mostrar como começar a usar o novo SDK do Vonage para Python, destinado a fazer chamadas às APIs do Vonage.

Migrar da versão 3

Se você está usando atualmente o SDK v3 e deseja atualizar, este guia sobre a migração da v3 para a v4 será útil.

Principais recursos

A reescrita completa nos deu a oportunidade de fazer algumas melhorias estruturais essenciais, bem como definir como o usuário deve interagir com o SDK. 

Aqui está uma lista de algumas das mudanças mais significativas:

1. Uma nova estrutura de monorepo

2. Modelos de dados Pydantic em solicitações e respostas

3. Documentação embutida aprimorada

4. Melhoria no tratamento de erros e mais informações

5. Suporte completo à Video API da Vonage

Uma nova estrutura de monorepo

A versão 4 do SDK do Python da Vonage agora utiliza uma estrutura de monorepo, com pacotes distintos para acessar diferentes APIs da Vonage, todos utilizando código comum. Ao instalar apenas o pacote de nível superior vonage puxa todos os pacotes necessários, portanto, não há necessidade de instalar mais nada diretamente. Isso nos dá mais flexibilidade quanto ao que é lançado e quando, para que possamos oferecer suporte a novas APIs mais cedo e versionar os diferentes pacotes de forma mais clara.

Modelos de dados Pydantic em solicitações e respostas

O SDK v4 faz uso intensivo de modelos de dados Pydantic para facilitar a chamada das APIs da Vonage e a análise dos resultados. 

O uso de modelos Pydantic para formar solicitações garante a tipagem correta e facilita o envio dos objetos adequados para a Vonage. As respostas agora são desserializadas em modelos Pydantic totalmente documentados, o que proporciona mais consistência do que retornar dicionários, como fazíamos na v3. Ainda é possível converter modelos Pydantic em dicionários ou strings JSON com model.model_dump e model.model_dump_json respectivamente.

Documentação embutida aprimorada

Foram adicionadas descrições de documentação (docstrings) aos métodos e modelos de dados em todo o SDK para melhorar a experiência do desenvolvedor e facilitar o desenvolvimento no IDE. Ao passar o mouse sobre um novo objeto ou método no seu IDE, você verá informações sobre o que ele faz e como chamá-lo.

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

Tratamento aprimorado de erros e mais informações

Na v3, a maioria dos erros do cliente HTTP gerava uma HttpClientError . Os erros na v4 agora são mais específicos e as mensagens de erro fornecem mais informações e contexto. 

Por exemplo, foi criado um novo HttpRequestError foi criado, com subtipos distintos, como AuthenticationError, ForbiddenError, NotFoundError etc. Você pode acessar a resposta HTTP capturando um erro HTTP e usando seu self.response atributo.

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

Alguns pacotes de API também apresentam seus próprios erros para casos específicos.

Para as APIs mais antigas da Vonage, que sempre retornam um código HTTP 200, foi incluída uma lógica de tratamento de erros para proporcionar uma experiência semelhante à das APIs mais recentes.

Agora você também pode acessar qualquer resposta HTTP com vonage.Vonage.http_client.last_response e à respectiva solicitação HTTP com vonage.Vonage.http_client.last_request, mesmo quando não há nenhum erro lançado, para lhe dar uma visão mais clara do que está acontecendo.

Suporte completo à Video API da Vonage

Foi adicionado suporte para todas as recursos da Video API da Vonage . Além dos recursos adicionados à v3, novos métodos foram incorporados para ajudar você a trabalhar com as APIs Live Captions, Audio Connector e Experience Composer.

Com isso, o SDK passa a ter os mesmos recursos do pacote OpenTok. Se você estiver usando o OpenTok, é altamente recomendável migrar para a versão 4 do SDK Python da Vonage, em vez do opentok pacote Python é altamente recomendada. Consulte o guia de migração do OpenTok para o Vonage Video para obter ajuda com isso.

Instalação

O novo SDK deve ser instalado em um novo ambiente virtual. Abra um console, crie um novo ambiente e instale o novo SDK com o pip usando os seguintes 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

Você perceberá que outros pacotes dependentes da Vonage, como vonage-http-client também foram instalados.

Se você já possui uma versão anterior do SDK, use a --upgrade opção para obter a versão mais recente:

pip install vonage --upgrade

Introdução

Para começar a usar o SDK v4, você precisará inicializar uma instância da vonage.Vonage classe, que pode ser usada para acessar os métodos da API. Em seguida, você precisará fornecer as informações de autenticação. Antes de detalharmos isso, veja aqui um exemplo completo que mostra como criar um novo aplicativo Vonage com o 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)

Agora, vamos analisar isso.

Autenticação

Dependendo da API da Vonage que você deseja usar, serão utilizadas diferentes formas de autenticação. Você precisará fornecer uma chave de API e um segredo ou o ID de uma Application da Vonage e sua chave privada correspondente. Isso é feito inicializando uma instância 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'
)

Isso auth pode então ser usado ao inicializar uma instância de vonage.Vonage. Para configurar uma instância da vonage.Vonage classe para chamar as APIs da Vonage, faça o seguinte:

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)

Acesso aos métodos da API

Para acessar métodos relacionados às APIs da Vonage, você criará uma instância da vonage.Vonage classe e acessá-los por meio de atributos nomeados; por exemplo, se você tiver uma instância de vonage.Vonage chamada vonage_client, use esta sintaxe:

vonage_client.vonage_api.api_method(...)

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

Isso é muito semelhante à versão 3 anterior.

Acesso aos modelos de dados da API

Ao contrário dos métodos para chamar cada API da Vonage, os modelos de dados e os erros específicos de cada API não são acessados por meio do vonage pacote, mas sim por meio do pacote específico da API.

Na maioria das APIs, os modelos de dados e os erros podem ser acessados a partir do nível superior do pacote da API; por exemplo, para enviar uma solicitação de Verify, faça o seguinte:

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)

No entanto, algumas APIs com muitos modelos os mantêm localizados no <vonage_api_package>.models pacote, por exemplo, vonage-messages, vonage-voice e vonage-video. Para acessá-los, basta importar de <vonage_api_package>.models, por exemplo, para enviar uma imagem pelo Facebook Messenger, faça o seguinte:

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)

Voltando ao nosso exemplo de código completo apresentado anteriormente, agora podemos ver como cada parte funciona.

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

Resumo

Esta foi uma breve visão geral dos novos recursos, alterações e aprimoramentos que introduzimos na versão 4 do SDK do Vonage para Python. Aqui está um link para o guia de migração da v3 para a v4 para obter detalhes mais específicos sobre as alterações na API.

Experimente o novo SDK e compartilhe sua opinião conosco. Adoraríamos saber o que você achou e mal podemos esperar para ver o que você vai criar com a Vonage!

Recursos adicionais

• Link para o guia de migração da v3 para a v4

• Link para o SDK do Python da Vonage

• Participe do Slack da Comunidade de Desenvolvedores da Vonage

• Enviar uma solicitação de suporte à Vonage