Upload
alexandre-santos
View
384
Download
10
Embed Size (px)
Citation preview
7/22/2019 ADVPL - Web Services Com Protheus
1/140
Web Services com Protheus
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
O Protheus, a partir da verso AP7, possui ferramentas nativas e integradas com a LIBde Infra-Estrutura do ERP, para desenvolvimento de aplicaes 'Cliente' e 'Server',utilizando a tecnologia dos Web Services. Para melhor compreenso do assunto, os
tpicos relacionados a ambos foram didaticamente separadosem Aplicaes ServereAplicaes Cliente, respectivamente. Nos tpicos 'Comandos' e 'Funes', so abortadasrespectivamente as diretivas e funes da Lib de Infra-estrutura do ERPdisponibilizadas para o desenvolvimento de ambas as aplicaes, Cliente e Server. No
tpico 'Exemplos Advpl', so demonstrados os exemplos 'atmicos' de uso das funes ecomandos.
7/22/2019 ADVPL - Web Services Com Protheus
2/140
COMANDOS - ENDWSCLIENT
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
ENDWSCLIENT [ self ]
Parmetros
Argumento Tipo Descrio
self (NULO) Esta instruo no recebe nenhum parmetro.
Descrio
Atravs desta instruo, encerra-se a declarao de uma classe 'Client'de Web Services,iniciada com ostatementWSCLIENT.
Esta instruo de declarao utilizada exclusivamente quando da gerao de um fonte'Cliente' de Web Services, atravs do assistente 'Gerar Cliente WebServices...' do IDE.
Observao : A utilizao deste comando exige a declarao do #include'APWEBSRV.CH'no fonte Advpl.
7/22/2019 ADVPL - Web Services Com Protheus
3/140
COMANDOS - ENDWSSERVICE
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
ENDWSSERVICE [ self ]
Parmetros
Argumento Tipo Descrio
self (NULO) Esta instruo no recebe nenhum parmetro.
Descrio
Atravs desta instruo, encerra-se a declarao de uma classe 'Server' de Web Services,iniciada com ostatementWSSERVICE.
O no-fechamento da declarao da classe ocasiona "falha de compilao" no fonte.
Observao : A utilizao deste comando exige a declarao do #include'APWEBSRV.CH'no fonte Advpl.
7/22/2019 ADVPL - Web Services Com Protheus
4/140
COMANDOS - ENDWSSTRUCT
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
ENDWSSTRUCT [ self ]
Parmetros
Argumento Tipo Descrio
self (NULO) Esta instruo no recebe parmetros
Descrio
Atravs desta instruo, encerra-se a declarao de uma estrutura a ser utilizada em umWeb Service, iniciada com ostatementWSSTRUCT.
O no-fechamento da declarao da estrutura ocasiona falha de compilao no fonte.
Observao : A utilizao deste comando exige a declarao do #include'APWEBSRV.CH'no fonte Advpl.
7/22/2019 ADVPL - Web Services Com Protheus
5/140
COMANDOS - WSCLIENT
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
WSCLIENT cClientName
Parmetros
Argumento Tipo Descrio
cClientName CaractercClientName corresponde 'a classe do Web Service a sergerada.
Descrio
Atravs desta instruo, inicia-se a declarao uma classe 'Cliente' de Web Services emAdvpl. Esta instruo de declarao utilizada exclusivamente quando da gerao deum fonte 'Cliente' de Web Services, atravs do assistente 'Gerar Cliente WebServices...',disponvel no Protheus IDE.
Para encerrar a declarao da classe, utilizada ainstruo ENDWSCLIENT.
Observao : A utilizao deste comando exige a declarao do #include'APWEBSRV.CH'no fonte Advpl.
7/22/2019 ADVPL - Web Services Com Protheus
6/140
COMANDOS - WSDATA
Reviso: 30/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
WSDATA cVarNAme AS [ ARRAY OF ] cVarType [ OPTIONAL ]
Parmetros
Argumento Tipo Descrio
cVarNAme CaractercVarName corresponde ao nome da propriedade adeclarar.
AS Caracter Separador para indicar o tipo da propriedade.
ARRAY OF CaractercVarType corresponde a um Tipo Soap / compatvel devarivel a ser utilizado no servio. Veja os tipossuportados abaixo na Tabela A -Tipos de Dados
cVarType CaractercVarType corresponde a um Tipo Soap / compatvel devarivel a ser utilizado no servio. Veja os tipossuportados abaixo na Tabela A -Tipos de Dados
OPTIONAL Caracter
Caso especificado , definimos que esta propriedade
opcional no contexto do Web Service .
Descrio
Utiliza-se esta instruo para declarar uma propriedadede uma classe paraWebServices, 'Cliente' ou 'Server'.
Uma propriedade obrigatoriamente deve ter definida seu nome e tipo, e opcionalmentepodemos definir que a mesma ter tratamento de array e/ou tratamento opcional.
Observao : A utilizao deste comando exige a declarao do #include
'APWEBSRV.CH'no fonte Advpl.
7/22/2019 ADVPL - Web Services Com Protheus
7/140
COMANDOS - WSMETHOD
Reviso: 22/04/2004
Abrangncia
Verso 7.10
Sintaxe
WSMETHOD cMethodName [ WSRECEIVE ] [ WSSEND
] [ WSSERVICE ]
Parmetros
Argumento Tipo Descrio
cMethodName CaractercMethodName corresponde 'ao nome do mtodo do WebService.
WSRECEIVE
Caracter
Atravs desta instruo , declaramos quais so o(s)parametro(s) que este mtodo recebe, separados porvrgulas. Caso um mtodo no receba parmetros ,devemos declarar que o mesmo recebe o parmetroreservado NULLPARAM.
WSSEND
CaracterAtravs desta instruo , declaramos um e apenas umparmetro de retorno de um Web Service .
WSSERVICE Caracter cServiceName corresponde ao nome da classe do servioao qual o mtodo atual pertence.
Descrio
Atravs desta instruo, incia-se a declarao de um mtodo de um Web Service -'Cliente' e/ou 'Server', em Advpl . Utilizamos esta instruo em dois momentos nodesenvilvimento :
Na declarao da classe 'Server' e/ou 'Cliente' do servio.Na definio do fonte do mtodo 'propriamente dito', do respectivoWebService.
Ao utilizarmos a instruo WSMETHOD dentro da declarao de uma classeWSSERVICE, informamos apenas o primeiro parmetro ( cMethodName ) . Porm, aodeclarar o fonte propriamente dito do mtodo, todos os parmetros desta instruo soobrigatrios.
Observao : A utilizao deste comando exige a declarao do #include'APWEBSRV.CH'no fonte Advpl.
7/22/2019 ADVPL - Web Services Com Protheus
8/140
COMANDOS - WSSERVICE
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
WSSERVICE cServiceName [ DESCRIPTION ] [ NAMESPACE ]
Parmetros
Argumento Tipo Descrio
cServiceName Caracter
cServiceName corresponde o nome do Servio ( Classeem Advpl ) que ser declarado / criado. A nomenclaturade um Web Service segue a regra de nomenclatura defunes Advpl .
DESCRIPTION
Caracter
cDescr corresponde descrio do Servio, mostrada natela de ndice de servios, e fornecida tambm jonto doWSDL gerado pelo servidor Protheus para o servioespecificado.
NAMESPACE
CaractercClsNS corresponde o NameSpace sob o qual este
servio deve ser publicado.
Descrio
Atravs desta instruo, iniciamos a declarao uma classe 'Server' de WebServices emAdvpl.
Dentro da estrutura de uma Classe 'Server' de Web Services, devemos declarar osmtodos disponibilizados da classe, e declaramos todas as propriedades ,parmetros eretornos utilizados por esta classe, devidamente especificadas, utilizando as instrues
WSMETHOD e WSDATA, respectivamente.
Para encerrar a declarao da classe, utilizamos a instruo ENDWSSERVICE..
A declarao de uma classe 'Server' de Web Services deve tr a seguinte estruturabsica :
WSSERVICE DESCRIPTION NAMESPACE
WSDATA AS
(... demais propriedades, parmetros e retornos ...)
7/22/2019 ADVPL - Web Services Com Protheus
9/140
WSMETHOD
(... demais mtodos da classe ...)
ENDWSSSERVICE
(... fonte(s) do(s) mtodo(s)s desta classe ...)
Observao : A utilizao deste comando exige a declarao do #include'APWEBSRV.CH'no fonte Advpl.
7/22/2019 ADVPL - Web Services Com Protheus
10/140
COMANDOS - WSSTRUCT
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
WSSTRUCT cSructName
Parmetros
Argumento Tipo Descrio
cSructName CaractercStructName corresponde ao nome da estrutura a sercriada. Obedee 'as regras de nomenclatura de funesAdvpl.
Descrio
Atravs desta instruo , iniciamos a declarao de uma estrutura, a ser utiilzada porum Web Service 'Server', em Advpl . Dentro de uma estrutura, devemos apenasdeclarar as propriedades que a mesma contm, atravs da instruo WSDATA.Devemos finalizar a declarao da estrutura utilizando o comando ENDWSSTRUCT.
Observao : A utilizao deste comando exige a declarao do #include'APWEBSRV.CH'no fonte Advpl.
7/22/2019 ADVPL - Web Services Com Protheus
11/140
Exemplo de uso da funoGETWSCERROR
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
No exemplo abaixo, ilustrado o tratamento de erro sugerido para uma chamada de ummtodo atravs de um programa 'Client', desenvolvido em Advpl.
#include 'Protheus.ch'
#include 'ApWebSrv.ch'
User Function TstService
Local oService , cSvcError , cSoapFCode ,cSoapFDescr
// Cria uma instncia do servio Cliente
oService := WSTeste():New()
// Realiza a chamada do mtodo Hello() do servio.
If oService:Hello()
// Mtodo executado com sucesso.
MsgStop('Execuo OK')
Else
// Caso o mtodo retorne .F. , devemos identificar e tratar aocorrncia
cSvcError := GetWSCError() // Resumo do erro
cSoapFCode := GetWSCError(2) // Soap Fault Code
cSoapFDescr := GetWSCError(3) // Soap Fault Description
If !empty(cSoapFCode)
// Caso a ocorrncia de erro esteja com o fault_code
preenchido ,
// a mesma teve relao com a chamada do servio .
MsgStop(cSoapFDescr,cSoapFCode)
Else
// Caso a ocorrncia no tenha o soap_code preenchido
// Ela est relacionada a uma outra falha ,// provavelmente local ou interna.
MsgStop(cSvcError,'FALHA INTERNA DE EXECUCAO DO
SERVIO')
Endif
Endif
oService := NIL
Return
7/22/2019 ADVPL - Web Services Com Protheus
12/140
Exemplo de uso da funoGETWSCVER
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
No exemplo abaixo , obtemos a verso da Lib 'Cliente'de Web Services compilada norepositrio atual.
User Function ShowVersions()
Local cCliVers := GetWSCVer()
MsgStop(cCliVers)
Return
7/22/2019 ADVPL - Web Services Com Protheus
13/140
Exemplo de uso da funoGETWSSVER
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
No exemplo abaixo , obtemos a verso da Lib 'Server' de Web Services compilada norepositrio atual.
User Function ShowVersion()
Local cSrvVers := GETWSSVER()MsgStop(cSrvVers)
Return
7/22/2019 ADVPL - Web Services Com Protheus
14/140
Exemplo de uso da funoSETSOAPFAULT
Reviso: 30/04/2004
Abrangncia
Verso 7.10 Verso 8.11
No exemplo 01, partindo de um mtodo de um WebServices 'Server', caso umparmetro no atenda a faixa de dados necessria, o servio retorna ao Client solicitanteum Soap-Fault, indicando a ocorrncia de erro.
No exemplo 02, retornamos um Soap-Fault, indicando que no estava disponvel umrecurso no servidor para o processamento requisitado. Neste, retornamos que o FaultCode 'SOAPFAULT_RECEIVER', pois o pacote no foi processado no por teralgum contedo invlido, mas sim por alguma razo ligada o ambiente do servidor.
Por default, o Fault-Code de um Soap-Fault 'SOAPFAULT_SENDER', o que indicaque o servio no foi processado por alguma razo ligada o pacote de dados enviados;e indica ao client que o pacote deve ser re-montado para que o servio seja executado.
Exemplo 01
(...)
If ::Indice > 1024
SetSoapFault('Argumento Invlido','O ndice no pode ser maior que
1024.')
Return .f.
Endif
(...)
Exemplo 02
(...)
If !File('\extras\modelo.cfg')
SetSoapFault('Servio Indisponvel','',SOAPFAULT_RECEIVER)
Return .f.Endif
(...)
7/22/2019 ADVPL - Web Services Com Protheus
15/140
Funes GETWSCERROR
Reviso: 22/04/2004
Abrangncia
Verso 7.10
Sintaxe
GETWSCERROR ( [ nInfo ] ) --> xErrorInfo
Parmetros
Argumento Tipo Descrio
nInfo Numrico
nInfo especifica qual informao pertinente ao erro deveser retornada, podendo ser :
1 -Retorna uma String contendo o Resumo do ErroCOMPLETO (DEFAULT)2 = Retorna uma String contendo o soap:fault_code , casodisponvel .3 = Retorna uma String contendo o soap:fault_String ,caso disponvel .4 = Retorna um Objeto XML contendo os nodes
completos com as informaes do erro , apenas caso oerro seja um soap_Fault.
Retorno
Tipo Descrio
(Qualquer)Retorna a informao do erro solicitada atravs do parmetro nInfo . CasonInfo seja 1 , 2 ou 3 , o retorno do tipo String . Caso seja tipo 4 , serretornado um Objeto XML.
Descrio
Utilizada no desenvolvimento de uma aplicao 'Client' de WebServices,atravs destafuno possvel recuperar as informaes pertinentes uma ocorrncia de erro deprocessamentode um mtodo 'Client', aps a execuo do mesmo.
Caso a execuo de um mtodo 'Client' de Web Services retorne .F.,deve ser utilizada afuno GetWSCError(), para identificar a origem da ocorrncia. Durante uma operaode execuo de um mtodo 'Client' de WebServices,so possveis ocorrncias de errodas seguintes naturezas, emmomentos especficos :
7/22/2019 ADVPL - Web Services Com Protheus
16/140
1 -Antes do pacote 'SOAP',com os parmetros e dados pertinentes requisio, serenviado.
Durante a montagem do pacote SOAP, para envio dos parmetros do mtodo solicitado
o servidor, realizada uma consistncia do(s) parmetro(s) a serem enviados, tais
como a obrigatoriedade do parmetro e o tipo Advpl com o qual o parmetro foialimentado. Se e somente se os parmetros informados sejam vlidos, o pacote SOAPmontado postado no servidor de WebServices.
2 -Ao postar o pacote 'SOAP' para o respectivo WebService
Ao postar o pacote, caso o host do Web Service utilizado ou o servidor referente omesmo no foi localizadoou no esteja no ar.
3 -Aps o envio do pacote e obteno do devido retorno do Server.
Uma vez enviado ao Server, a interface client entra em modo 'stand-by', aguardando por
um pacote de retorno SOAP doServer. Aps a portagem, caso o pacote devolvido noesteja em conformidade com a declarao do servio, ou o servidor devolveu um htmlao invs de um xml 'SOAP'.
4 -Erro Interno de execuo : Qualquer ocorrncia de erro fatal, seja antes ou depois doenvio da requisio, cuja origem no seja tratada ou prevista pelas rotinas 'Client' doServio, como por exemplo um retorno de um pacote XML com erro de sintaxe ouestruturalmente invlido .
7/22/2019 ADVPL - Web Services Com Protheus
17/140
Funes GETWSCVER
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
GETWSCVER ( ) --> cVersion
Retorno
Tipo Descrio
CaractercVersion corresponde verso do Build da Lib 'Cliente' de WebServices,copmpilada no repositrio em uso atualmente.
Descrio
Utilizada no desenvolvimento de uma aplicao 'Cliente' de Web Services ,atravsdesta funo possvelobter a string contendo a indentificao da verso de Build daLIB de Infra-Estrutura do Web Services 'Cliente'.
7/22/2019 ADVPL - Web Services Com Protheus
18/140
Funes GETWSSVER
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
GETWSSVER ( ) --> cVersion
Retorno
Tipo Descrio
CaractercVersion corresponde verso do Build da Lib 'Server' de WebServices,
compilada no repositrio em uso atualmente.
Descrio
Utilizada no desenvolvimento de uma aplicao 'Server' de Web Services ,atravs destafuno possvel obter a string contendo a indentificao da verso de Build da LIB deInfra-Estrutura do Web Services 'Server'.
7/22/2019 ADVPL - Web Services Com Protheus
19/140
Funes SETSOAPFAULT
Reviso: 30/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
SETSOAPFAULT ( < cError > , < cString > , [ nFCode ] , [ cFactor ] , [ cFDetail ] ) -->.T.
Parmetros
Argumento Tipo Descrio
cError Caracter
Atravs de cError deve ser especificada uma descrioreduzida , referindo-se ao tipo do erro , por exemplo :Erro de argumento , Parametro Invalido , Falha deArquivo ,...
cString Caracter
Em cString deve-se especificar um detalhe maior daocorrncia , no exatamente um detalhe tcnico , pormuma especificao objetiva da ocorrncia. Por exemplo :Parametro XXXXX forada faixa vlida de dados ,compreendida entre mmm e nnn , ...
nFCode Numrico
Fault Code : Atravs deste parametro , possvelespecificar a origem da ocorrncia da Soap Fault .Segundo a documentao do SOAP, Verso 1.2 (publicada na W3C ) , foram definidos 6 cdigos deocorrncias standard de erro , detalhados na Tabela A.Caso no seja especificado , por default assumido ocdigo 5 ( Sender )
cFactor Caracter
Atravs de CFActor , possvel especificarexplicitamente qual node / atributo do XML / Soap queno foi processado e/ou ocasionou a falha . Deve serutilizado o formato anyURI ( ref namespacehttp://www.w3.org/2001/XMLSchema ) para especifcar o
node / atributo que ocasionou a falha.
cFDetail Caracter
Atravs de cFDetail , possvel especificar para finsinternos de processamento maiores detalhes sobre umaocorrncia de erro, especificamente relacionada o
processamento do corpo ("body") de um pacote SOAP.
Retorno
http://www.w3.org/2001/XMLSchema7/22/2019 ADVPL - Web Services Com Protheus
20/140
Tipo Descrio
Lgico Esta funo sempre retorna .T. (true)
Descrio
Utilizada no desenvolvimento de uma aplicao'Server' de WebServices,atravs destafuno possvel setar uma ocorrncia de erro tratada, referente execuo do servio,ou impossibilidade de execuo do mtodo durante a execuo do mesmo.
Dentre as razes pelas quais este tratamento utilizado, podemos citar ocorrnciasrelacionadasa validade dos dados, recebidos no pacote de parametros enviados pelo'Cliente', como parmetros invalidos ou fora da faixa de dados permitida pela rotina,ouocorrncias relacionadas ao 'Server', como a falta de um determinado recurso no serverpara o processamento,como uma falha de acessoa base de dados, ou qualquer outrarazo implementada no servio.
Tabela A -FAULT CODES
nFCode Constante Descrio
1 SOAPFAULT_VERSIONMISMATCH NameSpace invlidoencontrado no processamentodo Soap:Body
2 SOAPFAULT_MUSTUNDERSTAND Refere-sea falha deinterpretao de um node /atributo contido noSoap:Header, especificadocom o atributomustUnderstand setado para
'true'3 SOAPFAULT_DTDNOTSUPPORTED A String Soap enviada como
parmetro continha um DTD(Document Type Definition).
4 SOAPFAULT_DATAENCODINGUNKNOWN O HEader ou o Body dopacote SOAP est utilizandoum encoding-type nosuportado pelo server.
5 SOAPFAULT_SENDER Refere-se a uma ocorrnciade erro e/ou falha deprocessamento da aao, poralgum tipo de inconsistnciarelacionadaa falta de um oumais dados necessrios aoprocessamento. Indica umaocorrncia que requer que opacote SOAP seja remontadopara que seja realizada umanova tentativa de acesso.
7/22/2019 ADVPL - Web Services Com Protheus
21/140
6 SOAPFAULT_RECEIVER Refere-se a uma ocorrnciade erro e/ou falha deprocessamento por razesque no estoespecificamente relacionadasao conteudo do pacote SOAp
e/ou parametros recebidos,porm relacionados 'a umafalha no Receptor do Servio,como por exemplo o servidor
estar bloqueado paramanuteno. Este tipo deocorrncia no indica queexiste falha no pacoteenviado, mas cosuma-seutilizar para indicar umaocorrncia relacionadanaquele instante de tempo ;possivelmente estandodisponvel posteriormente .
Observao : Para utilizarmos os mnemnicos, ao invs dos nmeros, nos codigosde erro, precisamos declarar no fonte Advpl a utilizao do Include'ApWebSrv.ch'
7/22/2019 ADVPL - Web Services Com Protheus
22/140
Funes SOAPDTGETD
Reviso: 22/04/2004
Abrangncia
Verso 8.11
Sintaxe
SOAPDTGETD ( < cDateTime > ) --> dDate
Parmetros
Argumento Tipo Descrio
cDateTime Caracter String, no formato "Soap" DateTime, a ser considerada.
Retorno
Tipo Descrio
Data Retorna a data identificada na String cDateTime
Descrio
A partir de uma string Advpl, contendo uma data no formato 'soap' DateTime, a funo
SoapDtGetD() retorna a data correspondente em Advpl, como um contedo do tipo 'D'Date.
7/22/2019 ADVPL - Web Services Com Protheus
23/140
Funes SOAPDTGETT
Reviso: 22/04/2004
Abrangncia
Verso 8.11
Sintaxe
SOAPDTGETT ( < cDateTmie > ) --> cTime
Parmetros
Argumento Tipo Descrio
cDateTmie Caracter String, no formato "Soap" DateTime, a ser considerada.
Retorno
Tipo Descrio
Caracter Retorna o horrio identificado, no formato HH:MM:SS
Descrio
A partir de uma string Advpl, contendo uma data no formato 'soap' DateTime, a funo
SoapDtGetD() retorna o horrio correspondente em Advpl, como um contedo do tipo'C' Character, no formato HH:MM:SS
7/22/2019 ADVPL - Web Services Com Protheus
24/140
Funes SOAPDTMOUNT
Reviso: 22/04/2004
Abrangncia
Verso 8.11
Sintaxe
SOAPDTMOUNT ( < dData > , < cTmie > ) --> cDateTmie
Parmetros
Argumento Tipo Descrio
dData Data Data a ser considerada para a montagem do 'DateTime'
cTmie CaracterHorrio, no formato hh:mm:ss, a ser considerado, para amontagem do 'DateTime'
Retorno
Tipo Descrio
CaracterString 'SOAP', correspondendo Data e Horrios especificados, no
formato DATETIME.
Descrio
A partir de uma Data em Advpl , e um horrio, especificado como string, a funoSoapDtMount() retorna a data e horrio especificados como uma string, no formato'Soap'DateTime.
7/22/2019 ADVPL - Web Services Com Protheus
25/140
Funes WSCLASSNEW
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
WSCLASSNEW ( < cSrvStruct > ) --> oNewStruct
Parmetros
Argumento Tipo Descrio
cSrvStruct CaracterEspecifique o nome da estrutura "Server" de Webservicespara a criao do Objeto.
Retorno
Tipo Descrio
ObjetoA funo retorna uma referncia uma nova instncia da estrutura passada
como parmetro.Caso a estrutura no exista, a funo retornar NIL.
Descrio
Atravs da funo WSClassNew(), possvel criar uma nova instncia de uma estrutura(WSSTRUCT) de WebServices, criada para ser utilizadacomo uma estrutura'Server'. Autilizao desta instuo, para criar instmcias de uma estrutura usada numa aplicao'Server' de WebServices em AdvPl, evida a necessidade de criao de um mtodo'NEW' para cada estrutura.
Observao : Embora seja possvel, no se deve utilizaresta instruo para inicializaruma estrutura criada em um fonte 'Client' em Advpl; pois as estruturas client possuemas definies do mtodo NEW() de cada uma, com as devidas inicializaes deparmetros inetrentes ao servio.
7/22/2019 ADVPL - Web Services Com Protheus
26/140
Funes WSDLDBGLEVEL
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Sintaxe
WSDLDBGLEVEL (< nLevel > ) --> NIL
Parmetros
Argumento Tipo Descrio
nLevel Numrico
Atravs de nLevel , definimos qual o nvel deinformaes a ser mostrado : 0 (default ) = seminformaes adicionais , 1 = Apenas pacote de retorno e 2= Informaes e pacote de Envio e Retorno .Obs: Devemos chamar esta funao apos inicializado oObjeto 'Cliente' do Web Service.
Retorno
Tipo Descrio
(NULO) Esta funo sempre retorna NIL
Descrio
Utilizada para depurao de uma aplicao 'Cliente' de Web Services em Advpl .Atravs desta funo, possvel setar, em tempo de execuo, um 'echo' deinformaesadicionais pertinentes execuo de um mtodo 'Client' de Web Services , a sermostrado no console do servidor Protheus ( caso habilitado ) , permitindo aindaparametrizar um nvel dedetalhamento das informaes a serem mostradas.
Observaes
O valor informado na chamada desta funo, ser mantido e considerado portodos os mtodos de servios 'Client' em Advpl, executados a partir de entonesta Thread, at que a aplicao seja finalizada, ou esta funo seja chamadanovamente.Esta funo deve ser utilizada nica e exclusivamente para fins de depurao,pois a mesma onera aperformancedaaplicao 'Client'.
7/22/2019 ADVPL - Web Services Com Protheus
27/140
Aplicaes 'Server' em Advpl
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Neste tpico, e posteriores documentos, so detalhadas as atribuies e funcionalidadesde uma aplicao 'Server'de Web Services, utilizando o Protheus, desde a criao daaplicao at as configuraes necessrias para a publicao do Web Service.
A criao de um 'Server' de Web Services em Advpl consiste na montagem de umaclasse Advplespecial, chamada WSSERVICE, onde cada mtodo da classe uma aodo Web Service. Caber aos fontes desta classe o processamento de uma requisio e a
gerao do respectivo retorno, cabendo ento Lib de Web Services da Infra-Estruturado ERP a camada de troca de dados, recepo, pr-validao etratamento do pacoteSOAP, as converses de dados cabveis do XML para as propriedades de parmetro daclasse Advpl e a montagem do pacote SOAP a partir das propriedades de retornosetadas pelo mtodo executado e retorn-lo ao 'Client' solicitante do proessamento, almde prover o 'Cliente' o documento WSDL referente (s) classe(s) 'Server'compilada(s)no repositrio de objetos em uso e configurado para atender s requisies deprocessamento.
Este mtodo de programao em camadas permite encapsular on tratamentos internos,em se tratando de protocolo HTTP, SOAP e WSDL, tornando relativamente fcil amisso de criar um Web Servie 'Server' utilizando-se do Protheus. Basta escrever umaclasse que receba nenhum, um ou mais que um parmetro e devolva obrigatoriamenteum retorno; configurar o Protheus Server para habilitar a interface HTTP e os WebServices, que a Lib faz todo o resto.
7/22/2019 ADVPL - Web Services Com Protheus
28/140
01. WebServices 'Server' - Configurao
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
O Servidor Protheus como 'SERVER' de WebServices
Um WebService em Advpl utiliza-se de Working Threads (**) para atender assolicitaes de processamento atravs do protocolo HTTP.
Existem duas maneiras de habilitar o WebService : Atravs da criao da seo[WEBSERVICES] no arquivo de configurao do servidor, ou atravs da configuraomanual de um ambiente de Working Threads Extended ( WEBEX ), tambm noinicializador. A diferena entre ambas que a segunda opo permite especificarmaiores detalhes do ambiente de execuo do servio, permite a configurao deservios e Web Sites simultaneamente,e tambm atendimento diferenciado deprocessamento para mais de um host e diretrios virtuais. Quando utilizamos o Protheus8, devemos utilizaro novo assistente de configurao do servidor Protheus -MP8WIZARD, para instalar e configurar o mdulo de WebServices.
Segue abaixo umexemplo documentado de como configurar o servidor Protheus paraWebServices, utilizando a chave [WEBSERVICES].
Observao : Esta configurao exigeque a seo HTTP no esteja configurada noservidor Protheus. Esta configurao ir internamente habilitar o servio de HTTP econfigurar o processo de resposta para WebServices.
[WEBSERVICES]
Enable=1 ; ( Obrigatrio ) Indica se o service est habilitado (1) ou no (0).Environment=ENVTESTE ; ( Obrigatrio ) Indica qual environment do Server
que ir atender as requisiesConout=0 ; ( Opcional ) Permite a exibio de informaes dos status internos do
servio ( default = 0 : desabilitado ) . Utilizado APENAS para depurao, em casosespecficos, pois prejudica significativamentea performance do(s) servio(s).
Trace=0 ; ( Opcional ) Habilita a gravao de um arquivo de log ( wsstrace.log ),contendo as informaes sobre todas as chamadas e status do Web Service ( default = 0)
PrepareIn=01,01 ; (Obrigatrio) Permite especificar qual a empresa e filial doERP sero utilizados para a montagem do ambiente de processamento das requisies.
NameSpace = http://localhost; ( Opcional ) Permite especificar o nome donamespace 'default', utilizado pelo(s) servio(s) compilado(s) sem a definio de'NameSpace'.( default = host atualmente utilizado )
URLLocation = http://localhost; ( Opcional) Permite especificar a url
http://localhost/http://localhost/7/22/2019 ADVPL - Web Services Com Protheus
29/140
responsvel pelo atendimentos solicitaes de processamento do(s) servio(s) ( default= host atualmente utilizado )
Para configurar o WebService manualmente, deve ser inicialmente habilitado oservio deHTTP do servidor Protheus,configurar um processo WEBEX, apontandopara funes internas de processamento dos Web Services, e configurar um host atravs
do qual as requisioes processamentosero atendidas. Veja no exemplo abaixo :
[HTTP] ;; Configurao do protocolo HTTPEnable=1Port=80Path=c:\Ap7\Http
[localhost];; A ttulo de exemplo, configuramos o hostda estao local.Defaultpage=wsindex.apwResponseJob=WSTESTE
[WSTESTE] ; Configuracao do job para atenderos WebServices
TYPE=WEBEX ;; ( Obrigatrio ) Tipo do Job para Web Services deve serWEBEX
ONSTART=__WSSTART ;; ( Obrigatrio ) configurao fixa para WebServices
ONCONNECT=__WSCONNECT ;; ( Obrigatrio ) configurao fixa paraWeb Services
Environment=ENVTESTE ;; Especifique qual ambiente (environment)doservidor Protheus que ir atenderos WebServices.
INSTANCES=2,5 ;; ( Obrigatrio ) Indica qual a quantidade minima (default )e mxima de processos ( Threads) que sero colocados na memria para atender ssolicitaes de processamento do(s) servio(s) publicado(s).
Conout=0 ;; ( Opcional ) Permite a exibio de informaes dos status internosdo servio ( default = 0 : desabilitado ) . Utilizado APENAS para depurao, em casosespecficos, pois prejudica significativamente a performance do(s) servio(s).
Trace=1 ;; (Opcional) Habilita a grevao de um arquivo de log ( wsstrace.log ),contendo as informaes sobre todas as chamadas e status do Web Service ( default = 0)
PrepareIn=01,01 ; (Obrigatrio) Permite especificar qual a empresa e filial doERP sero utilizados para a montagem do ambiente de processamento dasrequisies.
NameSpace = http://localhost/;; ( Opcional ) Permite especificar o nome donamespace 'default', utilizado pelo(s) servio(s) compilado(s) sem a definio de'NameSpace'.( default = host atualmente utilizado )
URLLocation = http://localhost/;; ( Opcional) Permite especificar a url
responsvel pelo atendimentos solicitaes de processamento do(s) servio(s) ( default= host atualmente utilizado )
WSINDEX -ndice de Servios
Uma vez habilitada a configurao para Web Services, obtemos o acesso a umainterface HTTP de consulta ao ndice de servios publicados. Para tal, basta re-iniciar oservidor Protheus aps a configurao ser realizada, abrir um Web Browser ( porexemplo, o Internet Explorer ), e acessar o link http:///wsindex.apw. No caso
http://%3Cservidor%3E/wsindex.apwhttp://localhost/http://localhost/7/22/2019 ADVPL - Web Services Com Protheus
30/140
do exemplo de configurao acima, basta digitarmos http://localhost/wsindex.apw, enos ser apresentada a interface de consulta o ndice dos servios.
Por exemplo, caso o host configuradi para os wehservices fio o host local (localhost) ,devemos acessar olink http://localhost/wsindex.apw. Utilizando o Protheus8, sermostrada uma tela semelhante vista abaixo:
Nesta interface so mostrados todos os servios compilados e disponibilizados noreopsitrio de objetos em uso no ambiente configurado. Atravs dela, possvel obtermaiores detalhes sobre cada um dos servios compilados.
Cada servio ativo um link para uma pgina, onde so mostrados todos os mtodos doservio, e onde apresentado tambm um link atravs do qual o servidor Protheusfornecera descrio do servio (WSDL). Logo abaixo mostrado o exemplo da tela dedetalhes do servio CFGTABLE.
http://localhost/wsindex.apwhttp://localhost/wsindex.apw7/22/2019 ADVPL - Web Services Com Protheus
31/140
O Link para a obteno do WSDL encontra-se acima em 'CFGTABLE.apw?WSDL'.Basta clicar neste link , que uma nova janela do Browser ser aberta, mostrando odocumento WSDL deste servio.
Cada mtodo do servio disponibilizado tambm um link, para uma pgina onde somostrados os exemplos de pacotes SOAP que este mtodo especificamente espera para
recepo de parmetros, e o modelo do pacote de retorno do servio.
Caso o fonte-Client Advpl deste servio seja gerado e esteja compilado no repositrioatual, a inteface de consulta habilita a funcionalidade de teste do WebService, atravs dainterface http, mostrando no final da tela o boto "testar".Ao clicar neste, montadauma tela em HTML para que os parmetros do servio sejam preenchidos. Aps osparmetros preenchidos e submetidos, o pacote de retorno do servio e seu respectivostatus retornado no Browse.
7/22/2019 ADVPL - Web Services Com Protheus
32/140
02. Criando um WebService 'Server' como Protheus
Reviso: 23/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Para criarmos um WebService 'Server' utilizando o Protheus, primeiro devevemoshabilitar o servidor Protheus como servidor de WebServices. Para tal, veja o documento'configurando o servidor ProtheusparaWebServices. '
Uma vez configurado e habilitado os WebServices no servidor Protheus, deve ser
inicialmente determinados os mtodos aos quais o servio se destina; para entodeterminar os parmetros e retorno de cada mtodo. Uma vez determinadas estasinformaes, deve ser codificada uma classe especial em Advpl , chamadaWSSERVICE, que constituir o servio propriamente dito.
Porm, antes de partir para a codificao, fortemente recomendado que sejam lidos osdocumentos deste tpico, onde so abortados em detalhes a infra-estrutura envolvidacom os WebServices, seu funcionamento e as particularidades de comportamento daclasse de WebServices.
7/22/2019 ADVPL - Web Services Com Protheus
33/140
03. Regras para codificao de umWebService
Reviso: 30/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Viso Geral
Paraa codificao deum webservice, foram criadas em Advpl instrues especiais dedeclarao de classe, especficas para WebServices, que suportam nomes 'longos' nonome da classe, mtodos e propriedades. A utilizao destes comandos exige a
declarao do #include 'apwebsrv.ch' no topo do cdigo-fonte; e exige tambm aateno em alguns pontos e particularidades, a iniciar pela nomenclatura do servio,estruturas, mtodos e propriedades.
Caractersticas operacionais do ambiente
Devemos estar atentos ao desenvolver os mtodos de WebServices, devido scaracteristicas operacionais do ambiente de 'Working Threads' utilizado pelo WebServices. Ao executar um mtodo do WebServices, o ambiente ser mantido no ar,aguardando uma nova requisio de processamento, de qualquer servio ou mtodo, ede qualquer cliente. De modo que, ao desenvolver um servio, no devemos deixarabertos as "Querys" utilizadas no mtodo, filtros setados em tabelas principais, euconfiguraes especficas no-padro do ambiente, realizadas para o processamento deum mtodo especfico; pois isto pode causar impacto no funcionamento de todos osWebServices compilados e ativos neste servidor, com efeitos imprevisveis.
Nomenclatura dos Servios
O nome de uma classe para WebServices, deve ser iniciado por um caractere alfabtico,e deve conter apenas os caracteres alfabticos compreendidos entre Ae Z, os caracteresnumricos compreendidos entre 0e 9, podendo tambm ser utilizado o caracter _(underline ) . Um servio no pode ter um nome de uma palavra reservada Advpl, e nopode ter o nome igual a um tipo bsico de informao.
Nomenclatura de Estruturas
O nome dado uma estrutura obedece as mesmas regras de nomenclatura de Servios;no podendo haver uma estrutura com o mesmo nome de um servio declarado.Devemos estar atentos tambm o fato de uma estrutura no estar diretamente ligada o
servio em questo, de modo que no podemos compilar duas estruturas de mesmonome no mesmo repositrio.
7/22/2019 ADVPL - Web Services Com Protheus
34/140
Uma estrutura contitui um agrupamento de dados, criado como uma classe especial(WSSTRUCT) em Advpl. Devemos criar de uma estrutura para um servio, quando necessrio agrupar um conjunto de dadosbsicos e/ou outras estruturas em um nivotipo de informao, que ser utilizada como parmetro e/ou retorno em um ou maismtodos do servio.
Nomenclatura das propriedades-parmetros e retorno
Cada parmetro e retornode todos os mtodosde um servio devem ser declaradoscomo uma propriedade da classe do Servio. Para dar nome a estes,sovlidas asmesmas regras de nomenclatura de Servios, no podendo haver um dado com o mesmonome de um servio ou estrutura j declarados anteriormente.
7/22/2019 ADVPL - Web Services Com Protheus
35/140
04. Tipos Bsicos de Dados - 'Server'
Reviso: 23/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Quando escrevemos um WebService 'Server', devemos especfiicar o tipo da informaode cada parmetro e retorno, em conformidade com a especificao 'SOAP', utilizadanos pacotes XML de troca de dados.
So considerados e suportados pelo Protheus, quando da declarao dos parmetros eretorno, os seguintes tipos bsicos :
String Dado Advpl do tipo String.Date Dado Advpl do tipo Data.Integer Dado Advpl do Tipo numrico(apenas numeros
inteiros.)Float Dado Advpl do Tipo numrico(pode conter numeros
inteiros e no-inteiros.)Boolean Dado Advpl do Tipo Booleano ( lgico ) .Base64Binary Dado Advpl do Tipo String Binria , aceitando todos os
Caracteres da Tabela ASCII , de CHR(0) a CHR(255)
Observaes
Ao declararmos uma propriedade como sendo do tipo "String", no podemosespecificar a palavra "String" em letras maisculas. A palavra STRING, escritadesta maneira, interpretada pelo pr-compilador do Protheus como sendo umaconstante, ocasionando erro de sintaxe da compilao do WebService.
7/22/2019 ADVPL - Web Services Com Protheus
36/140
05. Estruturas - Tipos complexos
Reviso: 23/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Definio de Estrutura
Uma estrutura ( tambm conhecida por Complex Type), constitui uma classe especialdo Advpl, chamada WSSTRUCT, criada especificamente para WebServices. Devemoscriar uma estrutura quando temos a necessidade de agrupar mais de uma informao,incluindo tipos bsicos e/ou outras estruturas.
Ao criarmos um servio que dever receber como parmetro um grupo de informaesdefinido, por exemplo, os dados cadastrais de um cliente, devemos criar uma estruturapara agrupar estes dados. Vale ressaltar que a declarao de uma estrutura no amarra amesma o servio em questo, de modo que a mesma estrutura pode ser utilizada paramais de um servio compilado no repositrio. Caso a estrutura criada seja especficapara o servio em questo, recomendado que seja dado um nome mesma que etnha aver com o servio o qual ela pertena, pois no possvel compilar mais de umaestrutura de mesmo nome no repositrio.
7/22/2019 ADVPL - Web Services Com Protheus
37/140
06. Mtodos 'Server' em Advpl -Caractersticas
Reviso: 26/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Definio
Um mtodo de um WebService consiste em uma ao a ser disponibilizada no servio.Damos a ela um nome para identificao, declaramos a mesma na estrutura da classe doServio, bem como seus parmetros e respectivo retorno.
Parmetros
Ao declarar o fonte de um mtodo, o mesmo pode receber um ou mais parmetros, detipo bsico e/ou estruturas, e inclusive pode no receber parmetro algum. Neste caso,devemos especificar que o parmetro recebido ser NULLPARAM, ou seja, nenhumparmetro.
Retorno
Um mtodo de WebServices deve obrigatoriamente tr uma propriedade de retorno.No faz parte da especificao de WebServices a criao de um mtodo que no possuaretorno.
Codificando o mtodo em Advpl
Como visto anteriormente, tanto os parmetros quanto o retorno de um mtodo deWebServices deve ser declarado como um dado da classe ( atravs da instruoWSDATA ).
Quando escrevemos um mtodo de um WebService, e o mesmo recebe uma solicitaode processamento, as propriedades declaradas como parmetros do mtodo soalimentadas, e o mtodo executado. Por tratarem-se de propriedades, o cdigo fonte
Advpl dever interagir com estas propriedades, prefixando-as com '::' dois pontosseguidos), ou 'self:' , sendo isto vlido tanto para os parmetros do mtodo, como para apropriedade de retorno.
Dada a existncia de uma LIB de Infra-Estrutura, que realiza a camada de comunicao,validao, montagem e desmontagem de pacotes; ao codificar um mtodo deWebService existem sempre dois retornos : A propriedade de retorno do mtodo, e oretorno efetivo do mtodo ao final do processamento.
7/22/2019 ADVPL - Web Services Com Protheus
38/140
O retorno efetivo do mtodo deve ser um valor booleano : Se retornado .T. (True) , istoindica LIB, que o mtodo foi executado com sucesso, e consequentemente apropriedade de retorno foi alimentada. Logo, o pacote 'SOAP' de retorno do mtodo sermontado pela LIB, e devolvida automaticamente o 'Client' que solicitou a chamada deprocessamento.
Caso o retorno efetivo do mtodo seja .F. (False), isto indica LIB que, por algumarazo tratada no fonte do mtodo, no foi possvel a execuo do mtodo. Nestecaso,devemos especificar, antes do retorno, atravs da funo SetSoapFault(), a causa daimpossibilidade de processamento.
Exemplo
WSMETHOD GetDate WSRECEIVE NULLPARAM WSSENDHorarioWSSERVICE ServerTime
If dow(date())=1// Seta um soap_fault, informando que este servio no disponvel aos domingosSetSoapFault('Metodo no disponvel','Este servio no funciona aos Domingos.')
// e retorna .F., indicando que o servio no foi processado com sucesso.Return .f.
Endif
// alimenta a propriedade de retorno::Horario := time()
// E retorna .T. indicando processamento do mtodo com sucesso
Return .T.
Ateno :
Sempre que o retorno efetivo do mtodo verdadeiro (.T. ), a propriedade deretorno deve ser preenchida. Caso ela no seja preenchida, a LIB ir retornar oclient solicitante um pacote de SOAP Fault, indicando que houve um erro noprocessamento do servio, e registrar um error.log na estao servidora. Sergerado tambm uma ocorrncia de erro, caso o mtodo retorne .T., porm afuno SetSoapFault() tenha sido chamada durante a execuo do mtodo. Aocorrncia gerada : RETURN .T. WITH SOAPFAULT EXCEPTION NOT EMPTY.Sempre que o retorno efetivo do mtodo falso (.F.), a funo SetSoapFault()
deve ser chamada, para que a LIB gere um pacote com o motivo do erro para o'Client' que solicitou o mtodo. Caso o retorno efetivo seja .F. , e a funo
SetSoapFault() no tenha sido chamada, devolvido estao'Client' solicitantedo processamento um Soap:Fault , com aocorrncia de erro :RETURN .F. WITH SOAP FAULT EXCEPTION EMPTY.
7/22/2019 ADVPL - Web Services Com Protheus
39/140
07. Tratamento de Erro dos WebServices
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Dada a infra-estrutura envolvida no processamento dos WebServices, a rotinadetratamento de erro da aplicao WebServices 'Server' prev o tratamento de ocorrncias,desde advertncia de carga dos servios, at falhas de inicializao de ambiente,passando por erros que invalidam um determinado servio compilado, at as ocorrnciasde inconsistncias de parmetros de chamada do servio, inconsistncias de retorno,ocorrncias de erro fatal de processamento na aplicao, eocorrncias deprocessamento que no constituam um erro fatal, porm devem retornar um pacote de
ocorrncia de erro, conhecido por SOAP FAULT .
Os tratamentos aplicados s ocorrncias reproduxidas no momento da carga doambiente de WebServices esto relacionados no tpico "Falhas de Carga dos Servios",os relacionados ocorrncias de erro fatal de execuo dos servios esto em"Ocorrncias de Erro Fatal", e a discrminao da utilizao do Soap Fault est estdescrita em "Utilizao do SOAP FAULT".
7/22/2019 ADVPL - Web Services Com Protheus
40/140
08. Utilizao do SOAP FAULT
Reviso: 30/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Quando desenvolvemos um servio, e temos a necessidade de retornar ao 'Client'solicitante do processamento, uma ocorrncia de falha no-fatal de um determinadoprocessamento, deve ser retornado ao mesmo um pacote SOAP, que indica a causa dafalha. Este pacote conhecido por 'SOAP FAULT'.A rotina de tratamento de erro fatalde execuio do WebService, quando da ocorrncia de tal, geraautomaticamente um'SOAP FAULT' com a descrio resumida da ocorrncia o client solicitante.
Dado que, a camada da lib, responsvel pela interpretao do pacote SOAP recebidopelo servio, j se encarrega de validar o formato do pacote e contedos obrigatrios,um Web Service escrito em Advpl deve, antes de realizar o processamento proposto,validar se o contedo dos parmetros est dentro da faixa de dados esperada, econdizentes com o esperado; para ento realizar o processamento e retornar o clientsolicitante.
Para inserir as excesses de execuo com Soap-Fault, em um servio 'Server',utilizamos a funo SetSoapFaut().
Soap-Faults padro do Servidor Protheus de WebServices
A camada de comunicaoda infra-estruruta de WebServices, realiza automaticamenteos tratamentos de protocolo, formato do pacote SOAP e parmetros obrigatrios. Casoexista alguma inconsistncia na chamada de um servio,que incorra em alguma destasexcesses, o servio solicitado no chamado, e o servidor Protheus devolveautomaticamente o client solicitante um Soap-Fault, indicando o que aconteceu.
Estas ocorrncias de Soap-Faultso mostradas no console do servidorProtheus, e soarmazenadas tambm no arquivo error.log do ambiente utilizado.
Soap-Faults padro aps processamento do servio
A camada de comunicaoda infra-estruruta de WebServices valida tambm amontagem do pacote de retorno.Caso exista alguma propriedade de retorno obrigatriodo servio que no esteja alimentada de forma correta, o servidor Protheus devolveautomaticamente o client solicitante um Soap-Fault, indicando que ocorreu um errointerno no servidor de WebServices.
7/22/2019 ADVPL - Web Services Com Protheus
41/140
09. Servio de Exemplo : SERVERTIME
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Inicialmente, o exemplo proposto tm o objetivo de montar um WebService que retorneo horrio no servidor Protheus. Para tal, ser criado um servio, com apenas(inicialmente) um mtodo. A esteservio, daremos a ele o nome de SERVERTIME. E,ao mtodo de buscar o horrio no servidor, daremos o nome de GETSERVERTIME.
A operao de buscar o horrio atual no servidor no necessita de nenhum parmetropara a execuo. Porm, ela ter um retorno : O horrio atual , no formato 'hh:mm:ss'. A
especificao de um WebServices permite que um servio seja declarado de modo a noreceber nenhum parmetro, porm exige que o WebService sempre possua um retorno.
Codificando o Servio
Para codificar um servio, devemos utilizar o Protheus IDE, e criar um novo arquivo deprograma, e nele escrever o servio. A numerao disposta esquerda do cdigo-fonte meramente ilustrativa, no devendo ser digitada. Ela utilizada mais abaixo, onde estecdigo detalhado linha a linha.
1 #INCLUDE 'PROTHEUS.CH'2 #INCLUDE 'APWEBSRV.CH'3
4 WSSERVICE SERVERTIME
5 WSDATA Horario as String6 WSMETHOD GetServerTime7 ENDWSSERVICE
8
9 WSMETHOD GetServerTime WSRECEIVE NULLPARAM WSSEND Horario
WSSERVICE SERVERINFO
10 ::Horario := TIME()11 Return .T.
Linha 1 especificada a utilizao do Include Protheus.ch, contendo as definiesdos comandos ADVPL e demais constantes
Linha 2 Tambm especificamos a o Include ApWebSrv.ch, que contm as definiesde comandos e constantes utilizados nas declaraoes de estruturas e mtodosdos Web Services. Ele obrigatrio para o desenvolvimento de WebServices.
Linha 4 Com esta instruo, definido o inicio da classe do servio principal, ao qualdemos o nome de SERVERTIME
Linha 5 Dentro da estrutura deste servio, informado que um dos parametrosutilizados chama-se horrio, e ser do tipo String
7/22/2019 ADVPL - Web Services Com Protheus
42/140
Linha 6 Dentro da estritura deste servio, informado que um dos mtodos do serviochama-se GetServerTime .Linha 7 Comono so necessrias mais propriedades ou metodos neste servio, aestrutura do servio fechada com esta instruo..Linha 9 Aqui declarado o fonte do Mtodo GetServerTime, que no receber
parametro nenhum ( mas para efeitos de declarao deve ser informado que elereceber o parametro NULLPARAM ), e informado que seu retorno ser odado Horario ( declarado na classe do servio como uma propriedade, do tipoString ) .
Linha 10 atribudo na propriedade ::Horario da classe deste servio, o retorno dafuno Advpl Time(), que retorna a hora atual no servidor no formatoHH:MM:SS. Devemos utilizar o '::', para alimentarmos a propriedade da classeatual
Linha 11 O mtodo GetServerTime finalizado nesta linha, retornando .T. (true),indicando que o servio foi executado com sucesso.
Aps compilado o servio, deve ser acessada novamente a pgina de ndice de servios(wsindex.apw), e verificar se o novo servio compilado l se encontra.
Testando o Servio
Ao acessar a pgina de ndice, e constatarmos a existncia do servio, devemos obter olink atravs do qual o WSDL deste servio est sendo fornecido, eutilizarmos de umaferramenta para gerar um 'Client' que possibilite o uso deste servio. possvel,inclusive, utilizar o Protheus IDE para gerar o fonte 'Client' para testar o servio; pormexiste a necessidade de criar uma funo para instanciar a classe 'Client' gerada,alimentar os parmetros e testar o servio.
A partir da verso Protheus 8, podemos apenas gerar um fonte 'Client' desta classe, ecompil-lo no mesmo repositrio do ambiente utilizado pelo WebServices 'Server', que
a prpria interface de ndice de Servios ir permitir o teste do mesmo.
7/22/2019 ADVPL - Web Services Com Protheus
43/140
Falhas de Carga dos Servios
Reviso: 06/05/2004
Abrangncia
Verso 7.10 Verso 8.11
Neste tpico so abordadas as mensagens de ocorrncias relacionadas carga dosservios.
Durante a inicializao do enginede Web Services, os servios compilados sovalidados, e um ambiente montado por threadpara o atendimento de solicitaes deprocessamento. Neste processo, existem ocorrncias, relacionadas montagem doambiente, que podem impossibilitar a operao dos WebServices como um todo; e
ocorrncias que podem invalidar apenas um servio, em caso ed inconsistncia dadeclarao do mesmo.
7/22/2019 ADVPL - Web Services Com Protheus
44/140
Erro de Estrutura : ARRAY OF emparametro de en...
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
XXX : Erro de Estrutura : ARRAY OF em parametro de entrada direto naosuportado.
Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando um parmetro [XXX] foi utilizado como parmetro de entrada
direto de um WebService, porm o mesmo foi declarado com tratamento de 'Array Of'.No suportado receber diretamente um array como parmetro de um mtodo deWebServices 'Server'.
Verifique e corrija o cdigo-fonte, e crie uma estrutura intermediria para encalsular oparmetro que deve ter tratamento de Array.
Erro de Estrutura : Estrutura
Indefinida.Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
[XXX] : Erro de Estrutura : Estrutura Indefinida.
Durante a etapade validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando uma propriedade da classe server foi especificado como sendo umaestrutura ( tipo no-bsico), porm a declarao da estrutura no foi localizada.
Verifique e corrija ocdigo-fonte e proceda com a declarao da referida estrutura.
7/22/2019 ADVPL - Web Services Com Protheus
45/140
Erro de Estrutura : Nome de EstruturaInvlido ...
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
[XXX]Erro de Estrutura : Nome de Estrutura Invlido -Tipo bsico conflitante.
Durante a etapade validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando o nome de uma determinada estrutura [XXX]foi especificado comum nome iguala um tipo bsico de informao. Esta ocorrncia invalida apenas o
servio que utiliza a determinada estrutura.
Verifique e corrija ocdigo-fonte e a declarao do tipo da estrutura.
Erro de Mtodo : Estrutura de Entradano encon...
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
[XXX] : [YYY] : Erro de Mtodo : Estrutura de Entrada no encontrada.
Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando um determinado mtodo [XXX] foi especificado com algum
parmetro de entrada [YYY],cuja declarao no foi encontrada como uma propriedadeno fonte construtor do servio.
Verifique e corrija o cdigo-fonte, e declare o parmetro YYY como uma propriedadeda classe XXX
7/22/2019 ADVPL - Web Services Com Protheus
46/140
Erro de Mtodo : Estrutura de Retornono encon...
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
[XXX] : [YYY] : Erro de Mtodo : Estrutura deRetorno no encontrada.
Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando um determinado mtodo [XXX] foi especificado com uma estrutura[YYY],cuja declarao no foi encontrada como uma propriedade no fonte construtor
do servio.
Verifique e corrija o cdigo-fonte, e declare a propriedade YYY como uma propriedadeda classe XXX
Erro de Mtodo : Estrutura de Retornono pode ...
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
[XXX] : [YYY] : Erro de Mtodo : Estrutura de Retorno no pode ser recebida comoparmetro.
Durante a etapa de validao dos servios,na carga dos WebServices, esta ocorrncia reproduzida quando um determinado mtodo [XXX] foi declarado para receber umaestrutura [YYY] e retornar a mesma estrutura [YYY] . Isto no suportado pelosWebServices do Protheus.
Verifique e corrija o cdigo-fonte.
7/22/2019 ADVPL - Web Services Com Protheus
47/140
Erro de Mtodo : Mtodo [XXX] doServio [YYY] ...
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Erro de Mtodo : Mtodo[XXX] do Servio[YYY] no declarado no Servio.
Durante a etapade validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando um determinado mtodo [XXX], referente o servio [YYY], foicodificado, porm no foi declarado no construtur do Web Service.Esta ocorrncia
invalida apenas o servio que utiliza a determinada estrutura.
Verifique e corrija ocdigo-fonte e proceda com a declarao do mtodo no construtordo servio.
Erro de Mtodo : Nome de MtodoInvlido - Tipo...
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
[XXX] Erro deMtodo : Nome deMtodo Invlido -Tipo bsico conflitante.
Durante a etapade validao dos servios, na carga dos WebServices, esta ocorrncia
reproduzida quando o nome de uma determinadamtodo [XXX]foi especificado comum nome igual a um tipo bsico de informao. Esta ocorrncia invalida apenas oservio que utilizao determinado mtodo.
Verifique e corrija ocdigo-fonte e a declarao do nome do mtodo.
7/22/2019 ADVPL - Web Services Com Protheus
48/140
Erro de Estrutura : Redundancia deEstruturas
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando temos uma cadeia de estruturas, compostas por tipos bsicos eoutras estruturas, e a declarao das estruturas entre em redundncia. Por exemplo,declaramos a estrutura ,que tem dentro dela uma outra propriedade que do tipo, ou a estrutura tm uma propriedade de tipo , e por sua vez tem uma
propriedade do Tipo .
Verifique e corrija o cdigo-fonte e corrija a declarao das estruturas envolvidas.
WSDL Server ONLOAD ERROR -Falha Interna na ...
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
WSDL Server ONLOAD ERROR -Falha Interna na Carga do WebService
Esta ocorrencia apresentada na tela de ndice dos WebServices ( wsindex.apw ),quandoalgum erro fatalocorra na carga dos WebServices. Os detalhes sobre a
ocorrncia fatal so mostrados no console do servidor Protheus, e gravados no arquivoerror.log do ambiente em uso.
7/22/2019 ADVPL - Web Services Com Protheus
49/140
Ocorrncias de Erro Fatal - AUTOMATICURLLOCATION FAILED
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Ao configurarmos um WebService 'Server', devemos especificar, atravs da chaveURLLOCATION , a url especfica para o acesso os servios.
Quando no definimos esta URL, a lib de WebServices identifica automaticamente sobqual hosto servio foi acessado. Esta operao no possvel quando o header HTTP
do pacote informe uma operao diferente de "GET" ou "POST",ou o servidor Protheusest sendo execudado em sua verso ISAPI, em conjunto com o Microsoft (R)Information Service.
Caso no seja possvel identificar o host sob o qual a chamada foi realizada, oWebService no processado, e o processamento abortado com a ocorrncia de erroacima.
7/22/2019 ADVPL - Web Services Com Protheus
50/140
Ocorrncias de Erro Fatal - BUILD [XXX]USING WEBSERVICES HTTPS NOTSUPPORTED
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Quandoda carga inicial dos WebServices 'Server', a configurao URLLOCATION criticada pela Lib. Caso seja especificado que o acesso ser realizado via 'HTTPS', e obuild atual do servidor Protheus utilizado ainda no suportaa utilizao do WebService
sob o protocoloHTTPS.
INVALID URLLOCATION [XXX] ON[YYY]
Reviso: 22/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Quando da configurao do servidor Protheus para WebServices, caso especificada aconfigurao URLLOCATION, porm a mesma no seja especificada com uma sintaxevlida, o processamento abortado na subida das Working Threadsdo servidor, comesta ocorrncia de erro fatal, indicando em [XXX] a url informada,e em [YYY] o nomedo arquivo de configurao do servidor Protheus.
Uma url considerada invlida, caso ela no seja iniciada com 'http://' ou 'https://', sejafinalizada com um caractere no-alfanumrico ou diferente de '/', ou possua caracteresacentuados ou espaos. So considerados vlidos apenas caracteres alfanumricos, e oscaracteres ':' (dois pontos), '.' (ponto), '/' (barra) e '-' (hfen).
Esta validao foi implementada na Infra-Estrutura de Web Services a partir da versode infra-estrutura 'ADVPL WSDL Server 1.031209'
7/22/2019 ADVPL - Web Services Com Protheus
51/140
Ocorrncias de Erro Fatal - REQUIREDReturn property [X] AS ARRAY OF [Y]IS ..
Reviso: 23/04/2004
Abrangncia
Verso 7.10 Verso 8.11
REQUIRED Return property [X] AS ARRAY OF [Y] IS EMPTY
Esta ocorrncia de erro, reproduzida quando do trmino do processamento de um
mtodo de um WebServices, na camada da LIB, quando da gerao do pacote 'SOAP'de retorno o 'Client' solicitante do servio.
Quando da identificao da propriedade [X] de retorno obrigatrio do mtodo , amesma deveria ser um 'Array' Advpl, contendo no mnimo um elemento; porm o arrayno continha nenhum elemento.
Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno esteja sendoalimentada.
7/22/2019 ADVPL - Web Services Com Protheus
52/140
Ocorrncias de Erro Fatal - REQUIREDReturn property [X] Type [Y] Unexpect...
Reviso: 23/04/2004
Abrangncia
Verso 7.10 Verso 8.11
REQUIRED Return property[X]Type [Y] Unexpected Valtype [Z]
Esta ocorrncia de erro, reproduzida quando do trmino do processamento de um
mtodo de um WebServices, na camada da LIB, quando da gerao do pacote 'SOAP'de retorno o 'Client' solicitante do servio.
Quando da identificao da propriedade obrigatria[X] de retorno do mtodo , amesma deveria ser alimentada com um contedo Advpl do tipo [Y], porm, ao invsdeste, ela continha um valor do tipo Advpl [Z].
Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno estejaalimentada com um contedo do tipo [Y], emconformidade com a declarao dapropriedade no servio.
7/22/2019 ADVPL - Web Services Com Protheus
53/140
Ocorrncias de Erro Fatal - Returnproperty [X] AS ARRAY Type [Y]Unexpected..
Reviso: 23/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Return property[X]AS ARRAY Type [Y] Unexpected Valtype [Z]
Esta ocorrncia de erro, reproduzida quando do trmino do processamento de um
mtodo de um WebServices, na camada da LIB, quando da gerao do pacote 'SOAP'de retorno o 'Client' solicitante do servio.
Quando da identificao da propriedade [X] de retorno do mtodo , a mesma deveriaser um 'Array' Advpl, contendo elementos do typo [Y], porm, ao invs da propriedadeser um do Tipo A (Array), ela continha um valor do tipo Advpl [Z].
Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno estejaalimentada com um array,
7/22/2019 ADVPL - Web Services Com Protheus
54/140
Ocorrncias de Erro Fatal - Returnproperty [X] AS OBJECT Type [Y]Unexpect ..
Reviso: 23/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Return property[X]ASOBJECT Type [Y] Unexpected Valtype [Z]
Esta ocorrncia de erro, reproduzida quando do trmino do processamento de um
mtodo de um WebServices, na camada da LIB, quando da gerao do pacote 'SOAP'de retorno o 'Client' solicitante do servio.
Quando da identificao da propriedade [X] de retorno do mtodo , a mesma deveriaser umaEstrutura ( Tipo Advpl 'O' -Objeto ) Advpl, do typo [Y], porm a propriedadede retorno continha um valor do tipo Advpl [Z].
Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno sejaalimentada com a respectiva estrutura, em conformidade com a declarao dapropridade da classe do servio.
7/22/2019 ADVPL - Web Services Com Protheus
55/140
Ocorrncias de Erro Fatal - Returnproperty [X] Type [Y] UnexpectedValtype ..
Reviso: 23/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Return property[X]Type [Y] Unexpected Valtype [Z]
Esta ocorrncia de erro, reproduzida quando do trmino do processamento de um
mtodo de um WebServices, na camada da LIB, quando da gerao do pacote 'SOAP'de retorno o 'Client' solicitante do servio.
Quando da identificao da propriedade [X] de retorno do mtodo , a mesma deveriaser alimentada com um contedo Advpl do tipo [Y], porm, ao invs deste, ela continha
um valor do tipo Advpl [Z].
Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno estejaalimentada com um contedo do tipo [Y], em conformidade com a declarao dapropriedade no servio.
7/22/2019 ADVPL - Web Services Com Protheus
56/140
Ocorrncias de Erro Fatal - UNKNOWERROR : EMPTY HTTP RETURN
Reviso: 29/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Quando do processamento de uma requisio de um mtodo de WebServices 'Server',so executadas consistncias de pr-processamento e ps-processamento. Todas asconsistncias internas realizadas tm uma mensagem de retorno. Quando do final daexecuo do servio, independentemente de ocorrer um processamento com sucesso oucom falha ( SoapFault), verificado se o tratamento efetuado gerouum pacote com a
mensagem de retorno.
Caso esta ocorrncia seja reproduzida, ela indica que ocorreu uma falha no tratada, ouuma impossibilidade de gerao do pacote de retorno. At o momento, esta ocorrnciano foi reproduzida sob nenhuma condio.
7/22/2019 ADVPL - Web Services Com Protheus
57/140
Ocorrncias de Erro Fatal - [SVC] :[METHOD] as [X] : Tipo Inesperado deRet..
Reviso: 06/05/2004
Abrangncia
Verso 7.10 Verso 8.11
[SVC] : [METHOD] as [X] : Tipo Inesperado de Retorno do Mtodo.
A ocorrncia de erro acima reproduzida, quando do trmino da execuo de um
mtodo de uma classe 'Server' de WebServices. A LIB espera um valor booleano ( .T.ou .F. ) de retorno efetivo do mtodo. Caso o retorno efetivo no seja booleano, oprocessamento abortado com a ocorrncia acima, identificando o servio chamado em[SVC], o mtodo em [METHOD], e o tipo do retorno efetivo retornado em [X].
Verifique o cdigo-fonte do mtodo do servio, e certifique-se que o retorno efetivo domtodo seja sempre .T.ou .F.
7/22/2019 ADVPL - Web Services Com Protheus
58/140
Aplicaes Protheus 'Client' deWebServices
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 processamentodo Servio, realizar a chamada, e tratar o pacote de retorno do servio e suas respectivasexcesses.
Embora existam Web Services que podem ser acessados via Http direto, apenaspassando parmetros via URL, o client de Web Services do Protheus tm seu foco erecursos direcionados apenas a servios que possuam interface de comunicao querealize POST de pacotes de dados XML em formato SOAP. O Protheus possuiferramentas 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 Protheusgere automaticamente, em Advpl, uma classe 'Client' para a comunicao e utilizaodo mesmo.
Para tal, basta obtermos o endereo internet ( URL) do WSDL desejado, criar um novoarquivo-fonte, e acessar o menu 'Ferramentas -> Gerar Cliente WebServices...'. Paracada servio que se tenha a necessidade de gerao de um fonte client, recomenda-sefortemente que cada fonte client seja gerado em um arquivo independente e exclusivopara 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 servidorProtheusque ir buscar o documento WSDL solicitado. De modo que, a estaoservidora utilizada no ambiente deve ter acesso o endereo solicitado.
7/22/2019 ADVPL - Web Services Com Protheus
59/140
Aplicaes Protheus 'Client' de WebServices- 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 acessadosatravs 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 ) oWSDL de uma maneira diferente . O WSDL de alguns servios restritos ( como porexemplo o servio de busca na base de dados do Google ) so disponibilizados emarquivo ASCII, enviados por e-mail, apos um cadastro no site e autorizao da empresapara 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 sejaacessado atravs de um Web Browser ( Internet .Explorer., por exemplo ), ser exibido
no browse um documento XML correspondendo a definio do servio.
http://localhost/SERVERTIME.apw?WSDL7/22/2019 ADVPL - Web Services Com Protheus
60/140
Aplicaes Protheus 'Client' de WebServices- 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 clientusando o Assistente do IDE
Ao ser gerado um fonte clientpara um Web Service, este fonte conter asdefinies 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 preferencialmenteser gerado e compilado em um arquivo exclusivo, destinado unica e exclusivamente aeste cdigo. E, por tratar-se de uma classe Advpl gerada a partir da definio de umservio, no deve ser inserida e/ou alterada nenhuma das definies geradas peloassistente, pois as mesmas sero perdidas caso o fonte seja gerado novamente .
Para gerao do fonte clientem Advpl para utilizar este servio, necessriocriar um novo arquivo .PRX no IDE, especificamente para conter as classes desteservio . Ento, deve ser acessado o menu Ferramentas, opo Gerar CienteWebservices . 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 sermostrado um texto semelhante ao abaixo :
Estabelecendo conexo com o server...Por favor aguarde. Obtendo descrio do WebService...Finalizando conexo com o server...Ok
http://localhost/SERVERTIME.apw?WSDL7/22/2019 ADVPL - Web Services Com Protheus
61/140
E, na janela do novo arquivo criado, dever ser criado um cdigo-fontesemelhante ao mostrado abaixo :
#INCLUDE 'PROTHEUS.CH'
#INCLUDE 'APWEBSRV.CH'
---header do servio ---/*
================================================================
===============
WSDL Location http://localhost/SERVERTIME .apw?WSDLGerado em 12/30/02 17:21:29
Observaes Cdigo-Fonte gerado por ADVPL WSDL Client 1.021217 BAlteraes neste arquivo podem causar funcionamento incorreto
e sero perdidas caso o cdigo-fonte seja gerado novamente.
================================================================
=============== */
/* -------------------------------------------------------------------------------
WSDL Service WSSERVERTIME
-------------------------------------------------------------------------------*/
---declarao da Classe clientdo 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 alimentaas propriedades de retorno do metodo, contendo os encapsulamentos necessrios para
tratamento deexcesses ---WSMETHOD GETSERVERTIME WSSEND NULLPARAM WSRECEIVE cGETSERVERTIMERESULT WSCLIENT
WSSERVERTIME
Local cSoap := '', oXmlRet
BEGIN WSMETHOD
DEFAULT ::_URL := 'http://localhost/SERVERTIME.apw'
cSoap += ''cSoap += ''
oXmlRet := SvcSoapCall( Self,cSoap,;'http://localhost/GETSERVERTIME',;'DOCUMENT','http://localhost/',)
http://localhost/',http://localhost/GETSERVERTIME',;http://localhost/'%3E'http://localhost/SERVERTIME.apw'http://localhost/SERVERTIME.apw?WSDL7/22/2019 ADVPL - Web Services Com Protheus
62/140
::cGETSERVER TIME RESULT := xGetInfo( oXmlRet,'_GETSERVERTIMERESPONSE:_GETSERVERTIMERESULT:TEXT', '' )
END WSMETHOD
oXmlRet := NIL
Return .T.
O fonte acima constitui uma Classe em Advpl, gerada para realizar a interfacecom a classe original publicada no Server, j realizando os tratamentos adequados pararealizar a comunicao via httpcom o servidor onde o servio est publicado. Valeobvervar que, as linhas em negrito no fonte acima no foram inseridas pelo assistente doIDE, mas acrescentadas a este documento para fins didticos.
O cabealho do fonte contm informaes sobre a localizao do WSDLutilizado para a gerao do fonte, data e hora de gerao e verso do engine de WebServicesutilizado . Logo abaixo, a declarao de uma classe clientde Web Services(WSCLIENT WSSERVERTIME ), com o mtodo new() para inicializao daspropriedades advpl da classe . E, em seguida, a declarao do mtodo de busca de
Horrio ( WSMETHOD GETSERVERTIME ), que no envia parmetro algum, eretorna o horrio atual do server em :: cGETSERVERTIMERESULT, com todos ostratamentos necessrios embutidos.
7/22/2019 ADVPL - Web Services Com Protheus
63/140
Aplicaes Protheus 'Client' de WebServices- 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 parautilizar a classe de Web Servicesclientpara obter o horrio no servidor.
1 #INCLUDE 'PROTHEUS.CH'2
3 User Function TestClient()4 Local oSvc := NIL
5
6 oSvc := WSSERVERTIME():New()7
8 If oSvc:GETSERVERTIME()
9 alert('Horrio no Servidor : '+ oSvc:cGETSERVERTIMERESULT)10 Else11 alert('Erro de Execuo : '+GetWSCError())12 Endif
13
14 Return
Linha 1 declarada a utilizao do Include Protheus.ch, contendo as definies doscomandos ADVPL e demais constantes
Linha 3 Inicia-se a definio da User Function para utilizar o Web ServiceLinha 4 Uma varivel local declarada para conter o Objeto do Web ServiceclientLinha 6 Utilizando-se do servio, a varivel oSvc alimentada com uma onva instncia
do Web Servicesclient, obtida atravs da sintaxe():New()
Linha 8 executado o mtodo GetServerTime a partir do Objeto do servio oSrv, sempassar qualquer parametro. O retorno de um mtodo do clientpode 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 aocorrncia de erro, deve ser utilizada a funo GetWSCerror(), que retorna umastring com o resumo da ocorrncia .
Linha 13 O programa de teste finalizado com um Return
7/22/2019 ADVPL - Web Services Com Protheus
64/140
Aplicaes Protheus 'Client' de WebServices- 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 Serviceesteja no ar e funcionando, e o fonte clientseja devidamentecompilado e sem erros, o resultado esperado uma janela semelhante a mostrada
abaixo:
No ambiente montado para teste, o Servidor de Web Servicese o clientestono Protheus, compilados no mesmo Repositrio de Objetos . Para fins didticos,
possvel simular uma ocorrncia de falha no client, ao desabilitar o ServerHTTP doProtheus (colocando enable=0 na chave [http] do arquivo de consigurao do servidor),re-iniciar o Server Protheus, e executar o programa clientnovamente . Deve ser obtidauma tela semelhante a exemplificada abaixo :
7/22/2019 ADVPL - Web Services Com Protheus
65/140
Aplicaes Protheus 'Client' de WebServices- 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 clientfuncionandoperfeitamente . Agora, possvel imaginar que, durante o desenvolvimento e testes doclientdo servio, faam-se necessrias determinadas informaes internas as rotinas
de execuo do servio no clientAdvpl . Para tal, foi criada uma funo que permitedefinir em tempo de execuo, um nvel de detalhamento de informaes adicionaisrelacionadas ao Web Service; informaes estas que sero mostradas no Console doServer Protheus ( caso habilitado ) . a Funo para definir o nvel de detalhe chama-seWSDLDbgLevel(), e recebe um nmero como parmetro :
0 ( default ) Sem informaes adicionais.
1 Apenas String SOAP de retorno do Server.
2 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 doservidor 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/SERVERTIM E.apw /DOCUMENT
NameSpace http://automan:8000/webservice/
SoapAction http://automan:8000/webservice/GETSERVERTIME
Called from GETSERVERTIME ( 137)Called from U_TESTCLIEN T ( 10)----------------------------------SOAPSEND -----------------------------------
http://schemas.xmlsoap.org/soap/enhttp://www.w3.org/2001/XMLSchema'http://www.w3.org/2001/XMLSchema-instance'http://automan:8000/webservice/GETSERVERTIMEhttp://automan:8000/webservice/http://automan:8000/webservice/SERVERTIME.apw7/22/2019 ADVPL - Web Services Com Protheus
66/140
------------------------------------------------------------------------------- ---------------------------------POST RETURN ---------------------------------10:37:10
-------------------------------------------------------------------------------
Fim Thread (siga0984, AUTOMAN) BytesIn 73 BytesOut 75O 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 ) aoServidor, e o conteudo em amarelo( POST RETURN ) informa o contedo do pacoteSoap devolvido pelo Server referente a esta solicitao.
Quando ocorre um erro qualquer, relacionado a execuo do clientWebServices, o mtodo chamado retorna .F., e o erro pode ser recuperado atravs da funoGetWSCerror(), vista anteriormente . Para cada excesso prevista no client, existe umcdigo de erro correspondente, todos eles prefixados com WSCERR . A maioria dasocorrncias est relacionada a gerao do Cdigo fonte do clientAdvpl utilizado-se oIDE. Todas as ocorrenctas de excesso tratadas peo Web ServicesclientAdvpl estorelacionadas no Tpico Web ServicesclientCdigos de Erro .
http://automan:8000/webservice/'%3E%3CGETSERVERTIMERESULT%3E10:37:1http://schemas.xmlsoap.org/soap/envelope/'%3E%3Csoap:Body%3E%3CGETSERVERThttp://www.w3.org/2001/XMLSchema'http://www.w3.or/http://automan:8000/webservice/'%3E7/22/2019 ADVPL - Web Services Com Protheus
67/140
Aplicaes Protheus 'Client' de WebServices- 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 dadoslistados abaixo.Parapermitir a manipulao decada tipo, utilizando variveis Advpl, so utilizados os tipos bsicos do Advpl paratratar 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
INTINTEGERBYTEFLOATDOUBLEUNSIGNEDLONGUNSIGNEDINTDECIMAL
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
STRINGDATETIMECHAR (**)BASE64BINARY
(**) O tipo CHAR corresponde uma string, contendo o nmero do caracterecorrespondente tabela ASCII
Os tipo abaixo disponibilizado em Advpl atravs de uma varivel de tipo 'L' Logica
BOOLEAN
7/22/2019 ADVPL - Web Services Com Protheus
68/140
WSCERR000 / WSDL no suportado.Existe mais de ..
Reviso: 22/04/2004
Abrangncia
Verso 8.11
[WSDL no suportado. Existe mais de um servio declarado.]
Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. Por definio, um WSDL deve conter um e apenasum servio declarado, com um ou mais mtodos . Caso sejam identificados mais de um
servio no mesmo WSDL, no momento da gerao do fonte, o processo abortado, oWSDL considerado invlido, e o fonte client no gerado.
7/22/2019 ADVPL - Web Services Com Protheus
69/140
WSCERR001 / No hSOAP:BINDINGS para a gerao ..
Reviso: 22/04/2004
Abrangncia
Verso 8.11
WSCERR001 / No h SOAP:BINDINGS para a gerao do Servio.
Durante a gerao do codigo-fonte para client Advpl, a partir de uma definio deservio (WSDL), uma vez identificado o servio, o gerador de cdigo procura adeclarao dos BINDINGS no WSDL. Caso esta declarao no esteja presente, a rotina
considera o WSDL incompleto, e aborta o processo de gerao de cdigo com estamensagem.
7/22/2019 ADVPL - Web Services Com Protheus
70/140
WSCERR003 / [XXX / YYY]Enumeration no suportado
Reviso: 22/04/2004
Abrangncia
Verso 8.11
WSCERR003 / [XXX / YYY] Enumeration no suportado
Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao,so analisados todos os
parmetros e estruturas utilizadas pelos mtodos do servio. Quando encontrada umaestruturabsica ( SimpleType), onde foi especificado um 'enumeration' ( lista deparametros vlidos pr-determinada ), so suportados os seguintestipos bsicos deparmetros, listados abaixo :
STRINGFLOATDOUBLEDECIMALINTINTEGERLONGUNSIGNEDINTUNSIGNEDLONG
Caso o WSDL contenha um 'enumeration', utilizando um tipo de dado diferente dosdeclarados acima, oprocesso de gerao de fonte abortado com aocorrncia de erroacima, onde o 'enumeration' no suportado identificado em e ,correspondendo o nome do parmetro e tipo utilziado, respectivamente.
7/22/2019 ADVPL - Web Services Com Protheus
71/140
WSCERR004 / NAO IMPLEMENTADO( 001 / / ...
Reviso: 22/04/2004
WSCERR004 / NAO IMPLEMENTADO ( 001 / / WSDLTYPE_NAME )
Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas utilizadas pelos mtodos do servio,at que todas as estruturasutilizadas sejam processadas.
Quando deste processamento, uma estrutura contenha um determinado elemento, queaponte para uma outra estrutura, e esta no seja encontrada no WSDL ( ocorrncia
= A ), ou seja encontrada -porm registrada no como uma estrutura (complextype)- (ocorrncia = B ), o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a estrutura pendente em.
7/22/2019 ADVPL - Web Services Com Protheus
72/140
WSCERR006 / WSDL invlido ou nosuportado.
Reviso: 22/04/2004
Abrangncia
Verso 8.11
WSCERR006 / WSDL invlido ou no suportado.
Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas utilizadas pelos mtodos do servio,at que todas as estruturas
utilizadas sejam processadas.
Quando deste processamento, um parmetro de primeiro nvel (message) do WSDL forespecificado sem nome, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima.
7/22/2019 ADVPL - Web Services Com Protheus
73/140
WSCERR007 / WSDL invlido ou nosuportado.
Reviso: 22/04/2004
Abrangncia
Verso 8.11
WSCERR007 / WSDL invlido ou no suportado.
Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas utilizadas pelos mtodos do servio,at que todas as estruturas
utilizadas sejam processadas.
Quando deste processamento, um parmetro de primeiro nvel (message) do WSDL forespecificado sem definio de tipo, o WSDL considerado invlido, e o processo degerao abortado com a mensagem acima.
7/22/2019 ADVPL - Web Services Com Protheus
74/140
WSCERR008 / Retorno NULLPARAMinvlido.
Reviso: 22/04/2004
Abrangncia
Verso 8.11
WSCERR008 / Retorno NULLPARAM invlido.
Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas utilizadas pelos mtodos do servio,at que todas as estruturas
utilizadas sejam processadas.
Quando deste processamento, um parmetrode retorno do WSDL seja identificadocomo 'retorno nulo', o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima.
7/22/2019 ADVPL - Web Services Com Protheus
75/140
WSCERR009 / INTERNAL ERROR (X)
Reviso: 29/04/2004
WSCERR009 /INTERNAL ERROR(X)
Esta uma ocorrncia de erro interna do 'engine' de gerao de cdigo-fonte Advpl, noreproduzida at o momento. Quando do processamento de um WSDL, os parmetros emensagens especificadas no WSDL so identificados internamente como parmetros deentrada , parmetro de sada , ou entrada e saida. Caso, aps a anlise inicial deparmetros, algum parmetro no seja enquadrado nestas definies, o processamentode gerao abortado com a ocorrncia acima.
7/22/2019 ADVPL - Web Services Com Protheus
76/140
WSCERR010 / [STRUCT_TYPE]Estrutura / Tipo inc ...
Reviso: 22/04/2004
Abrangncia
Verso 8.11
WSCERR010 / [STRUCT_TYPE] Estrutura / Tipo incompleto
Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas utilizadas pelos mtodos do servio, at que todas as estruturas
utilizadas sejam processadas.
Quando deste processamento, caso uma estrutura complexa no contenha aespecificao de seus elementos internos ea mesma no contenha nenhuma refernciaao SCHEMA ou outra estrutura, o WSDL considerado invlido, e o processo degerao abortado com a mensagem acima, informando em [STRUCT_TYPE], o nomeda estrutura incompleta.
7/22/2019 ADVPL - Web Services Com Protheus
77/140
WSCERR011 / Retorno NULLPARAMinvlido.
Reviso: 22/04/2004
Abrangncia
Verso 8.11
WSCERR011 / Retorno NULLPARAM invlido.
Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas uti