WebServices - Aplicaes Cliente

Aplicaes Protheus 'Client' de WebServices

Reviso: 30/04/2004

Abrangncia Verso 7.10 Verso 8.11

Definio de Client Quando um Web Service 'Server' criado e disponibilizado, junto dele tambm disponibilizada a definio do servio, seus argumentos, estruturas e retornos (WSDL) . Para a utilizao de um Web Service, necessrio montar um programa client, que seja capaz de montar um envelope SOAP com os dados necessrios ao processamento do Servio, realizar a chamada, e tratar o pacote de retorno do servio e suas respectivas excesses. Embora existam Web Services que podem ser acessados via Http direto, apenas passando parmetros via URL, o client de Web Services do Protheus tm seu foco e recursos direcionados apenas a servios que possuam interface de comunicao que realize POST de pacotes de dados XML em formato SOAP. O Protheus possui ferramentas e infra-estrutura incorporadas que permitem esta integrao. Gerao do Client em Advpl Utilizando o IDE, encontra-se disponvel, no menu 'Ferramentas', a opo para que, atravs de um link para a obteno do documento WSDL de um servio, o Protheus gere automaticamente, em Advpl, uma classe 'Client' para a comunicao e utilizao do mesmo. Para tal, basta obtermos o endereo internet ( URL ) do WSDL desejado, criar um novo arquivo-fonte, e acessar o menu 'Ferramentas -> Gerar Cliente WebServices...'. Para cada servio que se tenha a necessidade de gerao de um fonte client, recomenda-se fortemente que cada fonte client seja gerado em um arquivo independente e exclusivo para este fim, e que de forma alguma este fonte gerado pelo assistente seja alterado. Requisitos bsicos para a Gerao do Client em Advpl O processo de gerao de fonte disparado atravs do IDE, porm o servidor Protheus que ir buscar o documento WSDL solicitado. De modo que, a estao servidora utilizada no ambiente deve ter acesso o endereo solicitado.

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente Veja tambm Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / 09. Servio de Exemplo : SERVERTIME

Topo da Pgina

Gerao de Client em Advpl - Passo 01

Reviso: 30/04/2004

Abrangncia Verso 7.10 Verso 8.11

Passo 1 : Determinar como obter o WSDL do servio desejado A maioria das definies WSDL dos servios disponiveis na WEB so acessados atravs de uma URL, em geral apontando para o servidor onde o servio est publicado, contendo o nome do servio na url e um sufixo ?WSDL ou .WSDL na Url. No h padro definido para tal, de modo que cada servidor pode disponibilizar ( ou no ) o WSDL de uma maneira diferente . O WSDL de alguns servios restritos ( como por exemplo o servio de busca na base de dados do Google ) so disponibilizados em arquivo ASCII, enviados por e-mail, apos um cadastro no site e autorizao da empresa para o uso do servio por ele provido. No nosso exemplo ilustrativo, a definio do servio obtida diretamente via http, atravs do link http://localhost/SERVERTIME.apw?WSDL Caso este link seja acessado atravs de um Web Browser ( Internet .Explorer., por exemplo ), ser exibido no browse um documento XML correspondendo a definio do servio. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente

Topo da Pgina

Gerao de Client em Advpl - Passo 02

Reviso: 30/04/2004

Abrangncia Verso 7.10 Verso 8.11

Passo 2 : Gerar o Fonte AdvPl do client usando o Assistente do IDE Ao ser gerado um fonte client para um Web Service, este fonte conter as definies dos metodos do servio, a(s) estrutura(s) utilizada(s) no mesmo, e a(s) classe(s) intermediria(s) de uso interno para montagem e desmontagem da(s) estrutura(s) ; visando o encapsulamento de todos os tratamentos de envio e recebimento de dados atravs de pacotes SOAP. O Fonte gerado atravs do assistente de criao de fonte deve preferencialmente ser gerado e compilado em um arquivo exclusivo, destinado unica e exclusivamente a este cdigo. E, por tratar-se de uma classe Advpl gerada a partir da definio de um servio, no deve ser inserida e/ou alterada nenhuma das definies geradas pelo assistente, pois as mesmas sero perdidas caso o fonte seja gerado novamente . Para gerao do fonte client em Advpl para utilizar este servio, necessrio criar um novo arquivo .PRX no IDE, especificamente para conter as classes deste servio . Ento, deve ser acessado o menu Ferramentas, opo Gerar Ciente Webservices . Neste momento, ser mostrado na tela um pop-up semelhante ao mostrado abaixo :

No campo de entrada de dados, deve ser digitada a URL de onde o servidor ir obter a definio do WebSErvice. ( no nosso caso, http://localhost/SERVERTIME.apw?WSDL ) . Aps a confirmao da janela acima, caso o processamento ocorra com suicesso, na janela de mensagens do Ide ser mostrado um texto semelhante ao abaixo : Estabelecendo conexo com o server... Por favor aguarde. Obtendo descrio do WebService... Finalizando conexo com o server... Ok

E, na janela do novo arquivo criado, dever ser criado um cdigo-fonte semelhante ao mostrado abaixo :
#INCLUDE 'PROTHEUS.CH' #INCLUDE 'APWEBSRV.CH' --- header do servio --/* ========================================================== ===================== WSDL Location http://localhost/SERVERTIME.apw?WSDL Gerado em 12/30/02 17:21:29 Observaes Cdigo-Fonte gerado por ADVPL WSDL Client 1.021217 B Alteraes neste arquivo podem causar funcionamento incorreto e sero perdidas caso o cdigo-fonte seja gerado novamente. ========================================================== ===================== */ /* ------------------------------------------------------------------------------WSDL Service WSSERVERTIME ------------------------------------------------------------------------------- */ --- declarao da Classe client do WebService, com metodos e propriedades utilizadas --WSCLIENT WSSERVERTIME WSMETHOD NEW WSMETHOD GETSERVERTIME WSDATA _URL AS String WSDATA cGETSERVERTIMERESULT AS string ENDWSCLIENT --- declarao do mtodo NEW, para a criao do Objeto / Servio --WSMETHOD NEW WSCLIENT WSSERVERTIME ::_URL := NIL ::cGETSERVERTIMERESULT := '' Return Self /* ------------------------------------------------------------------------------WSDL Method GETSERVERTIME of Service WSSERVERTIME ------------------------------------------------------------------------------- */ --- Definio do mtodo, que recebe os parmetros de chamada, executa o servio e alimenta as propriedades de retorno do metodo, contendo os encapsulamentos necessrios para tratamento de excesses --WSMETHOD GETSERVERTIME WSSEND NULLPARAM WSRECEIVE cGETSERVERTIMERESULT WSCLIENT WSSERVERTIME Local cSoap := '', oXmlRet BEGIN WSMETHOD DEFAULT ::_URL := 'http://localhost/SERVERTIME.apw'

cSoap += '<GETSERVERTIME xmlns='http://localhost/'>' cSoap += '</GETSERVERTIME>' oXmlRet := SvcSoapCall( Self,cSoap,; 'http://localhost/GETSERVERTIME',; 'DOCUMENT','http://localhost/',) ::cGETSERVERTIMERESULT := xGetInfo( oXmlRet, '_GETSERVERTIMERESPONSE:_GETSERVERTIMERESULT:TEXT', '' ) END WSMETHOD oXmlRet := NIL Return .T.

O fonte acima constitui uma Classe em Advpl, gerada para realizar a interface com a classe original publicada no Server, j realizando os tratamentos adequados para realizar a comunicao via http com o servidor onde o servio est publicado. Vale obvervar que, as linhas em negrito no fonte acima no foram inseridas pelo assistente do IDE, mas acrescentadas a este documento para fins didticos. O cabealho do fonte contm informaes sobre a localizao do WSDL utilizado para a gerao do fonte, data e hora de gerao e verso do engine de Web Services utilizado . Logo abaixo, a declarao de uma classe client de Web Services ( WSCLIENT WSSERVERTIME ), com o mtodo new() para inicializao das propriedades advpl da classe . E, em seguida, a declarao do mtodo de busca de Horrio ( WSMETHOD GETSERVERTIME ), que no envia parmetro algum, e retorna o horrio atual do server em :: cGETSERVERTIMERESULT, com todos os tratamentos necessrios embutidos.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente

Gerao de Client em Advpl - Passo 03

Reviso: 22/04/2004

Abrangncia Verso 7.10 Verso 8.11

Passo 3 : Criar um fonte que utilize esta classe para utilizao do WebService. Agora, necessrio criar um novo arquivo no IDE, e montar uma funo para utilizar a classe de Web Services client para obter o horrio no servidor.
1 2 3 #INCLUDE 'PROTHEUS.CH' User Function TestClient()

4 5 6 7 8 9 10 11 12 13 14 Linha 1

Local oSvc := NIL oSvc := WSSERVERTIME():New() If oSvc:GETSERVERTIME() alert('Horrio no Servidor : '+ oSvc:cGETSERVERTIMERESULT) Else alert('Erro de Execuo : '+GetWSCError()) Endif Return

declarada a utilizao do Include Protheus.ch, contendo as definies dos comandos ADVPL e demais constantes Linha 3 Inicia-se a definio da User Function para utilizar o Web Service Linha 4 Uma varivel local declarada para conter o Objeto do Web Service client Linha 6 Utilizando-se do servio, a varivel oSvc alimentada com uma onva instncia do Web Services client, obtida atravs da sintaxe <NOME_DO_SERVICO>():New() Linha 8 executado o mtodo GetServerTime a partir do Objeto do servio oSrv, sem passar qualquer parametro. O retorno de um mtodo do client pode ser .T. (true) em caso de execuo com sucesso ou .F. (false) em caso de falha de execuo . Linha 9 Caso o servio tenha sido executado com sucesso, o retorno esperado alimenrado na propriedade cGetServerTimeResult do objeto do servio. Linha 11 Caso contrrio ( retorno .F. ), ocorreu alguma falha na chamada do servio, como por exemplo o servidor no estava no ar, demorou muito pra responder ( time-out ), entre outras. Para ser possvel recuperar maiores detalhes sobre a ocorrncia de erro, deve ser utilizada a funo GetWSCerror(), que retorna uma string com o resumo da ocorrncia . Linha 13 O programa de teste finalizado com um Return
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente

Gerao de Client em Advpl - Passo 04

Reviso: 22/04/2004

Abrangncia Verso 7.10 Verso 8.11

Passo 4 : Executar o programa de testes Abra uma nova instncia do Ap Remote, e execute a funo U_TESTCLIENT . Caso o Web Service esteja no ar e funcionando, e o fonte client seja devidamente compilado e sem erros, o resultado esperado uma janela semelhante a mostrada abaixo :

No ambiente montado para teste, o Servidor de Web Services e o client esto no Protheus, compilados no mesmo Repositrio de Objetos . Para fins didticos, possvel simular uma ocorrncia de falha no client, ao desabilitar o Server HTTP do Protheus (colocando enable=0 na chave [http] do arquivo de consigurao do servidor), re-iniciar o Server Protheus, e executar o programa client novamente . Deve ser obtida uma tela semelhante a exemplificada abaixo :

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente

Gerao de Client em Advpl - Passo 05

Reviso: 22/04/2004

Abrangncia Verso 7.10 Verso 8.11

Passo 5 : Obtendo informaes de debug Visto at o passo 4, um exemplo completo de um client funcionando perfeitamente . Agora, possvel imaginar que, durante o desenvolvimento e testes do client do servio, faam-se necessrias determinadas informaes internas as rotinas de execuo do servio

no client Advpl . Para tal, foi criada uma funo que permite definir em tempo de execuo, um nvel de detalhamento de informaes adicionais relacionadas ao Web Service ; informaes estas que sero mostradas no Console do Server Protheus ( caso habilitado ) . a Funo para definir o nvel de detalhe chama-se WSDLDbgLevel(), e recebe um nmero como parmetro : 0 ( default ) 1 2 Sem informaes adicionais. Apenas String SOAP de retorno do Server. Strings Soap de Envio e Retorno.

Ento, na linha 7, acrescentada a instruo WSDLDbgLevel(2), para ativar o nvel mais completo de informacoes adicionais, e possvel observar no console do servidor as mensagens apresentadas durante a execuo do fonte de testes do client . Deve ser obtido um echo no console do server semelhante ao exemplo abaixo : Iniciando Thread (siga0984, AUTOMAN)... ------------------------------------------------------------------------------SvcSoapCall to http://automan:8000/webservice/SERVERTIME.apw / DOCUMENT NameSpace http://automan:8000/webservice/ SoapAction http://automan:8000/webservice/GETSERVERTIME Called from GETSERVERTIME ( 137) Called from U_TESTCLIENT ( 10) ---------------------------------- SOAPSEND ----------------------------------<?xml version='1.0' encoding='utf-8'?> <soap:Envelope xmlns:xsi='http://www.w3.org/2001/XMLSchemainstance' xmlns:xsd=' http://www.w3.org/2001/XMLSchema' xmlns:soap='http://schemas.xmlsoap.org/soap/en velope/'> <soap:Body> <GETSERVERTIME xmlns='http://automan:8000/webservice/'> </GETSERVERTIME> </soap:Body> </soap:Envelope> --------------------------------------------------------------------------------------------------------------- POST RETURN --------------------------------<?xml version='1.0' encoding='utf-8'?><soap:Envelope xmlns:xsi='http://www.w3.or g/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:so ap='http://schemas.xmlsoap.org/soap/envelope/'><soap:Body><GETSE RVERTIMERESPONSE xmlns='http://automan:8000/webservice/'><GETSERVERTIMERESULT> 10:37:10</GETSERVE

RTIMERESULT></GETSERVERTIMERESPONSE></soap:Body></soap:Env elope> ------------------------------------------------------------------------------Fim Thread (siga0984, AUTOMAN) BytesIn 73 BytesOut 75 O texto marcado em azul claro so as mensagens informativas a respeito da chamada do WebService, informando a URL chamada, o estilo soap de troca de dados ( document ), o NameSpace e o SoapAction utilizados. O Texto marcado em verde (SOAPSEND) informa o conteudo do pacote Soap que foi enviado ( postado ) ao Servidor, e o conteudo em amarelo ( POST RETURN ) informa o contedo do pacote Soap devolvido pelo Server referente a esta solicitao. Quando ocorre um erro qualquer, relacionado a execuo do client Web Services, o mtodo chamado retorna .F., e o erro pode ser recuperado atravs da funo GetWSCerror(), vista anteriormente . Para cada excesso prevista no client, existe um cdigo de erro correspondente, todos eles prefixados com WSCERR . A maioria das ocorrncias est relacionada a gerao do Cdigo fonte do client Advpl utilizado-se o IDE. Todas as ocorrenctas de excesso tratadas peo Web Services client Advpl esto relacionadas no Tpico Web Services client Cdigos de Erro .
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente

Topo da Pgina

Tipos de dados suportados - 'Client'

Reviso: 22/04/2004

Abrangncia Verso 7.10 Verso 8.11

At o momento, so suportadas as geraes de cdigo Advpl para WebServices 'Client', que utilizam os tipos bsicos de dados listados abaixo. Para permitir a manipulao de cada tipo, utilizando variveis Advpl, so utilizados os tipos bsicos do Advpl para tratar simultaneamente mais de um tipo de dado dos pacotes 'SOAP' dos WebServices. Os tipos abaixo so disponibilizados em Advpl atravs de uma varivel de tipo 'N' Numrica INT INTEGER

BYTE FLOAT DOUBLE UNSIGNEDLONG UNSIGNEDINT DECIMAL LONG

Os tipo abaixo disponibilizado em Advpl atravs de uma varivel de tipo 'D' Data DATE

Os tipos abaixo so disponibilizados em Advpl atravs de uma varivel de tipo 'C' Character STRING DATETIME CHAR (**) BASE64BINARY

(**) O tipo CHAR corresponde uma string, contendo o nmero do caractere correspondente tabela ASCII Os tipo abaixo disponibilizado em Advpl atravs de uma varivel de tipo 'L' Logica BOOLEAN

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente

Topo da Pgina