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

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

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 de back-end, e o outro realiza uma passagem da mensagem SOAP para o back-end. As duas técnicas são descritas neste tópico.

Este vídeo mostra 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 mais controle sobre a transformação de SOAP para REST, crie um proxy usando políticas. Para mais informações, consulte Tutorial: construção manual de um proxy de API SOAP para REST no Apigee Edge.

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

Esta seção explica como criar um proxy de API SOAP RESTful com a opção REST para SOAP para REST no assistente "Criar um proxy".

Visão geral

A opção REST para SOAP para REST processa o WSDL para gerar um proxy de API RESTful. O Edge determina no WSDL as operações compatíveis, os parâmetros de entrada e assim por diante. O Edge "adivinha" qual método HTTP usar para cada operação. Normalmente, o Edge traduz 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 interface do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Develop > API Proxies 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 o arquivo WSDL.
    Campo Descrição
    Fornecer arquivo WSDL

    Selecione a origem do WSDL.

    • De endereço da Web (URL): insira ou cole o URL do WSDL.
    • Do meu computador: faça upload de um arquivo WSDL do seu diretório local. É possível fazer upload de vários arquivos se houver dependências.
  6. Clique em Validar para validar o WSDL.
  7. Insira 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 encaminhar as mensagens de solicitação recebidas para o proxy da API adequado.

    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 de base como o mesmo valor que o caminho de base de outro proxy de API, o Edge removerá automaticamente o proxy da API quando você salvá-lo. 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 Common policies do assistente, configure os itens a seguir:
    • 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 para o 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 para SOAP para REST.

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

  11. Selecione um Tipo de porta no menu suspenso para especificar qual conjunto de operações você quer usar. Em WSDL, os elementos de tipo de porta definem as operações que podem ser chamadas em um serviço da Web.
  12. Mude o caminho da API REST para uma operação, se quiser. O caminho será usado como o nome do recurso no URL do proxy de API.
  13. Se quiser, mude o Verbo (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
    O novo proxy de API é criado e implantado no ambiente selecionado.
  18. Clique em Edit proxy para exibir a página de detalhes do proxy de API.

Classic Edge (nuvem privada)

Para criar um proxy de API RESTful para um serviço baseado em SOAP usando a interface 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 de criação de proxy, selecione "Serviço SOAP".
  5. Clique em Próxima.
  6. Na página "Detalhes", faça estas seleções. Clique em Validar depois de selecionar um WSDL.
    Neste campo faça isso
    WSDL

    Selecione a origem do WSDL.

    • URL: insira o URL do WSDL que você quer usar.
    • Arquivo: escolha um arquivo WSDL no seu sistema de arquivos. Em casos em que há outros arquivos dependentes, você pode 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 de 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 encaminhar as mensagens de solicitação recebidas para o proxy da API adequado.

    Observação: o caminho base do proxy de API assume 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 único. 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 de base como o mesmo valor que o caminho de base de outro proxy de API, o Edge removerá automaticamente o proxy da API quando você salvá-lo. 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 para SOAP para REST.

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

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

  9. Selecione na coluna "Tipo de porta" o conjunto de operações que você quer usar. Em WSDL, os elementos de tipo de porta definem as operações que podem ser chamadas em um serviço da Web.
  10. Se quiser, mude o método HTTP associado à operação.

    Observação:o Edge faz uma "melhor estimativa" ao determinar o método HTTP a ser usado em cada operação. O GET geralmente é preferível porque as solicitações GET podem ser armazenadas em cache.
  11. Se quiser, mude o caminho da API REST de uma operação. O caminho será usado como o nome do recurso no URL do proxy de 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 Criar e implantar. 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. 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 oferece 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 de caminho.

Sobre o proxy final

Quando o Edge gera um proxy de API com base em um WSDL, o proxy resultante é 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, confira o fluxo resultante na visualização "Desenvolver" da interface de gerenciamento de API. Lá, você pode 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 para JSON, extrair o 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 conferir a especificação OpenAPI gerada automaticamente para esse 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 "Proxy de passagem" permite criar um proxy que passa a mensagem SOAP em uma solicitação para o serviço de back-end "intacta", facilitando a criação de um proxy para um serviço da Web baseado em SOAP. Em segundo plano, o Edge processa automaticamente todas as transformações e outras atividades de fluxo. Por exemplo, se a solicitação estiver no formato JSON, o Edge converterá em uma mensagem XML SOAP válida com namespaces corretos antes de enviar por POST ao 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 retorná-la ao cliente. Além disso, o Edge configura o endpoint de destino de 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 que você acesse o WSDL. O endereço do WSDL hospedado no Edge, http(s)://[proxy_domain]/[proxy_base_path]?wsdl, se torna o novo URL do endpoint de serviço para clientes que chamam o serviço SOAP pelo proxy.

Etapas básicas

Edge

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

  1. Faça login em apigee.com/edge.
  2. Selecione Develop > API Proxies 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 origem do WSDL.

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

    Nome do proxy de API.
    Caminho base

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

    Observação: para recomendações da Apigee sobre controle de versão de APIs, consulte Controle de versão no e-book Design da API da Web: o link ausente.

    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. Se você editar esse proxy e definir o caminho de base dele como o mesmo de outro proxy de API, ele será removido automaticamente quando você o salvar. É necessário editar o caminho de base antes de reimplantar.

    Como usar um caractere curinga em caminhos base

    É possível usar um ou mais caracteres curinga /*/ nos caminhos de base do proxy de API para preparar seus proxies para o futuro. Por exemplo, um caminho 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. Observe que /**/ não é compatível.

    Observação: o caminho base do proxy de API assume 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 Common policies do assistente, configure os itens a seguir:
  8. Na página WSDL, selecione o tipo de proxy de API SOAP de passagem.

  9. Selecione um Tipo de porta no menu suspenso para especificar qual conjunto de operações você quer usar. Em 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
    O novo proxy de API é criado e implantado no ambiente selecionado.
  13. Clique em Edit proxy para exibir a página de detalhes do proxy de API.

Classic Edge (nuvem privada)

Para criar um proxy de passagem para um serviço baseado em SOAP usando a interface 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 de criação de proxy, selecione "Serviço SOAP".
  5. Clique em Próxima.
  6. Na página "Detalhes", faça estas seleções. Clique em Validar depois de selecionar um WSDL.
    Neste campo faça isso
    WSDL

    Selecione a origem do WSDL.

    • URL: insira o URL do WSDL que você quer usar.
    • Arquivo: escolha um arquivo WSDL no seu sistema de arquivos. Em casos em que há outros arquivos dependentes, você pode 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 de proxy O caminho base do proxy é um fragmento de URI que identifica exclusivamente a API exposta por esse proxy de API. Os Serviços de API usam o URI do caminho base para corresponder e encaminhar as mensagens de solicitação recebidas para o proxy de API adequado. 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 de API é implantado. É recomendável incluir um número de versão no nome do projeto, por exemplo, /v1/delayedstockquote. Isso determina como sua API é invocada por apps consumidores.

    Observação: o caminho base do proxy assume 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 de API SOAP de passagem.

    Observação:uma tabela aparece listando cada operação WSDL e o payload SOAP correspondente. Esse é o payload "transmitido" ao serviço SOAP de back-end.

    Na página WSDL, o tipo de proxy de API é definido como "Pass-Through SOAP", e uma lista de operações, como "GetQuote", é organizada por tipo de porta.
  10. Selecione na coluna "Tipo de porta" o conjunto de operações que você quer usar. Em 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 Criar e implantar. 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 transferência, o proxy resultante é 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 transferência, confira o fluxo resultante na visualização "Desenvolver" da interface de gerenciamento de APIs. Lá, você pode ver exatamente quais políticas foram adicionadas.

Por exemplo, a figura a seguir mostra a parte do Preflow do endpoint de destino de um proxy de transferência. 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 para 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 mostram o fluxo da solicitação para a resposta, e os ícones mostram as políticas.

WSDL hospedado no Edge: para conferir o WSDL hospedado no Edge gerado para esse tipo de proxy, acesse http(s)://[proxy_domain]/[proxy_base_path]?wsdl.

Desenvolvimento avançado de proxy SOAP para REST

As seções anteriores abordaram 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 de SOAP para REST, ignore a automação fornecida pelo assistente e crie um proxy adicionando e configurando políticas manualmente para obter o comportamento desejado. Para mais informações, consulte Tutorial: construção manual de um proxy de API SOAP para REST no Apigee Edge.