Histórico da Página

Aplicações Protheus 'Client' de Web Services

Definição de client

Quando um Web Service 'Server' é criado e disponibilizado, junto é disponibilizada a definição do serviço, argumentos, estruturas e retornos (WSDL).

Para utilizar um Web Service, é necessário montar um programa client que seja capaz de montar um 'envelope' SOAP com os dados necessários ao processamento do serviço, realizar a chamada e tratar o pacote de retorno do serviço e suas respectivas excessões.

Embora existam Web Services que podem ser acessados via HTTP direto, apenas passando parâmetros via URL, o client do Web Services do TOTVS | Application Server têm seu foco e recursos direcionados apenas a serviços que possuam interface de comunicação que realize POST de pacotes de dados XML, em formato SOAP (a versão 1.1 da especificação SOAP foi utilizada como base para implementação do toolkit de Web Services do Microsiga Protheus). O TOTVS | Application Server possui ferramentas e infraestrutura incorporadas que pemitem esta integração.

Geração do client em AdvPL

No TOTVS | Development Studio, encontra-se disponível, no menu Ferramentas, a opção para que, através de um link para a obtenção do documento WSDL de um serviço, o TOTVS | Application Server gere automaticamente, em AdvPL, uma classe client para a comunicação e utilização do mesmo.

Para isso, é necessário obter o endereço internet (URL) do WSDL desejado, criar um novo código-fonte e acessar no menu Ferramentas + Gerar Cliente WebServices.... No entanto, para cada serviço que se tenha necessidade de gerar um código-fonte client, recomenda-se que cada código-fonte client seja gerado em um arquivo independente e exclusivo para este fim, e que de forma alguma este código-fonte gerado, pelo assistente, seja alterado.

Como a especificação SOAP 1.1 foi utilizada como base para a implementação da interface Client de Web Services, usar um WSDL fornecido com versão a partir de 1.2 pode não ser suportado na íntegra, gerando ocorrências desde falha na geração do fonte client em AdvPL, até a geração ou funcionamento incompletos.

Em casos especiais, pode ser necessária alguma alteração no código-fonte client gerado, caso necessário atender alguma necessidade específica da aplicação Server de Web Services não contemplada de modo nativo pela implementação de Web Services do TOTVS | Application Server. Neste caso, deve-se tomar muita atenção e documentar o código-fonte, pois caso este fonte tenha que ser gerado novamente por qualquer razão, a alteração realizada é perdida e, se ainda necessária, deverá ser realizado novamente no código regerado manualmente.

Requisitos básicos para geração do client em AdvPL

O processo de geração do código-fonte é disparado através do TOTVS | Development Studio, porém, é o servidor TOTVS | Application Server que buscará o documento WSDL solicitado. De modo que, a estação servidora utilizada no ambiente deve ter acesso ao endereço solicitado. É importante salientar que, o processo de busca da URL informada é disparado pelo TOTVS | Development Studio, mas a operação é realizada através do TOTVS | Application Server. Logo, a máquina onde o serviço do TOTVS | Application Server está sendo executado deve ter acesso à URL informada.

Geração de fonte client para WSDLs disponibilizados em arquivo

Existem fornecedores de serviços para Web Services que fornecem os arquivos contendo as definições (WSDL) para a geração dos clients. O TOTVS | Development Studio suportam a geração de fonte client em arquivo. PAra tal, deve-se disponibilizar o arquivo em uma pasta a partir do RootPath do ambiente (environment) configurado no TOTVS | Development Studio, e informar na caixa de diálogo da URL para a geração do código-fonte, o path do arquivo, sempre inciado com  "\"  (barra inversa) , seguido do path e nome do arquivo no servidor a ser utilizado para a geração.

Por exemplo, caso o arquivo contendo o WSDL chama-se "meuservico.txt", e ele seja copiado para uma pasta chamada "WSDL", que fica a partir do RootPath do ambiente em uso no TOTVS | Development Studio, a URL informada no TOTVS | Development Studio para gerar o código-fonte client deve ser  "\wsdl\meuservico.txt" . O TOTVS | Development Studio não vai criticar a extensão do arquivo, mas sim o conteúdo do mesmo. Ele deve conter um arquivo XML no formato WSDL.

Geração de fonte client para WSDLs publicados com autenticação e/ou conexão segura ( HTTPS )

A engine de conexão client HTTP do TOTVS | Application Server suporta conexão com URLs com HTTPS, inclusive para a geração de fonte client de Web Services. Existem apenas restrições quando a URI dos Web Services exigir autenticação (usuário e senha) para baixar o WSDL, e/ou seja uma conexão HTTPS que exiga um uso de certificado client específico.

No caso da autenticação, é possível acessar a URL onde o WSDL está publicao através de um Web Browser, fazer a autenticação através do Browser, e ao acessar o WSDL, salvá-lo em arquivo, copiar para uma pasta a partir do RootPath do TOTVS | Application Server, e fazer a geração do client pelo TOTVS | Development Studio informando o arquivo em disco. Este mesmo procedimento também pode ser aplicado quando o WSDL está publicado em um endereço HTTPS que requer uso de certificado client.  Basta conseguir acessar o conteúdo do WSDL no Web Browser, acessá-lo em disco, e fazer a geração a partir do arquivo em disco. Caso o Web Service possua dependências (imports) que estejam publicados, a geração é um pouco mais complicada, pois existe a necessidade de fazer download de todos os imports necessários, e compilar um e apenas um arquivo contendo o WSDL principal com todos oos imports para a geração do fonte client ser feita com sucesso.

Ainda quanto à geração de clients onde o WSDL está publicado com conexão segura (HTTPS) que exiga o uso de um certificado client especifico, é possível gerar pelo TOTVS | Development Studio, desde que o TOTVS | Application Server seja configurado para uso do certificado, como se o certificado fosse utilizado para conexão entre remote e server ( vide configuração da seção [SSLCONFIGURE] do TOTVS | Application Server). Basta configurar o certificado no TOTVS | Application Server, subir o serviço, e proceder com a geração do fonte client pelo TOTVS | Development Studio, informando a URL.