por Marcus Rommel Barbosa Leopoldo

Simple Object Access Protocol

Entendendo o Simple Object Access Protocol (SOAP)
Neste artigo vamos fazer uma anlise geral da base da tecnologia SOAP. Conheceremos as suas caractersticas principais e formas de envio das mensagens, assim como a sua relao com protocolos de redes, especificamente o HTTP. O protocolo SOAP um dos elementos fundamentais dos Web Services, apesar de no ser necessrio o conhecimento do funcionamento do protocolo para criar e consumir Web Services. O entendimento geral do protocolo ser til para lidar com situaes de erros e problemas com a interoperabilidade de plataformas no uso de Web Services. Simplificao da especificao, diferente de outros protocolos binrios como COM, DCOM e CORBA.

Funcionalidades do SOAP
O SOAP nos prov algumas funcionalidades: Interoperabilidade entre sistemas utilizando linguagens e protocolos padronizados largamente difundidos, como XML e HTTP. Permite a comunicao entre sistemas protegidos por firewalls, sem precisar abrir portas adicionais e possivelmente noseguras. Ele utiliza (na maioria dos servidores) a porta 80. SOAP descreve completamente cada elemento na mensagem, facilitando o entendimento e a proteo contra erros. A seguir, algumas funcionalidades que o SOAP no capaz de executar: Coleta de lixo distribuida. Objetos por Referncia (pois necessria a coleta de lixo distribuda). Definio de um mecanismo de autenticao.

Pr-Requisitos
Para acompanhar adequadamente este artigo, o leitor deve estar familiarizado com os seguintes assuntos: Conhecimentos intermedirios em XML. Conhecimentos bsicos em protocolos de redes de computadores, especificamente o protocolo HTTP.

O que SOAP?
O SOAP um protocolo simples e leve para troca de informao em um ambiente distribudo e descentralizado, como o ambiente da Internet. Em outras palavras, SOAP habilita dois processos (possivelmente em duas mquinas diferentes) comunicarem entre s desconsiderando o hardware e a plataforma que eles esto rodando. Um dos grandes benefcios do SOAP que ele aberto e foi adotado pela grande maioria das grandes empresas de hardware e software. A sua especificao aberta (ela foi submetida ao W3C*) e prov a base para a comunicao aplicao-aplicao: os Web Services.
Nota O W3C (World Wide Web Consortium) cria padres para a Web, com o objetivo de aumentar ao mximo o potencial da Web, com especificaes, diretrizes, softwares e ferramentas.

Especificao do protocolo
A especificao do protocolo SOAP uma nota submetida ao W3C que est agora no mesmo grupo dos protocolos XML. A especificao 1.1 do protocolo est dividida em 4 partes principais: SOAP Envelope: define uma plataforma para descrio do que h na mensagem e como process-la. Ela guarda todos os dados da mensagem e a nica parte do protocolo que obrigatria. SOAP Encoding Rules: define um mecanismo de serializao que pode ser usado para a troca de instncias de tipos definidos pela aplicao. SOAP RPC Style: define uma conveno que pode ser usada para representar chamadas e repostas remotas procedimentos, nada mais que a dupla requisio/resposta, que no obrigatria. Link SOAP-HTTP: define um protocolo que liga o SOAP e o HTTP. Ele descreve como as mensagens SOAP so transmitidas via HTTP.

Ele um protocolo que define uma gramtica XML especializada, porm flexvel, que padroniza o formato das estrututras das mensagens. As mensagens so, por outro lado, o mtodo fundamental de troca de informaes entre os Web Sevices e os seus consumidores. Ao utilizar XML para codificar mensagens o SOAP nos d alguns benefcios: XML pode ser facilmente lido por humanos, sendo portanto, mais fcil de entender e eliminar erros. XML parsers (analistas) e tecnologias corelatas so mundialmente disponveis. XML um padro aberto. XML inclui vrias tecnologias que podem fortalecer o SOAP.

Elementos da Mensagem SOAP

A mensagem SOAP formada por 3 elementos bsicos, como visto na Figura 1.

Envelope Header

o elemento principal do XML que representa a mensagem. um mecaninsmo genrico de adio de caractersticas mensagem SOAP em maneira descentralizada sem acordo anterior entre as partes comunicantes. Contm a codificao atual de uma chamada a um mtodo e todos os argumentos de entrada ou uma resposta codificada que contm o resultado de uma chamada a um mtodo

Body

Figura 1: Elementos da mensagem SOAP.

<soap:Envelope xmlns:xsi="Schema-Instance" xmlns:xsd="Schema" xmlns:soap="Envelope"> <soap:Header> <Autentica xmlns="Local"> <Usuario>usuario</Usuario> <Senha>senha</Senha> </Autentica> </soap:Header> <soap:Body> <!-- Os elementos do corpo inseridos aqui!!! --> </soap:Body> </soap:Envelope>

A partir de agora chamaremos os 3 elementos de Envelope, Cabealho e Corpo do protocolo respectivamente. Na Figura 2 vemos a estrutura da mensagem SOAP.

Figura 4: Exemplo de formatao de cabealho SOAP.

Uma utilizao tpica do cabealho SOAP na rea de autenticao, onde as credenciais requeridas para o acesso ao mtodo so codificadas. Ele tambm muito usado em gerenciamento de transaes, pagamentos etc. Se uma mensagem contm um cabealho, este deve ser o primeiro elemento a aparecer na mensagem aps a tag de abertura do envelope e todos os elementos filhos do cabealho (na Figura 3 o Usuario e a Senha) so definidos como cabealhos separados e chamados entradas de cabealho (header entries), que devem usar namespaces XML para qualificar seus nomes.

Atributos SOAP globais

Figura 2: Estrutura da mensagem SOAP.

O Envelope SOAP
O envelope SOAP a parte obrigatria de uma mensagem SOAP. Ele funciona como um recipiente de todos os outros elementos da mensagem, possivelmente o cabealho e o corpo, assim como os namespaces de cada um. Assim como o nome e o endereo de uma carta entregue pelo correio, o envelope SOAP precisa das informaes especficas do protocolo de transporte que est ligado a ele, com o intuito de garantir a chegada ao local certo. Especificamente no HTTP, temos um cabealho que se chama SOAPAction, indicador do endereo de entrega da mensagem. Um dos principais motivos de implementarmos o cabealho desta meneira por qu administradores de sistemas podem configurar seus firewalls para filtrar as mensagens baseados nas informaes dos cabealhos, sem consultar o XML. A Figura 3 ilustra a formatao de um envelope SOAP.
<soap:Envelope xmlns:xsi="Schema-Instance" xmlns:xsd="Schema" xmlns:soap="Envelope"> <soap:Body> <!-- Os elementos do corpo inseridos aqui!!! --> </soap:Body> </soap:Envelope>

Existem 3 atributos no SOAP que podem ser utilizados na mensagem: encodingStyle: pode ser usado para indicar o estilo de codficao mustUnderstand e actor: podem ser utilizados para indicar como e quem ir processar as entradas.

Atributo encodingStyle
O encodingStyle um atributo global que pod ser usado para indicar regras de serializao usadas nas mensagens SOAP. Ele pode aparecer em qualquer elemento, e seu escopo todo o contedo do elemento, assim como os elementos filhos. O valor deste atributo uma lista de uma ou mais URI identificando as regras de serializao ou deserializao, indicadas na ordem da mias especfica para a mais abrangente. Temos na Figura 5 exemplos de valores para o atributo encodingStyle.
http://www.xml.it/schemas http://www.xml.it/schemas http://schemas.eu.com.br

Figura 5: Valores vlidos para o atributo encodingStyle.

O valor vazio (a terceira linha da Figura 5) explicitamente indica que no h requisio de encodingStyle para o elemento contido. Isso pode ser usado para descodificar uma requisio feita um elemento pai.

Atributo actor
Algumas aplicaes SOAP so chamadas de intermedirias pois tm a capacidade de receber e encaminhar uma mensagem SOAP. Uma mensagem SOAP pode sair de um remetente para um destinatrio e, potencialmente, passar por vrias aplicaes SOAP intermedirias.
Nota Tanto as aplicaes SOAP intermedirias como as destinatrias so identificadas via URI

Figura 3: Exemplo de formatao de envelope SOAP.

O Cabealho SOAP
O cabealho SOAP uma parte opcional da mensagem. O conceito similar aos Meta Tags dos documentos HTML. Eles definem meta-dados que pode prover um contexto para a mensagem ou redirecionar o processamento da mensagem. Veja na Figura 4 a formatao de um cabealho SOAP.

Nem todas as partes de uma mensagem SOAP interessam a um destinatrio, assim como podem interessar a um ou mais intermedirios no caminho da mensagem. Quando uma aplicao SOAP (digamos A) recebe um elemento de cabealho ela dita receptora e encara o cabealho como um contrato entre ela e quem repassou a mensagem. Dessa forma, ao repassar a mensagem para outra aplicao (B), a aplicao A deve incluir um cabealho similar ao atual, mas no caso, o contrato deve ser entre A e B. Atributo actor pode ser usado como um indicador do receptor de um elemento de cabealho. Ele funciona como o mecanismo de hops representado pelo campo Connection do cabealho do HTTP. O seu valor uma URI, que se for vazio, informa que o receptor o destinatrio.

<soap:Envelope xmlns:xsi="Schema-Instance" xmlns:xsd="Schema" xmlns:soap="Envelope"> <soap:Body> <ConverteResponse xmlns="http://site.com.br"> <ValorResult>1010</ValorResult> </ConverteResponse> </soap:Body> </soap:Envelope>

Figura 7: Uma resposta SOAP que retorna um valor convertido para binrio.

Por algum motivo a resposta pode conter erros, e o resultado apresentado ser uma exceo (fault), como veremos posteriormente.
Nota Na resposta SOAP, o elemento responsvel pela resposta usa o mesmo nome do elemento de chamada (Converte) concatenado com o sufixo Response.

Atributo mustUnderstand
Este atributo pode ser usado para indicar se uma entrada de cabealho obrigatria ou opcional para o receptor processar. O seu valor pode ser 1 ou 0. Se o atributo no for escrito, o cabealho se comporta como tendo o atributo e o valor 0.
Nota Lembrando que os receptores das entradas de cabealho so definidas pelo atributo actor

Tipos de Dados suportados pelo SOAP

A especificao do SOAP define o suporte aos tipos de dados baseado no XSD, a especificao do XML Schema Definition. Esta especificao define padres para a descrio de tipos primitivos de dados assim como estruturas complexas e hierrquicas. Tipos definidos pelo usurio tambm so aceitos, de forma que possvel formar estruturas de dados a partir dos dados primitivos oferecidos pela XSD. Mais uma grande vantagem do uso do SOAP, que aceita qualquer tipo que possa ser representado por um XSD Schema. Nas Figura 8 temos uma tabela com os tipos aceitos no XSD.
boolean byte double datatype decimal enumeration float int long Qname short string timeInstant unsignedByte unsignedInt unsignedLong unsignedShort

O Corpo SOAP
O corpo da mensagem SOAP uma parte obrigatria que guarda dados especficos de uma chamada de um mtodo particular, tais como o nome do mtodo e parmetros de entrada, sada e resultados produzidos pelo mtodo. As utilizaes do corpo da mensagem incluem chamadas remotas mtodos e notificaes de erros. Ele est presente logo aps o cabealho da mensagem, se este existir. Caso no exsita, ele deve aparecer imediatamente aps a tag de abertura do envelope. O contedo do corpo da mensagem SOAP depende se ela uma requisio ou uma resposta. Caso seja requisio, ele contm informaesssobre a chamada do mtodo, se uma resposta contm dados do resultado da chamada ao mtodo. Nas Figuras 6 e 7 temos, respectivamente, exemplos de uma requisio e uma resposta. A requisio feita para converter um valor e a resposta o valor convertido.
<soap:Envelope xmlns:xsi="Schema-Instance" xmlns:xsd="Schema" xmlns:soap="Envelope"> <soap:Body> <Converte xmlns="http://conv.fractalti.com.br"> <Valor>10</Valor> <De>DEC</De> <Para>BIN</Para> </Converte> </soap:Body> </soap:Envelope>

Figura 8: Tipos bsicos de dados suportados pelo SOAP. Nota A formao de dados mais complexos foge do escopo deste artigo, pois uma especificao do XML. Caso haja o interesse de mais informaes de como manipular este tipo de dados, visite: XML Schema Part 1: Structures http://www.w3.org/TR/xmlschema-1/ XML Schema Part 1: Data Types http://www.w3.org/TR/xmlschema-2/

Excees SOAP
Como os mtodos acessados via SOAP no esto livres de erros, necessria alguma forma de notificao que ocorreu um erro e onde este erro foi encontrado. Infelizmente erros (com certa freqncia) ocorrem. Estes erros ou excees, que ocorrem em um web service devem ser retornados ao consumidor de alguma maneira, e a que entra a exceo SOAP.
Nota A especificao oficial do SOAP usa o termo fault (falha) ao invs de exception (exceo). Foi dada preferncia ao termo exceo por estar em sintonia com a terminologia usada na maioria das lingagens de programao.

Figura 6: Uma requisio SOAP que passa um valor para ser convertido de Decimal para Binrio.

As excees SOAP podem ocorrer em vrios estgios do processamento de requisies de um web service. Se o erro ocorre no envio HTTP, antes da chegada no web service, a camada do HTTP responsvel pelo erro deve utilizar a conveno do prrpio HTTP para notific-lo. Caso o erro ocorra na prrpia execuo do aplicativo SOAP, podemos ver na Figura 9 o cdigo gerado, o erro e a sua descrio.
Valor Nome 100 200 Version Mismatch Must Understand Invalid Request Application Faulted Significado A chamada usou uma verso SOAP que ela no suporta. Um elemento XML foi recebido com o atributo mustUnderstand com valor 1 , mas no foi entendido pelo receptor. O receptor no conseguiu processar a requisio por que ela est mal-formada ou no suportada. O recebimento da aplicao falhou quando o processamento foi requisitado.

Nota As aplicaes SOAP intermedirias no so as mesmas que os intermedirios do HTTP . Ou seja, no podemos esperar que o cabealho do HTTP Connection inspecione ou processe o corpo SOAP carregado no HTTP Request

HTTP Post
O comando Post do HTTP ser o responsvel pelo envio da mensagem SOAP. Ele contm uma URI requisitora que especifica um destino ID. O sevidor responsvel por mapear a URI para a implementao do Web Service e ativar o cdigo intrnseco plataforma onde o servio ir rodar. Ainda no cabealho do HTTP temos um campo com o nome do mtodo chamado. Seguido pelo cabealho, temos a prpria mensagem SOAP, que separada por uma linha em branco. A Figura 11 temos um modelo de uma estrutura SOAP contida em uma requisio HTTP Post.

300 400

Figura 9: Excees geradas pelo SOAP.

O elemento fault da mensagem SOAP define 4 subelementos (que so obrigatrios): faultcode: o cdigo da exceo gerada. faultstring: um texto resumindo o motivo do erro, bom que ele gere pelo menos a natureza do erro. faultactor: Informa quem foi o causador do erro. Similar ao atributo actor, ele informa a URI de quem causou o erro. Apenas a aplicao destinatria deve conter o faultactor detail: Informa erros especficos da aplicao, ele estar no cabealho ou no corpo da mensagem dependendo do tipo de erro.
Nota O erro 400 (Application Failed) apresentado no elemento detail. Figura 11: Estrutura do HTTP Post com uma mensagem SOAP.

Na Figura 10 vemos uma resposta SOAP contendo uma exceo. Note que a excesso foi gerada pela aplicao (erro 400) ao tentar-se dividir um nmero por 0 (zero).
<soap:Envelope xmlns:xsi="Schema-Instance" xmlns:xsd="Schema" xmlns:soap="Envelope"> <soap:Body> <soap:Fault> <faultcode>400</faultcode> <faultstring>Divide by zero error</faultstring> <detail> <t:DivideByZeroException xmlns:soap="http://www.fractalti.com.br"> <expression>x = 2 / 0;</expression> </t:DivideByZeroException> </detail> </soap:Fault> </soap:Body> </soap:Envelope>

Na Figura 12 vemos o exemplo da Figura 6 sendo enviado via HTTP Post.

POST /ctemp/ctemp.asmx HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://site.com.br" <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="Schema-Instance" xmlns:xsd="Schema" xmlns:soap="Envelope"> <soap:Body> <Converte xmlns="http://conv.fractalti.com.br"> <Valor>10</Valor> <De>DEC</De> <Para>BIN</Para> </Converte> </soap:Body> </soap:Envelope>

Figura 10: Exceo ocorrida em uma requisio SOAP.

Transportando SOAP via HTTP

Para entregar mensagens codificadas em SOAP como requisies ou como respostas, precisamos um protocolo de transporte. Claramente, por se tratar especialmente de web services, este protocolo deve ser largamente utilizado. A escolha biva seria o HTTP. O SOAP naturalmente levado a utilizar o modelo de requisio/resposta proposto no HTTP.

Figura 12: Exemplo de requisio feita via HTTP Post.

HTTP Response
o comando responsvel por enviar a resposta de um web service. Agora, na Figura 13, temos uma resposta HTTP. Note que URI do destinatrio no mais necessria, apesar da estrutura manter-se igual.

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="Schema-Instance" xmlns:xsd="Schema" xmlns:soap="Envelope"> <soap:Body> <ConverteResponse xmlns="http://site.com.br"> <ValorResult>1010</ValorResult> </ConverteResponse> </soap:Body> </soap:Envelope>

Figura 13: Exemplo de requisio feita via HTTP Post.

Outras vias de transporte

Apesar de preferido, o HTTP no uma forma obrigatria de envio de mensagens SOAP. Tambm possvel transportar o SOAP via outros protocolos, tais como FTP e SMTP.

Concluso
SOAP o elemento principal da infraestrutura dos Web Services e um fator determinante para o funcionamento dos mesmos, independente de plataformas, sistemas operacionais, modelos de objetos e lingagens de programao, auxiliando muito a interoperabilidade entre objetos e componentes distribudos. Este protocolo acaba com a disputa entre lingagens, garantindo que o programador possa desenvolver no ambiente que seja mais adequado s suas necessidades. Apesar de ser uma tecnologia recente, SOAP j tem um lugar significativo na internet, sendo portanto, uma excelente escolha para desenvolvimento de Web Services.

Marcus Rommel desenvolvedor da Fractal TI (www.fractalti.com.br) e atualmente trabalha com a plataforma .NET com nfase no desenvolvimento de aplicaes WEB com ASP.NET e C#, assim como aplicaes Windows Forms com o uso do C#. mailto: mrommel@fractalti.com.br
O autor permite a cpia e distribuio total ou parcial deste artigo desde que sejam citados o autor, a fonte e o ano de publicao. Marcus Rommel, Novembro de 2003