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

Você está visualizando 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. Uma gera uma interface RESTful para o serviço SOAP de back-end, e a outra realiza uma passagem da mensagem SOAP para o back-end. Ambas as 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 ter mais controle sobre a transformação 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 to SOAP to REST no assistente "Criar um proxy".

Visão geral

A opção REST to SOAP to REST processa o WSDL para gerar um proxy de API RESTful. O Edge determina as operações com suporte do serviço, os parâmetros de entrada e assim por diante, com base no WSDL. O Edge "adivinha" qual método HTTP usar para cada operação. Normalmente, o Edge converte operações em solicitações GET, que têm a vantagem de serem cacháveis. O Edge também 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 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 o 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. Você pode 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 vai 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 do 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. No WSDL, os elementos do tipo de porta definem as operações que podem ser chamadas em um serviço da Web.
  12. Opcionalmente, mude o Caminho da API REST para uma operação. O caminho será usado como o nome do recurso no URL do proxy da API.
  13. Mude o Verbo (método HTTP) associado à operação, se quiser.
  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 Create and deploy
    Seu 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.

Edge clássico (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 "Build a Proxy", selecione "SOAP service".
  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.
    • File: escolha um arquivo WSDL no sistema de arquivos. Nos casos em que há outros arquivos dependentes, você pode selecionar todos eles.
    • Exemplo de URL: selecione 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

    É 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 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 vai 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 da API está 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. No WSDL, os elementos do tipo de porta definem as operações que podem ser chamadas em um serviço da Web.
  10. Se preferir, mude o método HTTP associado à operação.

    Observação:o Edge faz uma "melhor estimativa" para determinar o método HTTP a ser usado em cada operação. Geralmente, o método GET é preferido porque as solicitações GET podem ser armazenadas em cache.
  11. Opcionalmente, mude 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. Um conjunto de recursos foi criado com base nas operações encontradas no arquivo WSDL.

    Na página de visão geral do proxy, a lista Resources 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 conferir 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 é 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. Nele, você pode conferir exatamente quais políticas foram adicionadas.

Por exemplo, na 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 para 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 da OpenAPI: para conferir a especificação da 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 da OpenAPI.

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

Esta seção explica como criar um proxy de passagem com a opção Pass-Through Proxy 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 "inalterada", facilitando a criação de um proxy para um serviço da Web baseado em SOAP. Por trás das cortinas, o Edge processa automaticamente todas as transformações e outras atividades do fluxo. Por exemplo, se a solicitação estiver no formato JSON, o Edge vai converter a solicitação em uma mensagem SOAP XML válida com os namespaces corretos antes de fazer o POST para o serviço. Da mesma forma, quando o serviço retorna uma resposta SOAP baseada em XML, o Edge a traduz para JSON antes de retornar ao 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 que você possa acessá-lo. O endereço desse 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. Você pode 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 do 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 vão usar para chamar o proxy da 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 como o mesmo de outro proxy de API, esse proxy será desimplantado automaticamente quando você o salvar. É necessário editar o caminho de base antes de reimplantá-lo.

    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 de base /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem que você precise 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 de 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 Pass-Through SOAP.

  9. Selecione um Tipo de porta no menu suspenso para especificar qual conjunto de operações você quer usar. No WSDL, os elementos do 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 Create and deploy
    Seu 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.

Edge clássico (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 "Build a Proxy", selecione "SOAP service".
  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.
    • File: escolha um arquivo WSDL no sistema de arquivos. Nos casos em que há outros arquivos dependentes, você pode selecionar todos eles.
    • Exemplo de URL: selecione 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

    É o nome do proxy que você está criando.
    Caminho base de proxy O caminho de base do proxy é um fragmento de URI que identifica exclusivamente a API exposta por esse proxy. Os serviços de API usam o URI do caminho base para corresponder e encaminhar as mensagens de solicitação recebidas para o proxy da API adequado. O caminho de 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 vai determinar como a API é invocada pelos apps de consumo.

    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 Pass-Through SOAP.

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

    Na página WSDL, o tipo de proxy da API é definido como SOAP de passagem 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. No WSDL, os elementos do 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 é 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, confira o fluxo resultante na visualização "Desenvolver" da interface de gerenciamento de API. Nele, você pode conferir exatamente quais políticas foram adicionadas.

Por exemplo, a figura a seguir mostra a parte do pré-fluxo do endpoint de destino de um proxy de passagem. Na 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 mostram o fluxo da solicitação para a resposta e os ícones representam 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 granular sobre a transformação SOAP para REST, ignore a automação fornecida pelo assistente e crie um proxy adicionando e configurando manualmente as políticas para conseguir o comportamento desejado. Para mais informações, consulte Tutorial: construção manual de um proxy de API SOAP para REST no Apigee Edge.