Serviços da Web com Ruby - SOAP4R

O que é SOAP?

O Simple Object Access Protocol (SOAP) é um protocolo RPC de plataforma cruzada e independente de linguagem baseado em XML e, geralmente (mas não necessariamente) HTTP.

Ele usa XML para codificar as informações que fazem a chamada de procedimento remoto e HTTP para transportar essas informações através de uma rede de clientes para servidores e vice-versa.

SOAP tem várias vantagens sobre outras tecnologias como COM, CORBA etc: por exemplo, sua implantação relativamente barata e custos de depuração, sua extensibilidade e facilidade de uso, e a existência de várias implementações para diferentes linguagens e plataformas.

Consulte nosso tutorial SOAP simples para entendê-lo em detalhes.

Este capítulo o familiariza com a implementação SOAP para Ruby (SOAP4R). Este é um tutorial básico, portanto, se você precisar de detalhes profundos, deverá consultar outros recursos.

Instalando SOAP4R

SOAP4R é a implementação SOAP para Ruby desenvolvida por Hiroshi Nakamura e pode ser baixado de -

NOTE - Pode haver uma grande chance de você já ter instalado este componente.

Download SOAP

Se você está ciente de gem utilitário então você pode usar o seguinte comando para instalar SOAP4R e pacotes relacionados.

$ gem install soap4r --include-dependencies

Se você estiver trabalhando no Windows, precisará baixar um arquivo compactado do local acima e instalá-lo usando o método de instalação padrão executando ruby install.rb .

Escrevendo servidores SOAP4R

SOAP4R suporta dois tipos diferentes de servidores -

Baseado em CGI / FastCGI (SOAP :: RPC :: CGIStub)
Independente (SOAP :: RPC: StandaloneServer)

Este capítulo fornece detalhes sobre como escrever um servidor autônomo. As etapas a seguir estão envolvidas na gravação de um servidor SOAP.

Etapa 1 - Herdar a classe SOAP :: RPC :: StandaloneServer

Para implementar seu próprio servidor autônomo, você precisa escrever uma nova classe, que será filha de SOAP :: StandaloneServer da seguinte forma -

class MyServer < SOAP::RPC::StandaloneServer
  ...............
end

NOTE- Se você deseja escrever um servidor baseado em FastCGI, então você precisa tomar SOAP :: RPC :: CGIStub como classe pai, o resto do procedimento permanecerá o mesmo.

Etapa 2 - Definir Métodos de Manipulação

A segunda etapa é escrever seus métodos de Web Services, que você gostaria de expor ao mundo exterior.

Eles podem ser escritos como métodos simples de Ruby. Por exemplo, vamos escrever dois métodos para adicionar dois números e dividir dois números -

class MyServer < SOAP::RPC::StandaloneServer
   ...............

   # Handler methods
   def add(a, b)
      return a + b
   end
   def div(a, b) 
      return a / b 
   end
end

Etapa 3 - Expor métodos de manipulador

O próximo passo é adicionar nossos métodos definidos ao nosso servidor. O método de inicialização é usado para expor métodos de serviço com um dos dois métodos a seguir -

class MyServer < SOAP::RPC::StandaloneServer
   def initialize(*args)
      add_method(receiver, methodName, *paramArg)
   end
end

Aqui está a descrição dos parâmetros -

Sr. Não.	Parâmetro e Descrição
1	receiver O objeto que contém o método methodName. Você define os métodos de serviço na mesma classe do método methodDef, este parâmetro é self .
2	methodName O nome do método que é chamado devido a uma solicitação RPC.
3	paramArg Especifica, quando fornecidos, os nomes e modos dos parâmetros.

Para entender o uso dos parâmetros inout ou out , considere o seguinte método de serviço que usa dois parâmetros (inParam e inoutParam), retorna um valor de retorno normal (retVal) e dois parâmetros adicionais: inoutParam e outParam -

def aMeth(inParam, inoutParam)
   retVal = inParam + inoutParam
   outParam = inParam . inoutParam
   inoutParam = inParam * inoutParam
   return retVal, inoutParam, outParam
end

Agora, podemos expor esse método da seguinte maneira -

add_method(self, 'aMeth', [
   %w(in inParam),
   %w(inout inoutParam),
   %w(out outParam),
   %w(retval return)
])

Etapa 4 - iniciar o servidor

A etapa final é iniciar seu servidor instanciando uma instância da classe derivada e chamando start método.

myServer = MyServer.new('ServerName', 'urn:ruby:ServiceName', hostname, port)

myServer.start

Aqui está a descrição dos parâmetros necessários -

Sr. Não.	Parâmetro e Descrição
1	ServerName Um nome de servidor, você pode dar o que você mais gosta.
2	urn:ruby:ServiceName Aqui urn: ruby é constante, mas você pode fornecer um nome ServiceName exclusivo para este servidor.
3	hostname Especifica o nome do host no qual este servidor ouvirá.
4	port Um número de porta disponível para ser usado para o serviço da web.

Exemplo

Agora, usando as etapas acima, vamos escrever um servidor autônomo -

require "soap/rpc/standaloneserver"

begin
   class MyServer < SOAP::RPC::StandaloneServer

      # Expose our services
      def initialize(*args)
         add_method(self, 'add', 'a', 'b')
         add_method(self, 'div', 'a', 'b')
      end

      # Handler methods
      def add(a, b)
         return a + b
      end
      def div(a, b) 
         return a / b 
      end
end
   server = MyServer.new("MyServer", 
            'urn:ruby:calculation', 'localhost', 8080)
   trap('INT){
      server.shutdown
   }
   server.start
rescue => err
   puts err.message
end

Quando executado, este aplicativo de servidor inicia um servidor SOAP independente no localhost e escuta as solicitações na porta 8080. Ele expõe um método de serviço, add e div , que leva dois parâmetros e retorna o resultado.

Agora, você pode executar este servidor em segundo plano da seguinte maneira -

$ ruby MyServer.rb&

Escrevendo clientes SOAP4R

A classe SOAP :: RPC :: Driver fornece suporte para escrever aplicativos cliente SOAP. Este capítulo descreve essa classe e demonstra seu uso com base em um aplicativo.

A seguir estão as informações mínimas de que você precisa para chamar um serviço SOAP -

A URL do serviço SOAP (URL do terminal SOAP).
O namespace dos métodos de serviço (URI do namespace do método).
Os nomes dos métodos de serviço e seus parâmetros.

Agora, escreveremos um cliente SOAP que chamaria métodos de serviço definidos no exemplo acima, chamados add e div .

Aqui estão as principais etapas para criar um cliente SOAP.

Etapa 1 - Criar uma instância do driver SOAP

Criamos uma instância de SOAP :: RPC :: Driver chamando seu novo método da seguinte maneira -

SOAP::RPC::Driver.new(endPoint, nameSpace, soapAction)

Aqui está a descrição dos parâmetros necessários -

Sr. Não.	Parâmetro e Descrição
1	endPoint URL do servidor SOAP ao qual se conectar.
2	nameSpace O namespace a ser usado para todos os RPCs feitos com este objeto SOAP :: RPC :: Driver.
3	soapAction Um valor para o campo SOAPAction do cabeçalho HTTP. Se nulo, o padrão é a string vazia "".

Etapa 2 - Adicionar métodos de serviço

Para adicionar um método de serviço SOAP a um SOAP :: RPC :: Driver , podemos chamar o seguinte método usando a instância SOAP :: RPC :: Driver -

driver.add_method(name, *paramArg)

Aqui está a descrição dos parâmetros -

Sr. Não.	Parâmetro e Descrição
1	name O nome do método de serviço da web remoto.
2	paramArg Especifica os nomes dos parâmetros dos procedimentos remotos.

Etapa 3 - invocar o serviço SOAP

A etapa final é faturar o serviço SOAP usando a instância SOAP :: RPC :: Driver da seguinte maneira -

result = driver.serviceMethod(paramArg...)

Aqui, serviceMethod é o método de serviço da web real e paramArg ... são os parâmetros de lista necessários para passar o método de serviço.

Example

Com base nas etapas acima, escreveremos um cliente SOAP da seguinte forma -

#!/usr/bin/ruby -w

require 'soap/rpc/driver'

NAMESPACE = 'urn:ruby:calculation'
URL = 'http://localhost:8080/'

begin
   driver = SOAP::RPC::Driver.new(URL, NAMESPACE)
   
   # Add remote sevice methods
   driver.add_method('add', 'a', 'b')

   # Call remote service methods
   puts driver.add(20, 30)
rescue => err
   puts err.message
end

Leituras adicionais

Eu expliquei a você apenas os conceitos básicos de Web Services com Ruby. Se você quiser se aprofundar ainda mais, há o seguinte link para encontrar mais detalhes sobre Web Services com Ruby .