cliente soap

Home > Cliente SOAP

Cliente SOAP

Important

Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.

Nível: iniciante

Em uma frase: o TRALSOAPClient chama serviços SOAP 1.1 e 1.2 - do RAL ou de qualquer outro (.NET, WCF, Java) - a partir do WSDL, sem escrever o envelope.

Você vai precisar: RAL 2.0 com os pacotes RALModuleXMLPackage e RALModuleSOAPPackage (Instalação).

Quando usar o TRALClient e quando o TRALSOAPClient

O TRALSOAPClient é um TRALClient: herda motores (EngineType), BaseURL com failover, TLS e pins, pool de conexões, autenticação e compressão. Use-o para serviços SOAP; para REST continue com o TRALClient. Nada mudou no TRALClient.

Na IDE, sem código

1. Coloque um TRALSOAPClient (paleta RAL - Client) e escolha o EngineType, como no cliente.
2. Clique com o botão direito no componente e escolha Importar WSDL.... Informe o endereço (http://servidor/calc?wsdl) ou um arquivo. O cliente preenche Operations, Namespace, BaseURL e ServicePath.
3. Em Operations, cada operação tem Params (os valores de entrada, com tipo) e Results (os de saída). Preencha o Value dos Params no Object Inspector, se quiser valores fixos.
4. Para chamar sem código: coloque um TActionList, acrescente a ação TRALSOAPExecute (categoria RAL), aponte Client e Operation e ligue um botão à ação.
5. Se a resposta traz um dataset, ligue ResultDataSet da operação a um memtable do formulário: ele é carregado a cada resposta.

Chamando em código

with RALSOAPClient1.Operations['Somar'] do
begin
  Params['a'].Value := '2';
  Params['b'].Value := '3';
  if Execute then
    ShowMessage(Results.ValueOf('SomarResult'));
end;

Execute devolve True quando a resposta chegou e preencheu Results (e o ResultDataSet). Response guarda o envelope da última resposta, para ler o que Results não mostra:

Doc := RALSOAPClient1.Operations['Somar'].Response;
Total := Doc.GetText('/Envelope/Body/SomarResponse/SomarResult');

Um parâmetro opcional com Value vazio não é enviado; um obrigatório (Required) vai mesmo vazio.

Em thread

Execute(ebMultiThread) volta na hora; a resposta chega depois, na thread principal, em Results, ResultDataSet e nos eventos. A ação TRALSOAPExecute tem ExecBehavior para o mesmo.

Envelope montado por você

Doc := RALSOAPClient1.CallXML('Somar', '<Somar xmlns="urn:calc"><a>7</a><b>8</b></Somar>');
try
  ShowMessage(Doc.GetText('/Envelope/Body/SomarResponse/SomarResult'));
finally
  Doc.Free;
end;

Call(operacao, no) faz o mesmo com um nó montado pela API do XML.

Falhas

Uma Fault do serviço chega em OnFault (da operação ou do cliente) com Code, CodeText, Reason, Detail e HTTPStatus. Sem nenhum evento, Execute levanta ERALSOAPFault:

try
  RALSOAPClient1.Execute('Somar');
except
  on E: ERALSOAPFault do
    ShowMessage(E.CodeText + ': ' + E.Reason);
end;

Em thread não há para quem levantar: sem evento, o motivo fica em LastError da operação. Uma falha de rede (servidor fora do ar) também chega como ERALSOAPFault, com código Receiver.

Propriedades

Propriedade	O que faz
Version	sv11 (padrão) ou sv12
WSDL	endereço ou arquivo que Importar WSDL lê
Namespace	namespace do serviço
ServicePath	caminho do serviço abaixo de BaseURL
EnvelopeContentType	troca o Content-Type dos envelopes (padrão: o da versão)
Operations	as operações
OnFault, OnSOAPResponse	eventos de todas as operações sem evento próprio
CompressType	ctNone no SOAP: servidores SOAP quase nunca leem um pedido comprimido. A resposta comprimida continua aceita

Cada operação: Name, Namespace, SOAPAction, Style (document ou rpc), Params, Results, ResultDataSet, OnFault, OnResponse, LastError e Response.

O que o Importar WSDL entende

WSDL 1.1 com binding SOAP 1.1 ou 1.2 (escolhe o da Version do cliente), document/literal (wrapped) e rpc/literal, tipos inline, xs:import, xs:include e wsdl:import com schemaLocation/location (é o ?wsdl do WCF e do JAX-WS), elementos com tipo nomeado, ref e complexContent/extension. Um valor complexo vira um parâmetro prtXML, cujo Value é o fragmento XML. SOAP encoded (rpc/encoded) e WSDL 2.0 não são lidos.

Em código (console)

uses RALSOAPTypes, RALSOAPClient, RALIndyClient;

Cliente := TRALSOAPClient.Create(nil);
Cliente.EngineType := 'Indy';
Cliente.ImportWSDL('http://localhost:8000/calc?wsdl');
Cliente.Operations['Somar'].Params['a'].Value := '2';
Cliente.Operations['Somar'].Params['b'].Value := '3';
Cliente.Execute('Somar');
Writeln(Cliente.Operations['Somar'].Results.ValueOf('SomarResult'));

Veja também

• Servidor SOAP
• O cliente
• XML