Subscrever a um Serviço Web em 4D

4D lhe permite subscrever (assinar) aos Serviços Web; ou seja, chamar os Serviços Web externos pelo interior de suas bases de dados.

Utilizando os Serviços Web disponíveis na Internet, é possível adicionar facilmente numerosas funções adicionais a suas bases, tais como informação do mercado de valores, seguimento de entrega de pacotes, execução de cálculos complexos, etc. A imensa disponibilidade de Serviços Web  na Internet pode suprir a maioria das necessidades.

Você também pode subscrever aos Serviços Web que tenha publicado em outras bases e desta forma permitir que várias bases de dados se comuniquem entre elas mesmas.

Qualquer banco de dados 4D pode subscrever a um Serviço Web; somente necessita estar conectada a Internet.

Geralmente, para poder chamar um Serviço Web, deve seguir os seguintes passos: 

1. Encontre a URL do Serviço Web ao qual deseja subscrever.
   Para fazer isto, você pode utilizar os sites da Web que fazem um registro dos Serviços Web publicados na Internet (por exemplo, www.xmethods.net) ou diretórios como el UDDI. Na maioria dos casos, deve obter o URL do arquivo WSDL para o Serviço Web.
   Nota: 4D pode utilizar Serviços Web publicados em modo RPC ou DOC (ver Compatibilidade de RPC, DOC e tipos Complexos).
2. Utilizando o Assistente de Serviços Web, analise o conteúdo do WSDL do Serviço Web a se utilizar e gere o sistema proxy correspondente.
   O sistema proxy é o método de projeto local encarregado de interrogar o Serviço Web e de recuperar os valores devolvidos. Este passo é descrito a seguir.
   Notas:
   
   • É possível criar sistemas proxy no Assistente de Serviços Web sem utilizar o arquivo WSDL (simplesmente introduza manualmente os parâmetros a utilizar).
   • Também é possível criar sistemas proxy no editor de sistemas, sem utilizar o Assistente de Serviços Web (usuários avançados).
3. No código de sua base, chame o sistema proxy cada vez que o necessite passando-lhe os parâmetros apropriados.
   Este passo se descreve em Chamar um sistema proxy.

O método proxy maneja a conexão ao Serviço de Web:

Para abrir a janela do Assistente de Serviços de Web, escolha o comando Assistente de serviços de Web... no menu Desenho de 4D. Aparece a janela do assistente

Nota: também é possível mostrar o assistente de serviços web desde o menu de opções da página Métodos do Explorador (ver ).

Esta janela inclui três áreas:

• a área “URL:” permite introduzir ou selecionar o URL do arquivo WSDL para o Serviço Web selecionado. Esta área é um combo box que armazena os valores previamente introduzidos na forma de lista suspensa.
• a área central mostra os resultados da análise de conteúdo do arquivo WSDL: nomes dos serviços e dos sistemas publicados.
  
• a área inferior (“Parâmetros avançados”, oculta por padrão) mostra os parâmetros do sistema selecionado na área central.
  

O botão Descobrir ativa a análise do arquivo WSDL designado e o preenchimento das áreas de informação.

O botão Examinar... mostra uma caixa de diálogo padrão para abrir arquivos, permitindo selecionar um arquivo WSDL armazenado localmente. Sua rota de acesso, que começa por “file://”, é mostrada na área “URL:” (é possível introduzir manualmente a rota de acesso nesta área).

O botão Criar permite gerar o sistema proxy correspondente ao Serviço Web selecionado.

O botão Fechar fecha a caixa de diálogo do assistente de serviços Web.

O uso típico do Assistente de Serviços Web consiste em analisar um arquivo WSDL e então gerar ele ou os sistemas proxy correspondentes.  Esta operação padrão é totalmente automática e não necessita de programação ou de outro conhecimento particular por parte do usuário.

Para analisar um arquivo WSDL e gerar o sistema proxy:

1. Na área “URL:”, introduza ou cole o URL do arquivo WSDL do Serviço Web que deseja utilizar:
   
   Este URL pode provir, por exemplo, de um “diretório” de Serviços Web ou ter comunicado diretamente pelo servidor do Serviço Web.
   Igualmente, pode-se especificar um URL local, ou seja, o endereço de um arquivo WSDL armazenado em seu disco rígido. Para fazer isto, clique no botão Examinar ... e escolha o arquivo WSDL local, ou introduza diretamente sua rota de acesso na área “URL:”. A rota de acesso do arquivo local começa por “file://” e então utiliza o separador de pastas do sistema. Debe-se passar uma rota de acesso absoluta.
2. Clique no botão Descobrir para que 4D analise o conteúdo do arquivo WSDL.
   Depois de um momento, a área central mostra os resultados da análise do arquivo: o(s) nome(s) do(s) Serviço(s) Web bem como o(s) sistema(s) publicado(s) aparecem na forma de lista hierárquica.
   
   Nota: É possível mostrar diretamente o código fonte XML do arquivo WSDL em seu navegador de Web por padrão, mantendo pressionada a tecla Shift ao clicar no botão Descobrir.
   Ao clicar em um Serviço Web, é mostrada sua documentação (se existir) ao lado direito da janela. Do contrário, aparecerá a indicação “Não documentação”. Da mesma forma, a documentação (se existente) para cada sistema aparece quando seleciona seu nome:
   Nota: Se a análise do arquivo WSDL revela a presença de parâmetros de tipo complexo, o Assistente mostra uma bandeira amarela junto ao método relacionado . 
3. Selecione o sistema Serviço Web que deseja utilizar e então clique no botão Criar. 
   4D gera instantaneamente o sistema proxy correspondente e o mostra em uma janela do editor de métodos:
   
   O nome do sistema proxy está definido pela concatenação do prefixo padrão “proxy_” e o nome do sisema Serviço Web. O prefixo padrão pode ser modificado em Página Web/Web Services das Preferências do banco de dados. O nome do método proxy também pode ser modificado depois de sua criação; isto não influencia no funcionamento do sistema.

Os sistemas proxy gerados pelo Assistente de Serviços Web a partir da análise de um arquivo WSDL são imediatamente operacionais e podem ser utilizados como tais (modo padrão).

Entretanto, você pode modificar os parâmetros resultantes da análise do WSDL. Por exemplo,  é possível renomear o sistema proxy.

Igualmente, pode-se utilizar o Assistente de Serviços Web para criar um sistema proxy para o qual você tenha introduzido manualmente os parâmetros. Neste caso, não utilize o analisador WSDL.

Não é obrigatório introduzir todos os parâmetros para poder criar um método. Inclusive é possível não introduzir nenhum parâmetro a fim de criar um “modelo” de sistema proxy que então possa ser chamado utilizando a linguagem de programação de 4D.

Nestes modos padrão, deve-se utilizar os parâmetros avançados do Assistente de Serviços Web. Para mostrar estes parâmetros, clique no botão localizado na parte inferior esquerda da janela do Assistente. Aparecem os campos dos parâmetros avançados. Se um sistema está selecionado, os campos mostram seus parâmetros atuais:

Todos os parâmetros são modificáveis. Note, contudo, que a modificação dos parâmetros resultantes da análise WSDL (exceto o nome do sistema) deve ser efetuada com precaução porque o funcionamento do Serviço Web pode ser afetado como conseqüência.

Esta é uma descrição dos parâmetros avançados:

• Nome do método: nome que o Assistente dará ao sistema proxy a se criar. Por padrão, este nome é formado pelo prefixo “proxy_” (modificável nas Preferências) seguido do nome do sistema selecionado. Este nome pode ser modificado livremente (por exemplo, se já existe na base de dados) sem que isto influa no funcionamento do Serviço Web.
• URL de acesso: URL ao qual o sistema proxy envia as solicitações SOAP.
• Ação Soap : conteúdo do campo SOAPAction. Este campo contém geralmente o valor “NomeServico#NomeMetodo.”
• Espaço de nomes: namespace do Serviço Web (para maiores informações, consulte Personalizar um espaço de nomes ).
• Parâmetros: esta tabela lista os parâmetros do sistema publicado.
  
  Cada linha da tabela descreve um parâmetro:
  
  • a primeira coluna indica se o parâmetro é de entrada (“in”) ou de saída (“out”). Esta característica é avaliada desde o ponto de vista do sistema proxy e não do sistema publicado.
  • a segunda coluna indica o nome do parâmetro.
  • a terceira coluna indica o tipo de SOAP do parâmetro. Os diferentes tipos de SOAP aceitos por 4D podem ser visualizados no menu Tipo localizado na área Propriedades. O Assistente de Serviços Web é o responsável por associar os tipos SOAP com os tipos 4D correspondentes no método proxy.
    A tabela a seguir descreve os tipos de valores SOAP aceitos e os tipos 4D correspondentes:
    

    Tipo SOAP	Tipo 4D correspondiente
    boolean	Booleano
    int	Inteiro longo
    time	Hora
    float	Real
    double	Real
    date	Data
    string	Texto
    base64Binary	BLOB
    ArrayOfBoolean	Array booleano
    ArrayOfInt	Array inteiro longo
    ArrayOfTime	Array inteiro longo
    ArrayOfFloat	Array real
    ArrayOfDate	Array data
    ArrayOfString	Array texto
    AsXML	BLOB

           
    Nota: O tipo AsXML não é um tipo SOAP, estritamente falando, mas é usado para compatilidade com tipos XML complexos (ver Processamento de tipos complexos).
    A área Propriedades mostra as características do parâmetro selecionado na tabela. O Assistente de Serviços Web lhe permite modificar os parâmetros existentes ou adicionar parâmetros, por exemplo se o arquivo WSDL não estiver atualizado.
    
    • Para modificar um parâmetro, selecione-o e então realize as modificações na área Propriedades.
    • Para adicionar um parâmetro, clique no botão Adicionar e então defina suas características na área Propriedades.
    • Para apagar um parâmetro, selecione-o na lista e então clique no botão Excluir.

Para chamar um sistema proxy no seu código, simplesmente escreva seu nome e passe os parâmetros requeridos. Estes parâmetros são declarados na área de cabeçalho do sistema proxy pelo Assistente de Serviços Web. Conforme a sintaxe padrão para passar parâmetros entre sistemas em 4D, são chamados $0, $1, $2... Podem ser visualizados nos parâmetros avançados da descrição do sistema publicado (ver Uso de parâmetros avançados) e às vezes são descritas em sua documentação.

Por exemplo, no caso de um sistema chamado WS_EuroConverter, o sistema proxy pode ser chamado desta forma:

Depois da execução do sistema, aparece o seguinte alerta:

4D lhe permite utilizar Serviços Web publicados em modo RPC ou DOC, incluindo tipos complexos (ver Compatibilidade de RPC, DOC e tipos Complexos).

Nota: Apesar do fato de serem tipos XML complexos, os arrays de dados são manejados por 4D como tipos simples.

Os sistemas proxy gerados pelo Assistente de Serviços Web que incluem tipos complexos (ou seja, publicados em modo RPC com tipos complexos ou em modo DOC) são similares aos sistemas proxy padrão. Contudo, você notará que em certos casos com estes Serviços Web, o comando [#cmd id="778"/] inclui, como um parâmetro, uma constante que contem a palavra manual.

De fato, o uso de tais Serviços Web requer um processo adicional. A principal razão é que os tipos complexos são trocados em forma de documentos ou elementos XML. Isto significa que para extrair ou incluir informação nestes parâmetros SOAP, é necessário uma análise XML prévia, enquanto no caso dos tipos simples, os valores dos parâmetros podem ser lidos diretamente.

• Uso de tipos simples (RPC)
  

• Uso de tipos compostos (DOC)
  

Só as tabelas e os dados de tipo complexo em um nível (um único nível hierárquico na solicitação SOAP) são totalmente suportados pelo Assistente de Serviços Web. Se encontram elementos mais complexos na solicitação, o Assistente o indicará com uma bandeira suspensa junto ao nome do método. O suporte deste tipo de Serviço Web geralmente requer processos personalizados por parte do desenvolvedor.Em 4D, os parâmetros de tipo complexo (exceto tabelas) são manejados em forma de BLOBs. Os comandos XML de 4D permitem tratar o conteúdo destes BLOBs. Para maiores informações, consulte os temas Web Services (Client) e XML DOM do manual de Linguagem 4D.