Guia de transição do Vonage Video para Ruby

A transição de OpenTok-Ruby-SDK para vonage-ruby-sdk

Introdução

Objetivo

O objetivo deste documento é servir como ponto de partida para a transição do SDK do servidor OpenTok para Ruby para o SDK do servidor Vonage para Ruby.

Âmbito

Este documento pressupõe que você esteja usando, no mínimo, a versão 4.9.0 ou posterior do SDK do OpenTok para Ruby. Uma implementação inicial da Video API foi adicionada ao SDK do servidor Ruby em versão 7.19.0, com recursos adicionais implementados em versão 7.24.0. No entanto, para a sua migração, recomendamos usar o mais recente versão do SDK do Vonage Ruby, que pode ser encontrada em GitHub ou RubyGems.

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 Ruby, nas ferramentas comuns de desenvolvimento em Ruby e no Git (ou outro sistema de controle de versão). Você deve estar à vontade para ler e escrever código em Ruby, gerenciar dependências de projetos, além de implantar e executar um projeto em Ruby. Uma introdução à linguagem Ruby, à plataforma e às ferramentas associadas está bem 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

• Documentação do Vonage Video
• Especificação da Video API da Vonage
• Guia de uso em vídeo do SDK do Vonage Ruby Server
• Rubydocs do SDK do Servidor Ruby da Vonage
• Código-fonte do vídeo do SDK do Vonage Ruby Server
• Repositório do GitHub do SDK do Vonage Ruby Server
• Artefatos do SDK do Vonage Ruby Server publicados no RubyGems

TokBox

• Referência da API REST do OpenTok
• Documentação do SDK do servidor OpenTok para Ruby
• Código-fonte do SDK do servidor OpenTok para Ruby
• Repositório do OpenTok Ruby Server SDK no GitHub
• Artefatos do SDK do servidor OpenTok para Ruby publicados no RubyGems

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

Para avaliar o impacto da migração em suas aplicações, há algumas questões que você precisará levar em consideração.

1. Quanto do código do seu aplicativo depende do SDK do OpenTok? Faça uma lista de todos os arquivos nos quais o SDK é usado diretamente. Uma maneira de determinar isso seria identificar quaisquer .rb arquivo que contém um require 'opentok' referência. Por exemplo, você pode procurar nos arquivos do seu projeto pela instrução require 'opentok' usando um editor de código, um IDE ou uma ferramenta de linha de comando para identificar os arquivos afetados.

2. Quantos Quais recursos do SDK do OpenTok seu aplicativo utiliza? Por exemplo, um aplicativo que utilize o SDK exclusivamente para criar sessões de vídeo e gerar tokens de cliente provavelmente será mais simples de migrar do que um que também utilize recursos como arquivamento, transmissão, moderação e outros.

3. Qual Quais recursos do SDK do OpenTok seu aplicativo utiliza? Alguns recursos podem exigir mais esforço para serem migrados do que outros. Consulte o Seção “Principais alterações e considerações” para obter detalhes sobre as alterações entre a implementação dos dois SDKs.

4. Como fortemente acoplado O código da sua aplicação utiliza o SDK do OpenTok? No contexto de uma aplicação Ruby on Rails, por exemplo, você está chamando métodos do SDK diretamente nas ações do seu controlador, ou já abstraiu essas chamadas de método de alguma forma (por exemplo, usando o Padrão Gateway ou o Padrão Adaptador)?

Também pode haver outras considerações relacionadas ao seu projeto específico que não estejam listadas acima.

Linha do tempo

Leve em consideração o tempo necessário para concluir a transição. Isso dependerá de vários fatores, como sua familiaridade com o projeto e o impacto da migração do projeto (conforme descrito acima). É fundamental contar com um bom conjunto de testes para que você possa verificar a equivalência entre as implementações do OpenTok e do Vonage Video. O tempo necessário para concluir a transição é aproximadamente proporcional ao número de locais em que o SDK do OpenTok é utilizado em seu código, bem como à variedade de recursos utilizados; porém, conforme mencionado anteriormente, 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 branch temporário 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 prejudicar o projeto existente. Você também pode usar os testes do projeto existente como referência para verificar a correção. O ideal é só mesclar o branch de transição ao branch principal depois de concluir a conversão.

Principais mudanças e considerações

A Video API da Vonage possui paridade de recursos com a OpenTok, e o SDK em Ruby é mantido ativamente para estar em conformidade com a especificação da API. No entanto, existem algumas diferenças entre os dois SDKs que você deve conhecer.

Novos recursos e normas

Estrutura do pacote

Tanto o SDK do OpenTok para Ruby quanto o SDK da Vonage para Ruby seguem o abordagem para estruturar gems do Ruby recomendada pelo Bundler, e, portanto, em um nível geral, são semelhantes em termos de estrutura. Há, no entanto, algumas diferenças importantes:

1. O SDK do Vonage Ruby utiliza o zeitwerk biblioteca para carregamento automático de código e, portanto, segue as convenções do zeitwerk quanto à estrutura de arquivos e diretórios e à nomenclatura. Se você sabe como as aplicações Ruby on Rails são estruturadas, então já está familiarizado com essas convenções. Caso contrário, talvez valha a pena dedicar alguns minutos familiarizar-se com eles. Considerando essa estrutura em termos da implementação da Video API:

• A principal Video A classe está definida em este arquivo
• Quaisquer classes que estejam no namespace Video (como, por exemplo, Video::Broadcasts e Video::Archives) estão definidos em este diretório.

2. O SDK do Ruby da Vonage implementa outras APIs da Vonage, além da Video API. O SDK implementa classes que representam cada um desses produtos de API, e o Client A classe fornece acessadores para objetos dessas classes.

Tendo em conta os pontos 1 e 2 acima, a partir da Vonage Client Pode ser necessário chamar um ou mais métodos adicionais antes de chegar ao método que representa o endpoint específico da Video API que você deseja chamar.

Exemplo 1: Criação de uma sessão

O uso do SDK do OpenTok para Ruby pode ser mais ou menos assim:

# 1: instantiate an `OpenTok` object (assuming credentials stored as environment variables)
opentok = OpenTok::OpenTok.new(
  ENV['OPENTOK_API_KEY'],
  ENV['OPENTOK_API_SECRET']
)

# 2: invoke the `create_session` method on the `OpenTok` object
session = opentok.create_session

Já o uso do SDK Ruby da Vonage pode ser algo parecido com isto:

# 1: instantiate a Vonage `Client` object (assuming credentials stored as environment variables)
client = Vonage::Client.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)

# 2: access the `Video` object
video = client.video

# 3: invoke the `create_session` method on the `Video` object
session = video.create_session

Como seria de se esperar no Ruby, é possível combinar as etapas 2 e 3 por meio do encadeamento de métodos:

session = client.video.create_session

Exemplo 2: Obter uma lista de gravações arquivadas

O uso do SDK do OpenTok para Ruby pode ser mais ou menos assim:

# 1: instantiate an `OpenTok` object
opentok = OpenTok::OpenTok.new(
  ENV['OPENTOK_API_KEY'],
  ENV['OPENTOK_API_SECRET']
)

# 2: access the `Archives` object
archives = opentok.archives

# 3: invoke the `all` method on the `Archives` object
archive_list = archives.all

Já o uso do SDK Ruby da Vonage pode ser algo parecido com isto:

# 1: instantiate a Vonage `Client` object
client = Vonage::Client.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)

# 2: access the `Video` object
video = client.video

# 3: access the `Archives` object
archives = video.archives

# 4: invoke the `list` method on the `Archives` object
archive_list = archives.list

Mais uma vez, as etapas podem ser combinadas por meio do encadeamento de métodos:

archive_list = client.video.archives.list

Uma observação sobre a digitação

O SDK do Vonage Ruby utiliza Sorvete para verificação de tipos estática. A fim de simplificar a migração do SDK Ruby do OpenTok para o SDK Ruby da Vonage, ainda não foram definidas assinaturas de tipos para nenhum dos métodos da implementação da Video API. As assinaturas de tipos serão definidas para esses métodos em uma versão futura.

Uma observação sobre as alterações no front-end

As bibliotecas de front-end utilizadas em seu aplicativo serão as mesmas que as bibliotecas do OpenTok. Há, no entanto, uma pequena mudança em relação ao seu uso.

A interação entre o back-end e o front-end será a mesma: o SDK criará sessões e também gerará tokens para que as bibliotecas de cliente do front-end tenham acesso a essas sessões. Assim como em uma implementação do OpenTok, as bibliotecas de cliente do front-end esperarão que o servidor de back-end forneça um ID da sessão e um token. No entanto, com uma implementação da Vonage, o servidor também precisará fornecer um ID do aplicativo. Esse ID de aplicativo substitui efetivamente o Chave da API que seriam utilizadas em uma implementação do OpenTok, embora as bibliotecas do cliente front-end ainda rótulo utilize-a como uma chave de API. Para obter mais informações sobre IDs de aplicativo, consulte a seção sobre Alterações na autenticação.

Essa pequena mudança na interação entre o front-end e o back-end pode exigir algumas pequenas atualizações na sua implementação, por exemplo, nos seus modelos de visualização ou na lógica que passa dados para esses modelos.

Atualização do pacote

Para usar o SDK do Vonage Ruby, você precisará atualizar as dependências do seu projeto para usar o vonage Gem do Ruby em vez do opentok Gem do Ruby. Você pode fazer isso atualizando seu Gemfile para incluir o vonage gem:

gem "vonage"

e, em seguida, executar bundle install.

Alterações na autenticação

Considerando que o opentok O gem usa um api_key e api_secret Para autorização, a implementação da Video API no vonage O gem utiliza um JWT. O SDK cuida da geração do JWT em segundo plano para você, mas exigirá um application_id e private_key como credenciais para gerar o token. Você pode obtê-las configurando um aplicativo da Vonage e gerando um ID de aplicativo e uma chave privada para esse aplicativo. O aplicativo da Vonage também permite definir outras configurações, como os produtos de API para os quais o aplicativo está habilitado, URLs de retorno de chamada, preferências de armazenamento etc.

Existem várias maneiras de criar uma aplicação da Vonage:

• Por meio do Painel do desenvolvedor
• Por meio do API do aplicativo
• Ao usar o CLI da Vonage

Seu application_id e private_key As credenciais são, então, passadas ao instanciar um Client objeto (o exemplo abaixo pressupõe que você tenha definido essas variáveis de ambiente):

client = Vonage::Client.new(
	application_id: ENV['VONAGE_APPLICATION_ID'],
	private_key: ENV['VONAGE_PRIVATE_KEY']
)

Se suas variáveis de ambiente tiverem os nomes indicados no exemplo acima, você pode, na verdade, omitir os argumentos do new chamada de método. O SDK irá procurar automaticamente o ENV procura por variáveis com esses nomes e usa seus valores, caso os encontre. Nesse caso, o exemplo a seguir de instanciação de um Vonage::Client O objeto é funcionalmente equivalente ao anterior:

client = Vonage::Client.new

Observe que o valor para o VONAGE_PRIVATE_KEY pode ser o caminho para o local onde está o seu private.key arquivo. A forma de determinar o valor desse caminho dependerá de como você estiver implantando seu aplicativo. Se estiver implantando seu aplicativo localmente, você pode armazenar seu private.key arquivo na raiz do seu projeto e defina o caminho como private.key. Por exemplo, se estiver usando dotenv Para gerenciar suas variáveis de ambiente, você deve VONAGE_PRIVATE_KEY definição no seu .env O arquivo ficaria assim:

VONAGE_PRIVATE_KEY=private.key

Se estiver fazendo a implantação em produção usando um serviço como Renderizar, esses tipos de serviços geralmente oferecem formas de armazenar arquivos com segurança, como chaves privadas. O método exato para fazer isso dependerá do serviço utilizado e está fora do escopo deste documento.

Alterações no método

Existem algumas diferenças nos métodos entre o SDK do OpenTok para Ruby e a implementação da Video API no SDK da Vonage para Ruby.

Parâmetros do método

Todos os parâmetros posicionais nas assinaturas de métodos foram substituídos por parâmetros de palavra-chave no SDK da Vonage.

Alterações nos nomes dos métodos

Alguns métodos foram renomeados e/ou movidos, para maior clareza e/ou para refletir melhor a função do método. Eles estão listados a seguir:

Objetos de resposta

Ao contrário do SDK do OpenTok para Ruby, o SDK da Vonage para Ruby não utiliza classes de objetos específicas ao deserializar a carga JSON de uma resposta HTTP, mas sim deserializa as respostas em objetos de resposta genéricos.

Objetos de resposta de recurso único

As respostas em que a carga JSON representa um único recurso são desserializadas pelo SDK Ruby da Vonage para um Vonage::Response objeto.

De maneira geral, você pode usar isso Vonage::Response objeto da mesma forma que você faria com o OpenTok::Archive, OpenTok::Broadcast, OpenTok::Stream, etc., objetos nos quais é possível acessar propriedades da carga útil da resposta chamando métodos no objeto com nomes equivalentes aos nomes das propriedades. Por exemplo, se você quisesse iniciar uma nova gravação em arquivo e obter seu ID a partir da resposta, a abordagem para fazer isso seria, em linhas gerais, semelhante para os dois SDKs.

Exemplo: SDK do OpenTok para Ruby

opentok = OpenTok::OpenTok.new(
  ENV['OPENTOK_API_KEY'],
  ENV['OPENTOK_API_SECRET']
)
session = opentok.create_session
archive = opentok.archives.create(session.session_id) # => returns a OpenTok::Archive object

# calling the `id` method on the object returns the value of the `id` property in the JSON payload
archive.id

Exemplo: SDK do Vonage Ruby

client = Vonage::Client.new.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)
session = client.video.create_session
archive = client.video.archives.start(session_id: session.session_id) # => returns a Vonage::Response object

# calling the `id` method on the object returns the value of the `id` property in the JSON payload
archive.id

Uma diferença fundamental na implementação dos objetos de resposta entre os dois SDKs está no uso do padrão fachada nos objetos de resposta do SDK Ruby da OpenTok. Os objetos de resposta do SDK da OpenTok são inicializados com uma referência ao objeto que invocou o método que os criou. Esse objeto, por sua vez, contém uma referência a um OpenTok::Client objeto. Isso significa que você pode invocar métodos que interagem com alguns dos endpoints da Video API diretamente nesses objetos. Os objetos de resposta no SDK Ruby da Vonage não oferecem uma maneira direta de chamar métodos que encapsulam endpoints da Video API; portanto, você precisará usar objetos que representem a classe de recurso específica como chamador do método.

Digamos, por exemplo, que você queira interromper uma gravação de arquivo que está em andamento no momento.

Exemplo: SDK do OpenTok para Ruby

No SDK do OpenTok, você pode chamar o stop método diretamente no Archive objeto retornado pelo Archives#create chamada de método.

opentok = OpenTok::OpenTok.new(
  ENV['OPENTOK_API_KEY'],
  ENV['OPENTOK_API_SECRET']
)
session = opentok.create_session
archives = opentok.archives
archive_1 = archives.create(session.session_id) # => returns a OpenTok::Archive object

# calling the `stop` method directly on the returned OpenTok::Archive object stops the archive recording
archive_1.stop

Exemplo: SDK do Vonage Ruby

No SDK da Vonage, você precisaria chamar o stop método em um Video::Archives objeto e passar os parâmetros relevantes archive_id como argumento.

client = Vonage::Client.new.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)
session = client.video.create_session
archives = client.video.archives
archive_1 = archives.start(session_id: session.session_id) # => returns a Vonage::Response object

# calling the `stop` method on a Video::Archives object, passing in the `id` of the archive you want to stop
archives.stop(archive_id: archive_1.id)

Objetos de Resposta com Múltiplos Recursos

As respostas em que a carga JSON representa uma coleção de um ou mais recursos são desserializadas pelo SDK Ruby da Vonage para um ListResponse nomes de objetos no namespace “product” e, em seguida, o tipo de objeto que fez a solicitação, por exemplo Vonage::Video::Broadcasts::ListResponse.

Essencialmente, eles oferecem a mesma funcionalidade que os tipos de objeto de resposta de lista do SDK do OpenTok para Ruby, na medida em que são coleções iteráveis de objetos de recurso individuais. A implementação difere ligeiramente entre os SDKs, mas, em geral, isso não deve afetar a maneira como você interage com esses objetos; essa diferença é descrita a seguir mais por uma questão de completude:

• O ListResponse os objetos no SDK Ruby da Vonage implementam um each método e incluir o Ruby's Enumerable módulo.
• As respostas do tipo lista no SDK do OpenTok para Ruby (por exemplo, ArchiveList, BroadcastList, etc.) subclasse da Ruby's Array classe.

Objetos de resposta a erros

Ambos os SDKs definem uma classe genérica de erros que é uma subclasse da classe do Ruby StandardError classe, com classes de erro mais específicas que são subclasses dessa classe genérica.

O SDK do OpenTok para Ruby define um OpenTok::OpenTokError classe e, em seguida, classes de erro específicas por tipo de recurso que são subclasses de OpenTokError, tais como OpenTokArchiveError, OpenTokBroadcastError, OpenTokAuthenticationError, etc. Nenhum desses tipos de erro implementa qualquer funcionalidade adicional além daquela que StandardError prevê.

O SDK do Vonage Ruby define um Vonage::Error classe e também um Vonage::APIError classe que é uma subclasse de Vonage::Error. O APIError A classe representa erros resultantes de uma solicitação HTTP a um endpoint da API da Vonage. O SDK define, então, várias classes de erro mais específicas, de acordo com a natureza da resposta recebida, que são subclasses de APIError. Essas aulas incluem Vonage::ClientError (para 4xx respostas), Vonage::ServerError (para 5xx respostas), e Vonage::AuthenticationError (que é uma subclasse de Vonage::ClientError, e é usado especificamente para 401 respostas).

O APIError A classe implementa uma lógica adicional que fornece métodos getter para o Net:HTTPResponse objeto, bem como o código de resposta, os cabeçalhos e o corpo. É possível capturar a exceção para acessar essas propriedades.

Exemplo

client = Vonage::Client.new.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: ENV['VONAGE_PRIVATE_KEY']
)

begin
  session = client.video.create_session
rescue Vonage::APIError => error
  if error.http_response
    error.http_response # => #<Net::HTTPUnauthorized 401 Unauthorized readbody=true>
    error.http_response_code # => "401"
    error.http_response_headers # => {"date"=>["Sun, 24 Sep 2023 11:08:47 GMT"], ...rest of headers}
    error.http_response_body # => {"title"=>"Unauthorized", ...rest of body}
  end
end

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 se atingir um estado “estável”. É claro que isso 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.

O plano exato para uma abordagem incremental dependerá de quantos e quais recursos da Video API você está utilizando e de como integrou esses recursos ao seu aplicativo. Embora não seja possível fornecer orientações específicas para a implementação nessa área, em termos de abordagem geral, um plano possível é atualizar seu código recurso por recurso e, dentro de cada recurso, método por método.

Um bom ponto de partida seria qualquer código que instancie um OpenTok::OpenTok objeto e substitua isso pelo código que instancia um Vonage::Client objeto, após a comparação entre os dois demonstrada no Estrutura do pacote seção.

O próximo passo poderia ser atualizar qualquer código relacionado à criação de sessões, à geração de tokens de cliente e ao envio de dados para as bibliotecas do cliente front-end.

Em seguida, você poderia atualizar, um por um, qualquer código que implemente recursos específicos da Video API. Tomando o Archives como exemplo:

• Identifique qualquer código em que Archives são criados ou com os quais se interage.
• Atualize as chamadas aos métodos para que eles sejam chamados em client.video em vez de opentok objetos.
• Atualize os nomes dos métodos que mudaram.
• Se uma chamada de método passar algum argumento, atualize-a para usar os parâmetros-chave corretos.
• Identifique qualquer código em que um método seja chamado diretamente em um Archive objeto de resposta e altere-o conforme descrito no Objetos de resposta seção.

Repita esse processo para cada recurso e método.

Pode ser que você precise realizar algumas etapas adicionais, como atualizar qualquer código em que você erros específicos do resgate. A lista de etapas acima não é exaustiva, mas esperamos que sirva como um bom ponto de partida para definir seu plano de migração.

Padrão Gateway/Adaptador

Se você ainda não estiver utilizando algum tipo de padrão de gateway ou adaptador como parte de sua implementação, essa migração seria uma boa oportunidade para fazê-lo. Isso não só ajudaria a facilitar a migração, mas também significaria que, no uso geral, o código do seu aplicativo estaria menos acoplado ao código do SDK.

Existem muitas abordagens diferentes para implementar esses padrões, dependendo de como sua aplicação está estruturada e/ou da estrutura de trabalho que você está utilizando. Está além do escopo deste documento fornecer orientações específicas nessa área.

Recomendações para testes

Testes minuciosos são essenciais para uma transição tranquila, tanto durante quanto após a migração. Isso inclui não apenas testes de unidade, mas também testes de integração e de regressão. Também vale a pena testar manualmente o fluxo do seu aplicativo pelo menos uma vez antes e depois da migração para garantir que seus testes automatizados funcionem como esperado ou para identificar quaisquer problemas que os testes possam não ter detectado. Você pode até 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 funcionam da mesma maneira. Esses testes podem 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

Canais de suporte

Para obter ajuda geral e participar de discussões sobre a migração para o Vonage Video, acesse 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 pelo 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, com os passos para reproduzir o problema, no GitHub.

Recursos adicionais

Exemplos de código

• Videochamada básica com vários participantes usando o Sinatra