Expón un servicio SOAP como un proxy de API

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X. Información

En este tema, se explica cómo crear proxies de API para servicios web basados en SOAP. Puedes crear dos tipos de proxies de SOAP en Edge. Uno genera una interfaz RESTful para el servicio de SOAP de backend y el otro realiza una “transferencia” del mensaje de SOAP al backend. Ambas técnicas se describen en este tema.

En este video, se proporciona una demostración de extremo a extremo para convertir un servicio de SOAP en un servicio de REST con Apigee Edge a través del asistente de proxy de la API. Sin embargo, si deseas tener más control sobre la transformación de SOAP a REST, puedes compilar un proxy mediante políticas. Para obtener más información, consulta el Instructivo: Construcción manual de un proxy de API de SOAP a REST en Apigee Edge.

Crea un proxy de API RESTful para un servicio basado en SOAP

En esta sección, se explica cómo crear un proxy de API de SOAP RESTful con la opción REST a SOAP a REST en el asistente de compilación de un proxy.

Descripción general

La opción REST a SOAP a REST procesa el WSDL para generar un proxy de API de RESTful. Edge determina a partir del WSDL las operaciones admitidas del servicio, los parámetros de entrada, etcétera. El perímetro "adivina" qué método HTTP usar para cada operación. Por lo general, Edge traduce las operaciones en solicitudes GET, que tienen la ventaja de que se pueden almacenar en caché. Edge también configura el extremo de destino del backend, que puede variar según la operación de SOAP.

Para este tipo de proxy, Edge genera de forma automática una Especificación de OpenAPI, que puedes usar para crear documentación de API.

Pasos básicos

Conexión de integración

Para crear un proxy de la API de RESTful a un servicio basado en SOAP mediante la IU de Edge, haz lo siguiente:

  1. Accede a apigee.com/edge.
  2. Selecciona Desarrollar > Proxies de API en la barra de navegación izquierda.
  3. Haz clic en +Proxy.
  4. Haz clic en Servicio SOAP.
  5. En la página Detalles del proxy, proporciona el archivo WSDL.
    Campo Descripción
    Proporciona el archivo WSDL

    Selecciona la fuente del WSDL.

    • Dirección web (URL) de origen: Ingresa o pega la URL del WSDL.
    • Desde mi computadora: Sube un archivo WSDL desde tu directorio local. Si hay dependencias, puedes subir varios archivos.
  6. Haga clic en Validate para validar el WSDL.
  7. Ingresa los siguientes detalles del proxy:
    Campo Descripción
    Nombre Es el nombre que se muestra para tu API. Especifica caracteres alfanuméricos, guiones (-) o guiones bajos (_).
    Ruta base

    Es el fragmento de URI que aparece después de la dirección http(s)://[host] del proxy de API. Edge usa el URI de la ruta de acceso base para hacer coincidir y enrutar los mensajes de solicitud entrantes al proxy de API adecuado.

    NOTA: La ruta base del proxy de API se configura de forma predeterminada como el valor especificado para el campo Name, convertido en minúsculas.

    Luego de la ruta base, se encuentran las URL de recursos adicionales. A continuación, se muestra la estructura completa de la URL que los clientes usarán para llamar al proxy de API:

    https://[host]/base_path/conditional_flow_path

    NOTA: La ruta base debe ser única. No puedes implementar dos proxies de API con la misma ruta base. Si editas un proxy de API implementado y estableces la ruta de acceso base con el mismo valor que la ruta base de otro proxy de API, Edge anula la implementación automática del proxy de API cuando lo guardas. Antes de poder volver a implementar el proxy de API, debes editar la ruta base para que sea única.

    Use comodines en las rutas base

    Usa uno o más comodines /*/ en las rutas base del proxy de API con el fin de preparar a los proxies de API para el futuro. Por ejemplo, una ruta base de /team/*/members permite que los clientes llamen a https://[host]/team/blue/members y a https://[host]/team/green/members sin necesidad de crear proxies de API nuevos para admitir equipos nuevos. Ten en cuenta que no se admite /**/.
    Descripción Es la descripción de la API (opcional).
  8. Presiona Siguiente.
  9. En la página Políticas comunes del asistente, configura lo siguiente:
    • Los requisitos de autorización de seguridad en Seguridad: Autorización. Consulta Cómo agregar seguridad.
    • La compatibilidad con el uso compartido de recursos multiorigen (CORS) en Seguridad: Navegador. Consulta Cómo agregar compatibilidad con CORS.
    • Las cuotas para proteger el servicio de backend del tráfico alto en Cuota. Consulta Cuotas (No está disponible si se selecciona la autorización de transferencia).
  10. En la página Operaciones de WSDL, selecciona el tipo de proxy de API REST a SOAP a REST.

    Aparecerá una tabla con las operaciones que Edge “descubrió” en el archivo WSDL. Puedes seleccionar y configurar las operaciones que deseas incorporar en tu proxy de API. La tabla se muestra en la siguiente imagen.

  11. Selecciona un Tipo de puerto del menú desplegable para especificar el conjunto de operaciones que deseas usar. En el WSDL, los elementos de tipo de puerto definen las operaciones a las que puedes llamar en un servicio web.
  12. De manera opcional, cambia la ruta de acceso de la API de REST para una operación. La ruta se utilizará como el nombre del recurso en la URL del proxy de API.
  13. De manera opcional, cambia el Verbo (método HTTP) asociado con la operación.
  14. Presiona Siguiente.
  15. En la página Hosts virtuales del asistente, selecciona los hosts virtuales a los que se vinculará el proxy de API cuando se implemente. Para obtener más información, consulta Información acerca de los hosts virtuales.
  16. Presiona Siguiente.
  17. Selecciona los entornos de implementación y haz clic en Create and deploy
    Tu nuevo proxy de API se creará y se implementará en el entorno seleccionado.
  18. Haz clic en Editar proxy para mostrar la página de detalles del proxy de API.

Versión clásica de Edge (nube privada)

Para crear un proxy de la API de RESTful a un servicio basado en SOAP mediante la IU clásica de Edge, haz lo siguiente:

  1. Accede a http://ms-ip:9000, donde ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.
  2. Selecciona API > Proxies de API en la barra de navegación superior.
  3. Haz clic en + API Proxy.
  4. En el asistente Build a Proxy, selecciona SOAP Service.
  5. Presiona Siguiente.
  6. En la página Detalles, realiza estas selecciones. Debes hacer clic en Validate después de seleccionar un WSDL.
    En este campo haz lo siguiente Sigue estas recomendaciones
    WSDL

    Selecciona la fuente del WSDL.

    • URL: Ingresa la URL del WSDL que deseas usar.
    • File: Elige un archivo WSDL en tu sistema de archivos. En los casos en que haya archivos dependientes adicionales, puedes seleccionarlos todos.
    • URL de ejemplo: Selecciona de una lista de WSDL para servicios web disponibles de forma pública. Son útiles para probar las funciones del proxy de SOAP/API de Edge.
    Proxy name

    Este es el nombre del proxy que estás creando.
    Ruta de acceso base del proxy

    Es el fragmento de URI que aparece después de la dirección http(s)://[host] del proxy de API. Edge usa el URI de la ruta de acceso base para hacer coincidir y enrutar los mensajes de solicitud entrantes al proxy de API adecuado.

    Nota: La ruta base del proxy de API se configura de forma predeterminada como el valor especificado para el campo Name, convertido en minúsculas.

    Luego de la ruta base, se encuentran las URL de recursos adicionales. A continuación, se muestra la estructura completa de la URL que los clientes usarán para llamar al proxy de API:

    https://[host]/base_path/conditional_flow_path

    Nota: La ruta base debe ser única. No puedes implementar dos proxies de API con la misma ruta base. Si editas un proxy de API implementado y estableces la ruta de acceso base con el mismo valor que la ruta base de otro proxy de API, Edge anula la implementación automática del proxy de API cuando lo guardas. Antes de poder volver a implementar el proxy de API, debes editar la ruta base para que sea única.

    Use comodines en las rutas base

    Usa uno o más comodines /*/ en las rutas base del proxy de API con el fin de preparar a los proxies de API para el futuro. Por ejemplo, una ruta base de /team/*/members permite que los clientes llamen a https://[host]/team/blue/members y a https://[host]/team/green/members sin necesidad de crear proxies de API nuevos para admitir equipos nuevos. Ten en cuenta que no se admite /**/.
    Descripción Una descripción breve del proxy.
  7. Presiona Siguiente.
  8. En la página WSDL, selecciona el tipo de proxy de API REST a SOAP a REST.

    Aparecerá una tabla con las operaciones que Edge “descubrió” en el archivo WSDL. Puedes seleccionar y configurar las operaciones que deseas incorporar en tu proxy de API. La tabla se muestra en la siguiente imagen.

    En la página de operaciones de WSDL, el tipo de proxy de API se establece en REST a SOAP a REST, y una tabla muestra una fila de resultados con la operación de agregar.

  9. En la columna Tipo de puerto, selecciona el conjunto de operaciones que quieres usar. En el WSDL, los elementos de tipo de puerto definen las operaciones a las que puedes llamar en un servicio web.
  10. De manera opcional, cambia el método HTTP asociado con la operación.

    Nota: Edge realiza la mejor estimación para determinar el método HTTP que se usará en cada operación. Generalmente, se prefiere GET porque las solicitudes GET se pueden almacenar en caché.
  11. De manera opcional, cambia la ruta de la API de REST para una operación. La ruta se utilizará como el nombre del recurso en la URL del proxy de API.
  12. Haz clic en el resto del asistente para agregar seguridad, seleccionar hosts virtuales y entorno de implementación.
  13. En la página Build, haz clic en Build and Deploy. Edge genera e implementa el nuevo proxy de API según el WSDL.
  14. Ve a la página de resumen del proxy de API nuevo. Ten en cuenta que se construyó un conjunto de recursos en función de las operaciones descubiertas en el archivo WSDL.

    En la página Descripción general del proxy, la lista Recursos proporciona una descripción detallada de la API nueva, sus operaciones y parámetros. Puedes considerar esta representación como la documentación de referencia de la API. Edge genera esta vista del modelo de la API de forma automática. Solo expande un recurso para ver su descripción y la información de su ruta.

Acerca del proxy final

Cuando Edge genera un proxy de API basado en un WSDL, el proxy resultante es, en realidad, un flujo complejo que incluye políticas para transformar datos, extraer y configurar variables, manipular mensajes y mucho más. Una vez que generes un proxy basado en un WSDL, consulta el flujo resultante en la vista de desarrollo de la IU de administración de la API. Allí puedes ver exactamente qué políticas se agregaron.

Por ejemplo, en el lado de la solicitud, se usa una política deAssignMessage para establecer la URL de destino. En el lado de la respuesta, las políticas se ejecutan para transformar la respuesta de XML a JSON, extraer la parte del cuerpo de SOAP en una variable y configurar el mensaje de respuesta. Estas políticas (y otras) se agregan automáticamente cuando creas el proxy.

OpenAPI Spec: Si quieres ver la especificación de OpenAPI generada de forma automática para este proxy, visita http(s)://[proxy_domain]/[proxy_base_path]/openapi.json. Sin embargo, la conversión no siempre es precisa, ya que no todas las reglas de un esquema XML se pueden representar en una especificación de OpenAPI.

Crea un proxy de paso a un servicio basado en SOAP

En esta sección, se explica cómo crear un proxy de paso con la opción Proxy de transferencia en el cuadro de diálogo Crear proxy nuevo.

Descripción general

La opción de proxy de transferencia te permite crear un proxy que pasa el mensaje de SOAP en una solicitud al servicio de backend “sin tocar”, lo que facilita la creación de un proxy para un servicio web basado en SOAP. En segundo plano, Edge controla automáticamente todas las transformaciones y otras actividades de flujo. Por ejemplo, si la solicitud está en formato JSON, Edge toma medidas para convertirla en un mensaje de SOAP XML válido con los espacios de nombres correctos antes de PUBLICARla en el servicio. Del mismo modo, cuando el servicio muestra una respuesta de SOAP basada en XML, Edge la traduce de nuevo a JSON antes de devolvérsela al cliente. Además, Edge configura el extremo de destino del backend, que puede variar según la operación de SOAP.

Para este tipo de proxy, Edge aloja el WSDL y crea un flujo en el proxy para que puedas acceder a él. La dirección de este WSDL alojado en el perímetro, http(s)://[proxy_domain]/[proxy_base_path]?wsdl, se convierte en la nueva URL del extremo de servicio para los clientes que llaman al servicio de SOAP a través del proxy.

Pasos básicos

Conexión de integración

Para crear un proxy de paso a un servicio basado en SOAP mediante la IU de Edge, haz lo siguiente:

  1. Accede a apigee.com/edge.
  2. Selecciona Desarrollar > Proxies de API en la barra de navegación izquierda.
  3. Haz clic en +Proxy.
  4. Haz clic en Servicio SOAP.
  5. En la página Detalles del proxy, proporciona los detalles de WSDL.
    Campo Descripción
    WSDL

    Selecciona la fuente del WSDL.

    • Dirección web (URL) de origen: Ingresa o pega la URL del WSDL.
    • Desde mi computadora: Sube un archivo WSDL desde tu directorio local. Si hay dependencias, puedes subir varios archivos.
    Nombre

    Nombre del proxy de API.
    Ruta base

    Fragmento de URI después de la dirección http(s)://[host] del proxy de API. Edge usa el URI de la ruta de acceso base para hacer coincidir y enrutar los mensajes de solicitud entrantes al proxy de API adecuado.

    Nota: Para conocer las recomendaciones de Apigee sobre el control de versiones de la API, consulta Control de versiones en el libro electrónico Diseño de API web: El vínculo perdido.

    Después de la ruta de acceso base, se encuentran las URLs de recursos adicionales. Esta es la estructura de URL completa que los clientes usarán para llamar a tu proxy de API:

    https://[host]/base_path/conditional_flow_path

    Nota: La ruta base debe ser única. Si luego editas este proxy y estableces su ruta base para que sea la misma que la de otro proxy de API, este proxy de API se anula automáticamente cuando lo guardas. Debes editar la ruta base antes de volver a implementarla.

    Usa un comodín en rutas de acceso base

    Puedes usar uno o más comodines /*/ en las rutas base del proxy de API para preparar los proxies para el futuro. Por ejemplo, una ruta base de /team/*/members permite a los clientes llamar a https://[host]/team/blue/members y https://[host]/team/green/members sin necesidad de crear proxies de API nuevos para brindar asistencia a equipos nuevos. Ten en cuenta que /**/ no es compatible.

    Nota: La ruta base del proxy de API se establece de forma predeterminada en el valor especificado para el campo Nombre convertido a minúsculas, a menos que edites el contenido de forma explícita en el campo Ruta base.
    Descripción Es la descripción de la API (opcional).
  6. Presiona Siguiente.
  7. En la página Políticas comunes del asistente, configura lo siguiente:
  8. En la página WSDL, selecciona el tipo de proxy de API SOAP de transferencia.

  9. Selecciona un Tipo de puerto del menú desplegable para especificar el conjunto de operaciones que deseas usar. En el WSDL, los elementos de tipo de puerto definen las operaciones a las que puedes llamar en un servicio web.
  10. Presiona Siguiente.
  11. En la página Hosts virtuales del asistente, selecciona los hosts virtuales a los que se vinculará el proxy de API cuando se implemente. Para obtener más información, consulta Acerca de los hosts virtuales.
  12. Selecciona los entornos de implementación y haz clic en Create and deploy
    Tu nuevo proxy de API se creará y se implementará en el entorno seleccionado.
  13. Haz clic en Editar proxy para mostrar la página de detalles del proxy de API.

Versión clásica de Edge (nube privada)

Para crear un proxy de paso a un servicio basado en SOAP mediante la IU de Edge clásica, sigue estos pasos:

  1. Accede a http://ms-ip:9000, donde ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.
  2. Selecciona API > Proxies de API en la barra de navegación superior.
  3. Haz clic en + API Proxy.
  4. En el asistente Build a Proxy, selecciona SOAP Service.
  5. Presiona Siguiente.
  6. En la página Detalles, realiza estas selecciones. Debes hacer clic en Validate después de seleccionar un WSDL.
    En este campo haz lo siguiente Sigue estas recomendaciones
    WSDL

    Selecciona la fuente del WSDL.

    • URL: Ingresa la URL del WSDL que deseas usar.
    • File: Elige un archivo WSDL en tu sistema de archivos. En los casos en que haya archivos dependientes adicionales, puedes seleccionarlos todos.
    • URL de ejemplo: Selecciona de una lista de WSDL para servicios web disponibles de forma pública. Son útiles para probar las funciones del proxy de SOAP/API de Edge.
    Proxy name

    Este es el nombre del proxy que estás creando.
    Ruta de acceso base del proxy La ruta base del proxy es un fragmento de URI que identifica de forma única la API que expone este proxy de API. Los Servicios de API usan el URI de ruta base para hacer coincidir y enrutar los mensajes de solicitud entrantes al proxy de API adecuado. (la ruta base se adjunta al dominio de la API, que se genera automáticamente según el nombre de tu organización y el entorno en el que se implementa el proxy de API). Se recomienda incluir un número de versión en el nombre del proyecto, por ejemplo, /v1/delayedstockquote. Esto determinará cómo las apps para consumidores invocan tu API.

    Nota: De manera predeterminada, la ruta base del proxy tiene el valor especificado para el nombre del proxy convertido a minúsculas, a menos que edites el contenido de forma explícita en el campo Ruta base del proxy.
    Descripción Una descripción breve del proxy.

  8. Presiona Siguiente.
  9. En la página de WSDL, selecciona el tipo de proxy de API SOAP de transferencia.

    Nota: Aparecerá una tabla en la que se enumera cada operación WSDL y su carga útil de SOAP correspondiente. Esta es la carga útil que se “pasa” al servicio de SOAP de backend.

    En la página WSDL, el tipo de proxy de API se establece en SOAP de transferencia y una lista de operaciones como GetQuote está organizada por tipo de puerto.
  10. En la columna Tipo de puerto, selecciona el conjunto de operaciones que quieres usar. En el WSDL, los elementos de tipo de puerto definen las operaciones a las que puedes llamar en un servicio web.
  11. Haz clic en el resto del asistente para agregar seguridad, seleccionar hosts virtuales y entorno de implementación.
  12. En la página Build, haz clic en Build and Deploy. Edge genera e implementa el nuevo proxy de API según el WSDL.

Acerca del proxy final

Cuando Edge genera un proxy de paso, el proxy resultante es, en realidad, un flujo complejo que incluye políticas para transformar datos, extraer y configurar variables, manipular mensajes y mucho más. Después de generar el proxy de transferencia, observa el flujo resultante en la vista de desarrollo de la IU de administración de la API. Allí puedes ver exactamente qué políticas se agregaron.

Por ejemplo, en la siguiente figura, se muestra la parte de flujo previo del extremo de destino de un proxy de transferencia. En el lado de la solicitud, se usa una política deAssignMessage para configurar la URL de destino. En el lado de la respuesta, las políticas se ejecutan para transformar la respuesta de XML a JSON, extraer la parte del cuerpo de SOAP en una variable y configurar el mensaje de respuesta. Estas políticas (y otras) se agregan de forma automática cuando creas el proxy.

En la vista Desarrollar, en el panel Flujo, las flechas representan el flujo desde la solicitud hasta la respuesta, y los íconos representan las políticas.

WSDL alojado en Edge: A fin de ver el WSDL alojado en Edge generado para este tipo de proxy, ve a http(s)://[proxy_domain]/[proxy_base_path]?wsdl.

Desarrollo avanzado de proxy de SOAP a REST

En las secciones anteriores, se explicó la creación de un proxy de API de SOAP a REST mediante el asistente de proxy de API en Edge. Sin embargo, si quieres tener un control más detallado sobre la transformación de SOAP a REST, puedes omitir la automatización que proporciona el asistente y compilar un proxy si agregas y configuras políticas de forma manual para obtener el comportamiento que deseas. Para obtener más información, consulta Instructivo: Construcción manual de un proxy de API de SOAP a REST en Apigee Edge.