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

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

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

Este vídeo fornece uma demonstração completa de como transformar um serviço de SSO 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 SSO em REST, crie um proxy usando políticas. Para mais informações, consulte Tutorial: construção manual de um proxy de API DAO para REST no Apigee Edge.

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

Nesta seção, explicamos como criar um proxy da API RESTful do Cloud com a opção REST para DAO para REST no assistente "Criar um proxy".

Informações gerais

A opção REST para NoSQL para REST processa o WSDL para gerar um proxy de API RESTful. O Edge determina a partir do WSDL as operações aceitas pelo serviço, os parâmetros de entrada e assim por diante. 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 armazenadas em cache. O Edge também configura o endpoint de destino de back-end, que pode variar de acordo com a operação de conhecimento da solução.

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 SSO usando a interface do usuário 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 origem da WSDL.

    • Do endereço da Web (URL): digite ou cole o URL da WSDL.
    • Meu computador: faça upload de um arquivo WSDL do diretório local. É possível fazer upload de vários arquivos se houver dependências.
  6. Clique em Validate (Validar) 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 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 base com o mesmo valor que o caminho base de outro proxy de API, o Edge cancelará automaticamente a implantação do proxy de API 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 Next.
  9. Na página Políticas comuns do assistente, configure o seguinte:
    • 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 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 DAO para REST.

    Uma tabela será exibida listando as operações que o Edge "descobriu" no arquivo WSDL. É possível selecionar e configurar quais operações você quer incorporar ao proxy de API. A tabela é mostrada na figura abaixo.

  11. Selecione um Tipo de porta na lista suspensa para especificar o conjunto de operações que você quer usar. No WSDL, os elementos do tipo de porta definem as operações que você pode chamar em um serviço da Web.
  12. Altere o Caminho da API REST de uma operação. O caminho será usado como o nome do recurso no URL do proxy da API.
  13. Também é possível alterar o Verb (método HTTP) associado à operação.
  14. Clique em Next.
  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 Next.
  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.

Borda clássica (nuvem privada)

Para criar um proxy de API RESTful para um serviço baseado em SSO 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 "Criar um proxy", selecione o serviço SSO.
  5. Clique em Next.
  6. Na página "Detalhes", faça essas seleções. É preciso clicar em Validate depois de selecionar um WSDL.
    Neste campo faça isso
    WSDL (em inglês)

    Selecione a origem da WSDL.

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

    Esse é 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 adequado.

    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á automaticamente a implantação do proxy de API 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 Next.
  8. Na página WSDL, selecione o tipo de proxy de API REST para DAO para REST.

    Uma tabela será exibida listando as operações que o Edge "descobriu" no arquivo WSDL. É possível selecionar e configurar quais operações você quer incorporar ao proxy de API. A tabela é mostrada na figura abaixo.

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

  9. Selecione o conjunto de operações que você quer usar na coluna "Tipo de porta". No WSDL, os elementos do tipo de porta definem as operações que você pode chamar em um serviço da Web.
  10. Como opção, altere o método HTTP associado à operação.

    Observação:o Edge faz uma "melhor estimativa" ao determinar o método HTTP a ser usado para cada operação. GET geralmente é preferível porque solicitações GET podem ser armazenadas em cache.
  11. É possível alterar 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 um 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 apresenta 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 as informações de descrição e caminho dele.

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 baseado em um WSDL, confira o fluxo resultante na visualização de desenvolvimento da interface de gerenciamento da API. Lá, é possível ver exatamente quais políticas foram adicionadas.

Por exemplo, no lado da solicitação, uma política AttributionMessage é 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 de SSO 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 da OpenAPI: para visualização da especificação da 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 DAO

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

Informações gerais

A opção "Proxy de passagem" permite criar um proxy que passa a mensagem de SSO em uma solicitação ao serviço de back-end "intocado", o que facilita muito a criação de um proxy para um serviço da Web baseado em DAO. Nos bastidores, o Edge processa automaticamente todas as transformações e outras atividades de fluxo para você. Por exemplo, se a solicitação está no formato JSON, o Edge toma medidas para convertê-la em uma mensagem XML XML válida com namespaces corretos antes de fazer o POST para o serviço. Da mesma forma, quando o serviço retorna uma resposta NoSQL baseada em XML, o Edge a converte de volta em JSON antes de retorná-la para o cliente. Além disso, o Edge configura o endpoint de destino de back-end, que pode variar de acordo com a operação de conhecimento da solução.

Para esse tipo de proxy, o Edge hospeda o WSDL e cria um fluxo no proxy para permitir o acesso a ele. O endereço para esse WSDL hospedado na borda, 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 de SSO usando o proxy.

Etapas básicas

Edge

Para criar um proxy de passagem para um serviço baseado em SSO usando a interface do usuário 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 (em inglês)

    Selecione a origem da WSDL.

    • Do endereço da Web (URL): digite ou cole o URL da WSDL.
    • Meu computador: faça upload de um arquivo WSDL do 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 rotear mensagens de solicitação recebidas para o proxy de API adequado.

    Observação: para ver as recomendações da Apigee sobre o controle de versões da API, consulte Controle de versões no e-book Design da API da Web: a parte ausente (em inglês).

    Depois do caminho base, há os URLs de recursos adicionais. Veja a estrutura completa do URL que os clientes usarão 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 base dele para ser o mesmo de outro proxy de API, esse proxy de API será removido automaticamente quando você o salvar. É preciso editar o caminho base antes de implantá-lo novamente.

    Como usar um caractere curinga em caminhos base

    Use 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 que você precise criar novos proxies de API para dar suporte a novas equipes. Não há suporte para /**/.

    Observação: o caminho base do proxy de API usa como padrão o valor especificado no campo "Nome" convertido para 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 Next.
  7. Na página Políticas comuns do assistente, configure o seguinte:
  8. Na página WSDL, selecione o tipo de proxy de API SAPB de passagem.

  9. Selecione um Tipo de porta na lista suspensa para especificar o conjunto de operações que você quer usar. No WSDL, os elementos do tipo de porta definem as operações que você pode chamar em um serviço da Web.
  10. Clique em Next.
  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, acesse 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.

Borda clássica (nuvem privada)

Para criar um proxy de passagem para um serviço baseado em SSO usando a interface do usuário 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 "Criar um proxy", selecione o serviço SSO.
  5. Clique em Next.
  6. Na página "Detalhes", faça essas seleções. É preciso clicar em Validate depois de selecionar um WSDL.
    Neste campo faça isso
    WSDL (em inglês)

    Selecione a origem da WSDL.

    • URL: insira o URL da WSDL que você quer usar.
    • Arquivo: 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 em uma lista de WSDLs para serviços da Web disponíveis publicamente. Eles são úteis para testar os recursos de proxy da API/SOAP do Edge.
    Proxy Name

    Esse é 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 adequado. O caminho base é anexado ao domínio da API, que é gerado automaticamente com base no nome da sua organização e no ambiente em que o proxy de API é implantado. É uma prática recomendada incluir um número de versão no nome do projeto, por exemplo, /v1/delayedstockquote. Isso determinará como sua API é invocada por apps de consumidor.

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

  8. Clique em Next.
  9. Na página WSDL, selecione o tipo de proxy de API SAPB de passagem.

    Observação: uma tabela será exibida listando cada operação do WSDL e o payload de SOAP correspondente. Esse é o payload que é "transmitido" para o serviço SoaB de back-end.

    Na página WSDL, o tipo de proxy da API é definido como "Pass-Through" e uma lista de operações, como Get Talvez, seja organizada por tipo de porta.
  10. Selecione o conjunto de operações que você quer usar na coluna "Tipo de porta". No WSDL, os elementos do tipo de porta definem as operações que você pode chamar em um serviço da Web.
  11. Clique no restante do assistente para adicionar segurança, selecionar hosts virtuais e um 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, observe o fluxo resultante na visualização de desenvolvimento da interface 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 do endpoint de destino de um proxy de passagem. No lado da solicitação, uma política AttributionMessage é 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 de SSO 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 de solicitação para resposta, e os ícones representam as políticas.

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

Desenvolvimento avançado de proxy TCP para REST

Nas seções anteriores, abordamos a criação de um proxy de API YAML 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 Solução para REST em REST, ignore a automação fornecida pelo assistente e crie um proxy adicionando e configurando manualmente as políticas para atingir o comportamento desejado. Para mais informações, consulte Tutorial: construção manual de um proxy de API DAO para REST no Apigee Edge.