Como expor um serviço SOAP como um proxy de API

Você está vendo a documentação do Apigee Edge.
Consulte a documentação do Apigee X.

Este tópico explica como criar proxies de API para serviços da Web baseados em SOAP. É possível criar dois tipos de proxies SOAP no Edge. Um gera uma interface RESTful para o serviço SOAP do back-end e o outro executa uma "passagem" da mensagem SOAP para o back-end. Ambas as técnicas estão descritas neste tópico.

Neste vídeo, você verá uma demonstração completa de como transformar um serviço SOAP em um serviço REST com o Apigee Edge usando o assistente de proxy de API. No entanto, se você quiser ter mais controle sobre a transformação SOAP para REST, crie políticas usando políticas. Para mais informações, consulte Tutorial: construção manual de um proxy de API SOAP para REST na Apigee Edge.

Como criar um proxy de API RESTful para um serviço SOAP

Nesta seção, explicamos como criar um proxy RESTful da API SOAP com a opção REST a SOAP to REST no assistente "Build a Proxy".

Visão geral

A opção REST para SOAP para REST processa o WSDL para gerar um proxy da API RESTful. O Edge determina a partir do WSDL as operações compatíveis com o serviço, os parâmetros de entrada e assim por diante. "Adivinhe" qual método HTTP usar para cada operação. Normalmente, o Edge converte as operações em solicitações GET, que têm a vantagem de serem armazenáveis em cache. O Edge também configura o endpoint de destino do back-end, que pode variar de acordo com a operação SOAP.

Para esse tipo de proxy, o Edge gera automaticamente uma especificação OpenAPI, que pode ser usada para criar a documentação da API.

Etapas básicas

Edge

Para criar um proxy de API RESTful para um serviço baseado em SOAP usando a IU do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Desenvolver > Proxies de API na barra de navegação à esquerda.
  3. Clique em +Proxy.
  4. Clique em Serviço SOAP.
  5. Na página de detalhes do proxy, forneça o arquivo WSDL.
    Campo Descrição
    Fornecer arquivo WSDL

    Selecione a fonte do WSDL.

    • Endereço da Web (URL): digite ou cole o URL da WSDL.
    • Meu computador: faça upload de um arquivo WSDL do seu diretório local. É possível fazer o upload de vários arquivos se houver dependências.
  6. Clique em Validate para validar o WSDL.
  7. Digite os seguintes detalhes do proxy:
    Campo Descrição
    Nome Nome exibido para a API. Especifique caracteres alfanuméricos, traço (-) ou sublinhado (_).
    Base path

    Fragmento de URI que aparece após o endereço http(s)://[host] do proxy de API. O Edge usa o URI do caminho base para corresponder e rotear mensagens de solicitação recebidas para o proxy de API apropriado.

    OBSERVAÇÃO: o caminho base do proxy de API assume como padrão o valor especificado para Name convertido em letras minúsculas.

    Após o caminho base estão todos os URLs de recursos extras. Esta é a estrutura de URL completa que os clientes usarão para chamar o proxy de API:

    https://[host]/base_path/conditional_flow_path

    OBSERVAÇÃO: o caminho de base precisa ser único. não é possível implantar dois proxies de API com o mesmo caminho de base. Se você editar um proxy de API implantado e definir o caminho base com o mesmo valor que o caminho base de outro proxy de API, o Edge cancelará a implantação do proxy de API automaticamente quando ele for salvo. Antes de reimplantar o proxy de API, será preciso editar o caminho de base para que ele seja exclusivo.

    Usar caracteres curinga em caminhos de base

    Use um ou mais caracteres curinga /*/ nos caminhos de base do proxy de API para preparar seus proxies para o futuro. Por exemplo, um caminho de base /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem a necessidade de criar novos proxies de API para oferecer suporte a novas equipes. /**/ não é compatível.
    Descrição (Opcional) Descrição da API.
  8. Clique em Próxima.
  9. Na página Políticas comuns do assistente, faça as seguintes configurações:
    • Requisitos de autorização de segurança em Security: Authorization. Consulte Como adicionar segurança.
    • Suporte para Compartilhamento de recursos entre origens (CORS, na sigla em inglês) em Security: Browser. Consulte Como adicionar suporte a CORS.
    • Cotas para proteger seu serviço de back-end contra tráfego alto em Quota. Veja Cotas. Essa opção não estará disponível se a autorização de passagem estiver selecionada.
  10. Na página Operações WSDL, selecione o tipo de proxy de API REST como SOAP para REST.

    Uma tabela será exibida listando as operações que o Edge "descobriu" no arquivo WSDL. Você pode selecionar e configurar quais operações quer incorporar ao proxy de API. A tabela é mostrada na figura a seguir.

  11. Selecione um Tipo de porta na lista suspensa para especificar o conjunto de operações que você quer usar. Na WSDL, os elementos de tipo de porta definem as operações que podem ser chamadas em um serviço da Web.
  12. Como opção, altere o Path da API REST para uma operação. O caminho será usado como o nome do recurso no URL do proxy da API.
  13. Como opção, altere o Verb (método HTTP) associado à operação.
  14. Clique em Próxima.
  15. Na página Virtual hosts do assistente, selecione os hosts virtuais que serão vinculados ao proxy de API no momento da implantação. Para mais informações, consulte Sobre hosts virtuais.
  16. Clique em Próxima.
  17. Selecione os ambientes de implantação e clique em Criar e implantar
    Seu novo proxy de API será criado e implantado no ambiente selecionado.
  18. Clique em Edit proxy para exibir a página de detalhes do proxy de API.

Versão clássica do Cloud Edge (nuvem privada)

Para criar um proxy de API RESTful para um serviço baseado em SOAP usando a IU clássica do Edge:

  1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
  2. Selecione APIs > Proxies de API na barra de navegação superior.
  3. Clique em + Proxy de API.
  4. No assistente Build a Proxy, selecione o serviço SOAP.
  5. Clique em Próxima.
  6. Na página "Detalhes", faça essas seleções. Clique em Validar depois de selecionar uma WSDL.
    Neste campo faça isso
    WSDL

    Selecione a fonte do WSDL.

    • URL: insira o URL da WSDL que você quer usar.
    • Arquivo: escolha um arquivo WSDL no seu sistema de arquivos. Nos casos em que há mais arquivos dependentes, é possível selecionar todos eles.
    • URL de exemplo: selecione em uma lista de WSDLs para serviços da Web disponíveis publicamente. Eles são úteis para testar os recursos de proxy SOAP/API do Edge.
    Proxy Name

    Este é o nome do proxy que você está criando.
    Caminho base do proxy

    Fragmento de URI que aparece após o endereço http(s)://[host] do proxy de API. O Edge usa o URI do caminho base para corresponder e rotear mensagens de solicitação recebidas para o proxy de API apropriado.

    Observação: o caminho base do proxy de API usa como padrão o valor especificado para o campo Name convertido em letras minúsculas.

    Após o caminho base estão todos os URLs de recursos extras. Esta é a estrutura de URL completa que os clientes usarão para chamar o proxy de API:

    https://[host]/base_path/conditional_flow_path

    Observação: o caminho base precisa ser exclusivo. Não é possível implantar dois proxies de API com o mesmo caminho base. Se você editar um proxy de API implantado e definir o caminho base com o mesmo valor que o caminho base de outro proxy de API, o Edge cancelará a implantação do proxy de API automaticamente quando ele for salvo. Antes de reimplantar o proxy de API, será preciso editar o caminho de base para que ele seja exclusivo.

    Usar caracteres curinga em caminhos de base

    Use um ou mais caracteres curinga /*/ nos caminhos de base do proxy de API para preparar seus proxies para o futuro. Por exemplo, um caminho de base /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem a necessidade de criar novos proxies de API para oferecer suporte a novas equipes. /**/ não é compatível.
    Descrição Uma breve descrição do proxy.
  7. Clique em Próxima.
  8. Na página WSDL, selecione o tipo de proxy de API REST como SOAP para REST.

    Uma tabela será exibida listando as operações que o Edge "descobriu" no arquivo WSDL. Você pode selecionar e configurar quais operações quer incorporar ao proxy de API. A tabela é mostrada na figura a seguir.

    Na página de operações WSDL, o tipo de proxy de API está definido como REST como SOAP como REST, e uma tabela mostra uma linha de resultados com a operação de adição.

  9. Na coluna Tipo de porta , selecione qual conjunto de operações você deseja usar. Na WSDL, os elementos de tipo de porta definem as operações que podem ser chamadas em um serviço da Web.
  10. Como opção, altere o método HTTP associado à operação.

    Observação: o Edge faz uma estimativa para determinar o método HTTP a ser usado em cada operação. Geralmente, é preferível receber GET porque as solicitações GET podem ser armazenadas em cache.
  11. Como opção, altere o caminho da API REST para uma operação. O caminho será usado como o nome do recurso no URL do proxy da API.
  12. Clique no restante do assistente para adicionar segurança, selecionar hosts virtuais e o ambiente de implantação.
  13. Na página "Build", clique em Build and Deploy. O Edge gera e implanta o novo proxy de API com base no WSDL.
  14. Acesse a página de resumo do novo proxy de API. Observe que um conjunto de recursos foi criado com base nas operações descobertas no arquivo WSDL.

    Na página "Visão geral" do proxy, a lista Recursos fornece uma descrição detalhada da nova API, das operações e dos parâmetros dela. Pense nessa representação como a documentação de referência da API. O Edge gera essa visualização do modelo de API automaticamente para você. Basta expandir um recurso para ver a descrição e as informações do caminho.

Sobre o proxy final

Quando o Edge gera um proxy de API com base em um WSDL, o proxy resultante é, na verdade, um fluxo complexo que inclui políticas para transformar dados, extrair e definir variáveis, manipular mensagens e muito mais. Depois de gerar um proxy com base em um WSDL, observe o fluxo resultante na visualização "Desenvolver" da IU de gerenciamento da API. Lá, é possível ver exatamente quais políticas foram adicionadas.

Por exemplo, no lado da solicitação, uma política "AssignMessage" é usada para definir o URL de destino. No lado da resposta, as políticas são executadas para transformar a resposta de XML em JSON, extrair a parte do corpo SOAP da resposta em uma variável e definir a mensagem de resposta. Essas políticas (e outras) são adicionadas automaticamente quando você cria o proxy.

Especificação OpenAPI: para ver a Especificação OpenAPI gerada automaticamente para este proxy, acesse http(s)://[proxy_domain]/[proxy_base_path]/openapi.json. No entanto, a conversão nem sempre é precisa, já que nem todas as regras de um esquema XML podem ser representadas em uma especificação OpenAPI.

Como criar um proxy de passagem para um serviço baseado em SOAP

Nesta seção, explicamos como criar um proxy de passagem com a opção Proxy de passagem na caixa de diálogo "Criar novo proxy".

Visão geral

A opção "Pass-through Proxy" permite criar um proxy que transmite a mensagem SOAP em uma solicitação para o serviço de back-end "sem alterações", o que facilita muito a criação de um proxy para um serviço da Web baseado em SOAP. Nos bastidores, o Edge processa automaticamente qualquer transformação e outras atividades de fluxo para você. Por exemplo, se a solicitação estiver no formato JSON, o Edge tomará medidas para convertê-la em uma mensagem XML SOAP válida com os namespaces corretos antes de postá-la para o serviço. Da mesma forma, quando o serviço retorna uma resposta SOAP baseada em XML, o Edge a traduz de volta para JSON antes de devolvê-la para o cliente. Além disso, o Edge configura o endpoint de destino do back-end, que pode variar de acordo com a operação SOAP.

Para esse tipo de proxy, o Edge hospeda o WSDL e cria um fluxo no proxy para permitir o acesso. O endereço para esse WSDL hospedado no Edge, http(s)://[proxy_domain]/[proxy_base_path]?wsdl, torna-se o novo URL do endpoint de serviço para clientes que chamam o serviço SOAP por meio do proxy.

Etapas básicas

Edge

Para criar um proxy de passagem para um serviço baseado em SOAP usando a IU do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Desenvolver > Proxies de API na barra de navegação à esquerda.
  3. Clique em +Proxy.
  4. Clique em Serviço SOAP.
  5. Na página Detalhes do proxy, forneça os detalhes do WSDL.
    Campo Descrição
    WSDL

    Selecione a fonte do WSDL.

    • Endereço da Web (URL): digite ou cole o URL da WSDL.
    • Meu computador: faça upload de um arquivo WSDL do seu diretório local. É possível fazer o upload de vários arquivos se houver dependências.
    Nome

    Nome do proxy de API.
    Caminho base

    Fragmento de URI depois do endereço http(s)://[host] do proxy da API. O Edge usa o URI do caminho base para corresponder e rotear mensagens de solicitação recebidas para o proxy de API apropriado.

    Observação: para ver recomendações da Apigee sobre o controle de versões da API, consulte Controle de versão no e-book Design de API da Web: a parte que faltava.

    Depois do caminho base, ficam os outros URLs de recursos. Veja a estrutura completa do URL que os clientes usarão para chamar o proxy de API:

    https://[host]/base_path/conditional_flow_path

    Observação: o caminho base precisa ser exclusivo. Se você editar esse proxy posteriormente e definir o caminho base como o mesmo de outro proxy de API, a implantação será cancelada automaticamente quando você salvar o proxy. É preciso editar o caminho base antes de reimplantá-lo.

    Como usar um caractere curinga em caminhos base

    É possível usar um ou mais caracteres curinga /*/ nos caminhos base do proxy de API para preparar os proxies para o futuro. Por exemplo, um caminho base de /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem a necessidade de criar novos proxies de API para dar suporte a novas equipes. Observe que /**/ não é compatível.

    Observação: o caminho base do proxy de API usa como padrão o valor especificado para o campo "Nome" convertido em letras minúsculas, a menos que você edite explicitamente o conteúdo no campo "Caminho base".
    Descrição (Opcional) Descrição da API.
  6. Clique em Próxima.
  7. Na página Políticas comuns do assistente, faça as seguintes configurações:
  8. Na página WSDL, selecione o tipo de proxy da API Pass-through SOAP.

  9. Selecione um Tipo de porta na lista suspensa para especificar o conjunto de operações que você quer usar. Na WSDL, os elementos de tipo de porta definem as operações que podem ser chamadas em um serviço da Web.
  10. Clique em Próxima.
  11. Na página Virtual hosts do assistente, selecione os hosts virtuais que serão vinculados ao proxy de API no momento da implantação. Para mais informações, consulte Sobre hosts virtuais.
  12. Selecione os ambientes de implantação e clique em Criar e implantar
    Seu novo proxy de API será criado e implantado no ambiente selecionado.
  13. Clique em Edit proxy para exibir a página de detalhes do proxy de API.

Versão clássica do Cloud Edge (nuvem privada)

Para criar um proxy de passagem para um serviço baseado em SOAP usando a IU clássica do Edge:

  1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
  2. Selecione APIs > Proxies de API na barra de navegação superior.
  3. Clique em + Proxy de API.
  4. No assistente Build a Proxy, selecione o serviço SOAP.
  5. Clique em Próxima.
  6. Na página "Detalhes", faça essas seleções. Clique em Validar depois de selecionar uma WSDL.
    Neste campo faça isso
    WSDL

    Selecione a fonte do WSDL.

    • URL: insira o URL da WSDL que você quer usar.
    • Arquivo: escolha um arquivo WSDL no seu sistema de arquivos. Nos casos em que há mais arquivos dependentes, é possível selecionar todos eles.
    • URL de exemplo: selecione em uma lista de WSDLs para serviços da Web disponíveis publicamente. Eles são úteis para testar os recursos de proxy SOAP/API do Edge.
    Proxy Name

    Este é o nome do proxy que você está criando.
    Caminho base do proxy O caminho base do proxy é um fragmento de URI que identifica exclusivamente a API exposta por esse proxy de API. Os serviços da API usam o URI do caminho base para corresponder e rotear mensagens de solicitação recebidas para o proxy de API apropriado. O caminho base é anexado ao domínio da API, que é gerado automaticamente com base no nome da organização e no ambiente em que o proxy da API está implantado. É uma prática recomendada incluir um número de versão no nome do projeto, por exemplo, /v1/delayedstockquote. Isso determinará como a API é invocada por apps de consumidor.

    Observação: o caminho base do proxy usa como padrão o valor especificado para o nome do proxy convertido em letras minúsculas, a menos que você edite explicitamente o conteúdo no campo "Caminho base do proxy".
    Descrição Uma breve descrição do proxy.

  8. Clique em Próxima.
  9. Na página WSDL, selecione o tipo de proxy da API Pass-through SOAP.

    Observação: é exibida uma tabela que lista cada operação WSDL e o respectivo payload SOAP. Essa é a carga útil que é "transmitida" para o serviço SOAP do back-end.

    Na página WSDL, o tipo de proxy de API está definido como SOAP de passagem, e uma lista de operações, como GetQuote, é organizada por tipo de porta.
  10. Na coluna Tipo de porta , selecione qual conjunto de operações você deseja usar. Na WSDL, os elementos de tipo de porta definem as operações que podem ser chamadas em um serviço da Web.
  11. Clique no restante do assistente para adicionar segurança, selecionar hosts virtuais e o ambiente de implantação.
  12. Na página "Build", clique em Build and Deploy. O Edge gera e implanta o novo proxy de API com base no WSDL.

Sobre o proxy final

Quando o Edge gera um proxy de passagem, o proxy resultante é, na verdade, um fluxo complexo que inclui políticas para transformar dados, extrair e definir variáveis, manipular mensagens e muito mais. Depois de gerar o proxy de passagem, veja o fluxo resultante na visualização "Desenvolver" da IU de gerenciamento da API. Lá, é possível ver exatamente quais políticas foram adicionadas.

Por exemplo, a figura a seguir mostra a parte de pré-fluxo de endpoint de destino de um proxy de passagem. No lado da solicitação, uma política "AssignMessage" é usada para definir o URL de destino. No lado da resposta, as políticas são executadas para transformar a resposta de XML em JSON, extrair a parte do corpo SOAP da resposta em uma variável e definir a mensagem de resposta. Essas políticas (e outras) são adicionadas automaticamente quando você cria o proxy.

Na visualização "Desenvolver", no painel "Fluxo", as setas representam o fluxo da solicitação à resposta, e os ícones representam as políticas.

WSDL hospedado pelo Edge: para ver a WSDL hospedada pelo Edge gerada para esse tipo de proxy, acesse http(s)://[proxy_domain]/[proxy_base_path]?wsdl.

Desenvolvimento avançado de proxy SOAP-para-REST

Nas seções anteriores, abordamos a criação de um proxy de API SOAP para REST usando o assistente de proxy de API no Edge. No entanto, se você quiser um controle mais refinado sobre a transformação SOAP para REST, é possível ignorar a automação fornecida pelo assistente e criar um proxy adicionando e configurando políticas manualmente para conseguir o comportamento que você quer. Para mais informações, consulte Tutorial: construção manual de um proxy de API SOAP para REST na Apigee Edge.