Guia de transição do Vonage Video para Python

A transição de Opentok-Python-SDK para vonage-python-sdk

Introdução

Objetivo

O objetivo deste documento é fornecer um ponto de partida para a transição do SDK do servidor OpenTok para Python para o SDK do servidor Vonage para Python. Há um guia de migração mais específico e detalhado, disponível neste link.

Âmbito

Este documento pressupõe que você esteja usando, no mínimo, a versão 3.9.0 ou posterior à a SDK do OpenTok para Python.

A Video API é totalmente compatível com o SDK do Vonage para Python. Você deve usar a versão completa mais recente do SDK, que pode ser encontrada em GitHub ou PyPI.

Suposições

Este guia destina-se a ser seguido por um engenheiro de software profissional. Presume-se que o leitor possua, no mínimo, um nível básico de conhecimento em Python, nas ferramentas comuns de desenvolvimento em Python, em sistemas de compilação e no Git (ou outro sistema de controle de versão).

Você deve ter facilidade para ler e escrever código em Python, gerenciar dependências de projetos, bem como implantar e executar um projeto em Python. Recomenda-se o uso de um ambiente virtual de Python.

Uma introdução à linguagem Python e às ferramentas associadas está muito além do escopo deste documento.

Recursos

Os links a seguir são úteis para leituras complementares a este documento e como referência para qualquer assunto não abordado neste documento:

Vonage

TokBox

Planejando sua migração

Antes de fazer a transição do OpenTok para o Vonage Video, é importante levar em conta a magnitude da tarefa para definir expectativas realistas.

Avaliar o impacto

A primeira pergunta a se fazer é: qual a proporção do código do seu aplicativo que depende do SDK do OpenTok?

Faça uma lista de todos os arquivos nos quais o SDK é usado diretamente. Ou seja, qualquer .py arquivo que contém um import opentok ou from opentok import... declaração. Você pode pesquisar os arquivos do seu projeto usando um IDE ou uma ferramenta de linha de comando para identificar os arquivos afetados.

Linha do tempo

Leve em consideração o tempo necessário para concluir a transição. Isso dependerá da sua experiência com o projeto e do impacto dele, bem como dos testes. É fundamental contar com um bom conjunto de testes para que você possa verificar a equivalência entre os SDKs de vídeo do OpenTok e da Vonage. O tempo necessário para concluir a transição é aproximadamente proporcional ao número de locais em que o SDK do OpenTok é usado em seu código, bem como à variedade de recursos utilizados. Algumas chamadas de API serão mais simples de substituir do que outras.

Controle de versões

O OpenTok e o Vonage Video são dois produtos diferentes — isso torna impossível uma migração gradual.

Você deve criar um novo branch no seu sistema de controle de versão para a transição, de modo a poder fazer alterações gradualmente e com frequência sem afetar o projeto existente. Você também pode usar os testes do projeto existente como referência para verificar a correção, caso sejam abrangentes. O ideal é que você só faça a fusão do branch de transição com o branch principal depois de ter concluído a conversão.

Principais mudanças e considerações

Atualização do pacote

Primeiramente, você precisará instalar ou atualizar o SDK do Vonage para Python no seu projeto. Para isso, execute o comando pip install -U vonage.

Para uma migração gradual, você pode incluir as dependências do OpenTok e do Vonage em seu projeto; no entanto, recomendamos enfaticamente que isso seja feito apenas para fins de teste, e não para implantações em produção.

Alterações na autenticação

A autenticação nos SDKs de servidor Python do OpenTok e do Vonage é gerenciada automaticamente para você; portanto, basta fornecer as credenciais da sua conta uma única vez, durante a inicialização. A diferença é que o OpenTok exige uma chave de API e um segredo, enquanto que, para o SDK Python da Vonage, você precisa fornecer um ID de aplicativo e sua chave privada. Embora tanto a Vonage quanto o OpenTok utilizem autenticação baseada em tokens, os tokens da Vonage são JWTs enquanto o OpenTok utiliza um formato personalizado. Embora seja possível fornecer uma chave de API e um segredo ao vonage.Client objeto — assim como no OpenTok —, isso é usado para outras APIs da Vonage, e não para vídeo. Portanto, você precisará criar ou usar um aplicativo da Vonage já existente.

Você pode criar um aplicativo a partir do Painel do Vonage. Certifique-se de que o recurso de vídeo esteja ativado no seu aplicativo. Clique em “Editar” em uma aplicação existente para visualizar seus recursos e credenciais. A partir daí, clique em “Gerar chave pública e privada”. Isso só deve ser feito uma vez, pois, a cada vez que você fizer isso, as credenciais serão alteradas, o que invalidará o par de chaves existente. Ao clicar aqui, será iniciado o download da sua chave privada. Você deve armazenar esse arquivo em um local seguro para fins de teste. NUNCA COMPARTILHE OU DIVULGUE SUA CHAVE PRIVADA!

A chave privada é, na verdade, a “senha” do seu aplicativo; portanto, deve ser tratada com cuidado. Recomenda-se que você armazene sua chave privada em um arquivo seguro. Use um pacote como dotenv para criar um .env arquivo e, em seguida, salve o caminho para o arquivo da sua chave privada como uma variável de ambiente, para que você possa consultá-lo ao configurar o cliente, nomeando a variável algo como VONAGE_PRIVATE_KEY_PATH. O mesmo deve ser feito com o ID do seu aplicativo (que pode ser encontrado no painel ou na URL ao editá-lo).

Para obter mais orientações sobre como configurar um aplicativo, consulte o guia de introdução.

Uso de modelos Pydantic

O SDK do Vonage para Python utiliza Modelos de dados do Pydantic para receber as opções do usuário e retornar dados da Video API. A maioria das solicitações à Video API exige um modelo Pydantic como entrada.

É possível acessar os modelos de dados da Video API — por exemplo, como argumentos para os métodos do pacote Video — importando-os do vonage_video.models pacote, por exemplo,

from vonage_video.models import SessionOptions

session_options = SessionOptions(...)

vonage_client.video.create_session(session_options)

Uso

Instantiação de um cliente

Veja O arquivo README do SDK do Python para obter instruções sobre como usar este SDK.

Substituir as referências a opentok.Client e opentok.OpenTok com o Video classe acessada por meio de vonage.Vonage.video.

Em vez disso, com o OpenTok:

client = opentok.Client(api_key, api_secret)

Faça o seguinte:

from vonage import Auth, Vonage

client = Vonage(Auth(
		application_id='VONAGE_APPLICATION_ID',
		private_key='VONAGE_PRIVATE_KEY_PATH',
	)
)

Assim que você tiver acesso a um vonage.Vonage Por exemplo, você pode usar o Video API. Para chamar métodos relacionados à Video API, use esta sintaxe:

vonage.Vonage.video.video_api_method(...)

Para obter instruções de uso mais detalhadas, consulte o Guia em vídeo do SDK do servidor Python.

Diferenças entre os métodos dos SDKs da OpenTok e da Vonage

Há algumas alterações nos métodos entre o OpenTok O SDK e a implementação da Video API no Vonage SDKs.

  • Quaisquer parâmetros posicionais nas assinaturas de métodos em opentok foram substituídos por parâmetros do tipo chave-valor no vonage pacote.
  • Os métodos agora retornam a resposta como um dicionário do Python.
  • Alguns métodos foram renomeados, para maior clareza e/ou para refletir melhor a função do método. Eles estão listados a seguir:
Nome do método do OpenTok Nome do método de vídeo da Vonage
opentok.generate_token video.generate_client_token
opentok.add_archive_stream video.add_stream_to_archive
opentok.remove_archive_stream video.remove_stream_from_archive
opentok.set_archive_layout video.change_archive_layout
opentok.add_broadcast_stream video.add_stream_to_broadcast
opentok.remove_broadcast_stream video.remove_stream_from_broadcast
opentok.set_broadcast_layout video.change_broadcast_layout
opentok.set_stream_class_lists video.change_stream_layout
opentok.force_disconnect video.disconnect_client
opentok.mute_all video.mute_all_streams
opentok.disable_force_mute video.disable_mute_all_streams
opentok.dial video.initiate_sip_call
opentok.start_render video.start_experience_composer
opentok.list_renders video.list_experience_composers
opentok.get_render video.get_experience_composer
opentok.stop_render video.stop_experience_composer
opentok.connect_audio_to_websocket video.start_audio_connector

Estratégias de migração

Migração incremental

Recomendamos uma migração gradual, passando de um caso de uso para outro e confirmando as alterações sempre que chegar a um estado “estável”. Observe que essa abordagem exigiria a coexistência temporária da API do OpenTok e da Video API da Vonage.

Observe que, durante esse processo gradual, seu aplicativo como um todo não estará mais totalmente funcional, uma vez que o OpenTok e a Video API da Vonage são dois sistemas totalmente diferentes.

Você deve começar criando um “Adaptador de Vídeo” específico que agrupe todas as interações atuais com o OpenTok e, em seguida, substituir, uma a uma, as chamadas ao OpenTok pela Video API da Vonage.

Outra abordagem poderia ser duplicar esse “Adaptador de Vídeo” para criar um novo “Adaptador de Vídeo Vonage”, dedicado a essa migração, antes de trocar esses dois adaptadores entre si. Saiba mais com o Padrão da figueira-estranguladora.

Recomendações para testes

Testes completos são essenciais para uma transição tranquila, tanto durante quanto após a migração. Isso inclui não apenas testes unitários, mas também testes de integração e de regressão. Também vale a pena testar manualmente o fluxo da sua aplicação pelo menos uma vez antes e depois da migração para garantir que seus testes automatizados funcionem conforme o esperado, ou para identificar quaisquer problemas que os testes possam não ter detectado. Você pode até mesmo considerar a criação de testes de equivalência.

A ideia é criar um conjunto de testes que comprove que tanto a versão OpenTok quanto a versão Vonage Video do seu aplicativo realizam as mesmas funções. Esses testes poderão ser descartados assim que a transição estiver concluída e a versão OpenTok do seu aplicativo for removida.

Solução de problemas e suporte

O SDK do servidor Python da Vonage se esforça para fornecer mensagens de exceção úteis nos rastreamentos de pilha, caso você encontre erros de tempo de execução. Analise-as cuidadosamente para determinar a causa.

Canais de suporte

Para obter ajuda geral e participar de discussões sobre a migração para o Vonage Video, confira o Canal #Video API no nosso Slack da Comunidade, onde você pode obter respostas da equipe da Vonage e de outros usuários. Você também pode entrar em contato conosco no X @VonageDev.

O principal ponto de contato para quaisquer questões relacionadas à própria Video API é support@api.vonage.com. Se você encontrar um bug no SDK, por favor, abrir um ticket no GitHub com os passos para reproduzir o problema.