Lidando com SOAP em Node.js

Se você começou a programar nos últimos 5 anos talvez nem saiba do que estou falando. Ou se sabe, é culpa de algum sistema legado com o qual você tem de lidar. Não te culpo por isso e “tamo junto”.

SOAP, ou Simple Object Access Protocol (não confundir com SOA), é um protocolo para criação de serviços web distribuídos e descentralizados, os famosos web services, que permitem a troca de informações entre sistemas, usando o formato XML. Eu não sei quando isso começou, mas a versão mais recente é de 2007 (1.2) e foi a forma mais popular de conectar sistemas na primeira década dos anos 2000, antes do surgimento do protocolo REST que incentivou as web APIs com JSON e mais tarde os micro serviços, formas mais leves para trocar informações entre sistemas pela web.

Todas as tecnologias web e mobile mais recentes oferecem suporte nativo (ou próximo disso) para lidar com Web APIs REST, mas pouco se fala de conexões com SOAP. O intuito deste tutorial é justamente ajudar quem precisa lidar com Node no client e SOAP no server.

#1 – Preparando o projeto

Este tutorial é intermediário e espera que você já saiba programar em Node.js. Caso ainda não possua esse conhecimento básico, conheça meus livros e meu curso.

Dito isso, crie um novo projeto na sua máquina com o nome de projeto-soap, crie um index.js vazio, rode um npm init para criar o package.json e instale a dependência do pacote Node SOAP que vamos utilizar, como abaixo:

Neste projeto, vamos criar um cliente que vai consumir um Web Service SOAP aberto e gratuito, disponível na Internet. Vou usar aqui, para fins de estudo o WS Dilbert, disponibilizado publicamente pela GComputer, cujo endereço é http://www.gcomputer.net/webservices/dilbert.asmx, mais especificamente o Web Method Daily Dilbert, que espera uma data como argumento e retorna uma frase como resposta, do famoso cartoon Dilbert.

Se você não está familiarizado com a documentação de Web Services SOAP, não é muito difícil de entender, desde que esteja minimamente acostumado com XML. Basicamente cada requisição, que pode ser enviada via HTTP (mais comum) ou RPC, é envelopada com seus argumentos e meta-informações em uma estrutura XML e retornada no mesmo formato, com seu valor de retorno e meta-informações. Por utilizar o formato XML, requests/responses SOAP geralmente são mais onerosos que seus equivalentes RESTful com JSON.

Estrutura SOAP
Estrutura SOAP

Para que clientes web consigam se comunicar com web services é necessário que eles entendam essa estrutura de comunicação XML, o que se faz através da leitura e interpretação do WSDL, ou Web Service Description Language, que fica disponível sempre no mesmo endereço do WS, apenas colocando o respectivo parâmetro no final: http://www.gcomputer.net/webservices/dilbert.asmx?wsdl

Dito isso e com a URL do WSDL em mãos, vamos iniciar a codificação do nosso cliente Node.

#2 – Criando o SOAP client

Fazer um SOAP client usando o pacote node-soap é muito fácil e nem dá para acreditar na trabalheira que é fazer sem um pacote profissional como esse.

Vamos começar criando um cliente através da conexão da biblioteca com o endereço do WSDL do nosso webservice, como abaixo:

Este código é bem simples e auto-explicativo, onde carregamos o pacote soap, a URL do WSDL e usamos a function createClient passando a url pra ela. Se tudo der certo, deve imprimir o conteúdo do objeto client no console.

O próximo passo, uma vez que temos um cliente SOAP instanciado e configurado para o WSDL de um web service em questão, é chamarmos algum de seus web methods. Ao acessar a página do web service encontramos dois deles, como mostra na imagem abaixo.

Web Service Dilbert
Web Service Dilbert

Temos dois WebMethods neste Web Service, o DailyDilbert e o TodaysDilbert (atenção à caixa alta e baixa, para chamar corretamente). Nós vamos usar o primeiro deles que, se clicarmos no mesmo (ou consultando diretamente o WSDL) vemos que ele espera apenas um parâmetro: ADate e retorna apenas um elemento: DailyDilbertResult, como mostrado na imagem abaixo.

WebMethod
WebMethod

Sendo assim, em nosso client SOAP, basta chamarmos esta function passando o argumento esperado e teremos o retorno desejado, como abaixo.

Coloque pra rodar e você vai ver que funciona. Ou quase. Infelizmente este webservice do Dilbert consome um site que não funciona mais e ele vai te retornar uma mensagem de erro dentro do DailyDilbertResult. 🙁

Eu demorei tanto tempo para terminar de escrever este tutorial que o site em questão mudou, hahaha. Mas não tem problema, se você receber uma mensagem de que não foi possível criar um canal seguro SSL, é porque você conseguiu se comunicar corretamente com o WebService, ele é que não conseguiu se comunicar com o site da comics.com onde ele pegava as frases do Dilbert.

Caso venha alguma coisa no objeto err, aí sim é um erro de verdade.

Eu cheguei a pensar em usar outro web service SOAP público, mas eles são raros hoje em dia e esse cumpre o papel de fazer a troca de mensagens corretamente, então fiquei com ele mesmo gerando uma única mensagem sempre. Acabei achando esse aqui depois que já tinha terminado de escrever o tutorial, então use ele como um exercício, pra ver se realmente aprendeu.

Então é isso por hoje. Tutorial curto e objetivo mas tenho certeza que vai ajudar quem estiver tendo que comunicar Node com SOAP. A título de curiosidade, não é incomum em apps mobile ter uma camada intermediária que faz esta tradução de SOAP pra REST para que o app possa trabalhar sempre apenas com REST.

Um abraço e sucesso!

Prof. Luiz

Curtiu o post? Então clica no banner abaixo e dá uma conferida no meu curso sobre programação web com Node.js!

Curso Node.js e MongoDB

Migrando XML para SQL Server com Entity Framework

Download do Código-Fonte

O objetivo deste post é ajudar os leitores a realizar uma tarefa muito penosa e que por mais de uma vez eu já tive de fazer: migrar bases de dados XML para algum banco de dado Entidade-Relacional, como SQL Server, MySQL, etc. O cenário é o seguinte: por algum motivo você tem um arquivo XML contendo dezenas, centenas, MILHARES de informações muito úteis para seu sistema (como um arquivo contendo todas as cidades brasileiras, por exemplo) mas não-curte/não-quer usar Linq To SQL para manipular o XML como se fosse uma base de dados. O que você quer na verdade é apenas pegar aquelas informações e colocar em seu banco de dados favorito. Cadastrar tudo na mão usando Inserts? ‘Tá maluco? Este é o objetivo do post de hoje: como migrar um XML para uma base de dados, como exemplo, o SQL Server.

Veremos neste post:

  1. Ingredientes
  2. Preparativos
  3. Mãos à obra
  4. Considerações Importantes

Vamos lá!

Ingredientes

  • Nós vamos precisar de um Visual Studio 2010 (pode ser a excelente versão Express distribuída gratuitamente neste link).
  • Também iremos utilizar uma base de dados Entidade-Relacional de sua preferência. Em nosso exemplo utilizaremos o SQL Server 2008 R2 (também possui versão Express gratuita neste link). Se for utilizar outra base como Oracle, Postgre SQL ou MySql, não esqueça de baixar seu conector .NET nos sites dos desenvolvedores desses bancos para que o Visualo Studio reconheça os mesmos.
  • Um arquivo XML contendo muitas informações úteis que você deseja inserir no banco. No exemplo utilizaremos nosso Estados.xml, disponibilizado no post anterior.
  • Muita vontade de ler este blogueiro chato!

Preparativos

Abra seu VS2010 e crie um novo projeto do tipo Console Application.

Nada impede que você utilize outro projeto, é apenas mania minha criar Consoles Applications para scripts desse tipo.

A receita aqui é velha: File -> New | Project -> Visual C# | Windows | Console Application. Dê o nome que quiser (Xml2Bd no meu caso) e toca ficha na criação. Note que vamos deixar a versão do Framework como 4, conforme o padrão do VS2010.

Porque não podemos utilizar na versão 3.5? Duas palavras: Entity Framework.

O Entity Framework surgiu como uma feature adicional ainda durante a versão 3.0 do Framework .NET e foi incorporado definitivamente na versão 3.5, porém (sempre tem um porém…) era uma porcaria.

Isso mesmo, a versão inicial do EF possui muitos bugs largamente conhecidos entre a comunidade de desenvolvedores como rastreamento de objetos, contexto de objetos, desenvolvimento em N camadas e por aí vai. Boa parte desses bugs foram solucionados na nova versão, presente no Framework 4. Por isso você está fazendo um favor a si mesmo se não perder tempo tentando usar o EF do Framework 3.5, vai por mim.

Este tutorial espera que você tenha os conhecimentos necessários para criar sozinho uma base de dados no SQL Server utilizando o fantástico SQL Server Management Studio (se estiver com preguiça, use o script SQL pronto que deixei dentro da Solution para download no início deste tuto).

Você precisará de um banco de dados com o nome de Xml2Bd contendo uma única tabela Estado (o singular é proposital mas não obrigatório) com as seguintes colunas: ID (int, PK), IDCapital (int), Sigla (char[2]) e Nome (nvarchar[50]). Este é o banco onde serão armazenados os dados do XML.

Se for fazer este exemplo com o xml de cidades também, não esqueça de adicionar uma tabela Cidade no banco contendo as devidas colunas. A figura abaixo mostra como seu banco deve se parecer para que o script que criaremos a seguir funcione corretamente.

Note que não criei o relacionamento das tabelas, pois isso faria com que não conseguíssemos inserir Estados antes de cidades e vice-versa por causa das restrições de Foreign Keys. Também não deixei os IDs das tabelas como auto-incremento pois no próprio XML já está contido os IDs de cada registro.

O próximo passo é adicionar o arquivo XML ao seu projeto.

Crie uma pasta XML e jogue lá dentro o dito-cujo, no nosso caso, o Estados.xml. Sem figura para esta etapa, todo mundo está careca de saber que basta clicar o botão direito do mouse sobre o projeto e ir em Add | New Folder para criar a pasta e em Add | Existing Item para adicionar o arquivo na pasta.

No passo seguinte (ok, desta vez coloco figura) adicione um novo item ao projeto seguindo o caminho Add | New Item -> Visual C# | Data | ADO.NET Entity Data Model. Coloque o nome de ContextoDados e clique em Add. Este arquivo com a extensão .EDMX nada mais é do que um mapeador objeto-relacional. Só isso.

Ok eu explico: esse arquivo .EDMX com o nome de ContextoDados conterá informações sobre o banco de dados que você criou no passo anterior, ele vai mapear cada uma das tabelas que existem lá e criar classes para elas, facilitando o manuseio. Através dos próximos passos você vai entender isso melhor.

Iniciará o Entity Data Model Wizard, um assistente para mapeamento do seu banco. No primeiro passo deixe a opção “Generate from Database” marcada e clique em Next. Na tela seguinte (Choose your data connection), clique em “New Connection” para adicionar uma conexão com seu banco de dados (criado lá no início, lembra?) ou apenas selecione ela no ComboBox se estiver aparecendo (meu caso). Clique em Next.

Em seguida (Choose your database objects) você deve selecionar quais objetos do seu banco você deseja mapear. No nosso caso, selecione apenas a tabela Estado (ou Cidade também, se a incluiu no banco como eu) e mantendo as demais configurações por padrão, clique em Finish.

Ao concluir o processo, serão adicionadas algumas referências ao seu projeto, bem como o arquivo EDMX citado anteriormente. O VS2010 também já deixará o dito arquivo aberto para que você visualize o resultado do mapeamento em um diagrama semelhante aos ER tradicionais. Agora você tem o XML com os dados e o banco devidamente mapeado para objetos (cortesia do EF), go code!

Mãos à Obra!

Depois dessa preparação que mais pareceu tarefa de setor de infraestrutura (NNF na gíria deles), vamos finalmente ao que interesse: o código!

Basicamente o que faremos aqui será o seguinte: analisaremos o arquivo XML de estados e para cada estado lá presente, instanciaremos uma classe Estado (criada automaticamente pelo EF durante o mapeamento), preencheremos suas propriedades com os valores do XML e salvaremos ela no ContextoDados, que por sua vez salvará no banco. Simples assim.

Obviamente isso exige algum conhecimento de Linq To XML, que não será coberto neste post (quem sabe futuramente?) mas que não faltam informações no Tio Google. Sim, eu darei os scripts de Linq To XML, mas seria bom se você realmente estudasse um pouco mais porque é realmente muito poderoso trabalhar com XML desta forma.

Começamos nosso código abrindo o arquivo XML com Linq2Xml e imprimindo todos seus estados no console. Esse código vai dentro do método Main no arquivo Program.cs de sua Console Application.

Note que o caminho do arquivo XML deve ser alterado para condizer com a sua realidade. Se tudo der certo, o Console exibirá o nome de todos os estados existentes no XML. Importante: não esqueça de adicionar uma diretiva using no topo do seu código para o namepsace System.Xml.Linq ou ele não vai compilar.

Se você fez o exemplo anterior de forma correta, já imagina como proceder para terminar o script sozinho, mas vamos terminar juntos. Incremente seu código conforme o exemplo abaixo, fazendo com que você instancie um Xml2BDEntities (nome gerado automaticamente para o contexto de dados do nosso banco Xml2Bd) e adicione um novo objeto Estado para cada registro Estado no XML.

Voilá! Aqui temos nosso código de migração XML para Sql Server 100% pronto! Se você for na sua tabela de Estados encontrará  todos os registros devidamente inseridos. O código para inserir as cidades no banco é praticamente o mesmo, mudando apenas a entidade a ser salva (Cidade) e os elementos do XML a serem percorridos. O referido código se encontra 100% pronto na solution que disponibilizei para download no início do post, se o que você queria era apenas co0locar os estados e cidades dos arquivos no seu BD, basta executar.

Considerações Importantes

Note que tive uma preocupação importante neste código que foi a de não instanciar múltiplos contextos de dados (Xml2BdEntities) para não sobrecarregar a memória do programa e nem encher o banco de requisições inúteis. Também efetuei somente uma operação de inserção no banco contendo todos os registros a serem adicionados, feito evidenciado pela chamada contextoDados.SaveChanges() na última linha de código, que nada mais faz do que persiste as entidades alteradas diretamente o banco de dados físico.

Essas preocupações são o mínimo que se espera de um código ágil (afinal chamadas repetitivas ao banco de dados tornam a aplicação lenta) e escalável (nunca subestime a sua capacidade de escrever programas que derrubem a pilha de memória do servidor). E se eu quisesse migrar informações de uma base MySQL para uma SQL Server? Esse assunto foi abordado nesse post.

Por hoje é só pessoal. Até o próximo post!

Base de dados com todos estados e cidades brasileiras

Há alguns meses atrás estava desenvolvendo uma aplicação e por um motivo específico da mesma eu necessitava de uma base de dados com todos os estados brasileiros, todas cidades brasileiras, saber as capitais de cada estado e os DDDs de cada cidade. Dei várias “Googladas” e não encontrei nada. Ao que parece ninguém disponibilizou tal base de dados publicamente, embora todos esses dados sejam públicos e facilmente encontrados em sites como do IBGE. Como “coder” que sou, acabei desenvolvendo um script que lia uma página do IBGE e retirava as informações que me importavam, neste caso, a lista de cidades de cada estado. Mais uns minutos pesquisando e obtive as informações do DDD através do site da Embratel. Atando as pontas e mais um pouco de código e voilá! Uma base de dados prontinha contendo todas as informações geo-políticas das quais necessitava!

Como todo bom samaritano, tratei de guardar tal base para disponibilizá-la mais tarde quando tivesse um blog próprio. Opa! Segue abaixo o link para download de dois arquivos XML. O Estados.xml contém os dados referentes aos estados brasileiros, suas siglas e capitais. No Cidades.xml você tem uma imensa lista que acredito que abranja no mínimo 90% das cidades brasileiras (a culpa é do site do IBGE que é desatualizado) com o estado ao qual pertence e seu DDD (sim, não é apenas um DDD por estado). O quê, você não sabe como fazer para transformar esse XML na sua base de dados favorita? Então não perca meu próximo post

Se você acabar utilizando tais arquivos em seu sistema, não esqueça de por meu nome nos agradecimentos, hehehehe.

Update em 02/01/2010: um pedido de desculpas aos leitores mineiros. Acabei de atualizar os arquivos com o estado de Minas Gerais (Estados.xml), as cidades de Minas Gerais (Cidades.xml) e para compensar o erro, adicionei um outro XML para download, o Regioes.xml com dezenas de regiões do Brasil, como Baixada Santista, Serra Gaúcha, entre outras, para facilitar a vida de quem esteja desenvolvendo (assim como eu) aplicações que usam dados geográficos como filtro para alguma busca. Agora o arquivo de cidades possui 5537 cidades brasileiras, bem pertinho dos 5565 aproximados que o IBGE diz que nosso Brasil possui.