Expón un servicio SOAP como un proxy de API

Estás viendo la documentación de Apigee Edge.
Ve a la documentación de Apigee X. info

En este tema, se explica cómo crear proxies de API para servicios web basados en SOAP. Puedes crear dos tipos de proxies SOAP en Edge. Uno genera una interfaz RESTful para el servicio de SOAP de backend y el otro realiza un "pase" del mensaje 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 SOAP en un servicio REST con Apigee Edge mediante el asistente de proxy de API. Sin embargo, si deseas tener más control sobre la transformación de SOAP a REST, puedes crear un proxy con políticas. Para obtener más información, consulta el instructivo: Cómo compilar manualmente 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 para crear 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 compatibles del servicio, los parámetros de entrada, etc. Edge “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 poder almacenarse en caché. Edge también configura el extremo de destino del backend, que puede variar según la operación SOAP.

Para este tipo de proxy, Edge genera automáticamente una especificación de OpenAPI, que puedes usar para crear documentación de la API.

Pasos básicos

Edge

Para crear un proxy de API RESTful para un servicio basado en SOAP con la IU de Edge, sigue estos pasos:

  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.

    • Desde la dirección web (URL): Ingresa o pega la URL del WSDL.
    • Desde mi computadora: Sube un archivo WSDL desde tu directorio local. Puedes subir varios archivos si hay dependencias.
  6. Haz 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 base para hacer coincidir los mensajes de solicitud entrantes y enrutarlos 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 configuras la ruta base con el mismo valor que la ruta base de otro proxy de API, Edge anulará automáticamente la implementación de este proxy cuando lo guardes. 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. Haz clic en 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 Agrega seguridad.
    • La compatibilidad con el uso compartido de recursos multiorigen (CORS) en Seguridad: Navegador. Consulta Agrega 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 figura.

  11. Selecciona un Tipo de puerto en el menú desplegable para especificar qué conjunto de operaciones deseas usar. En 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 la API de REST para una operación. La ruta se usará como el nombre del recurso en la URL del proxy de API.
  13. De forma opcional, cambia el Verbo (método HTTP) asociado con la operación.
  14. Haz clic en 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. Haz clic en Siguiente.
  17. Selecciona los entornos de implementación y haz clic en Crear e implementar.
    Se creará tu nuevo proxy de API y se implementará en el entorno seleccionado.
  18. Haz clic en Editar proxy para mostrar la página de detalles del proxy de API.

Edge clásico (nube privada)

Para crear un proxy de API RESTful para un servicio basado en SOAP con la IU clásica de Edge, 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 para compilar un proxy, selecciona el servicio de SOAP.
  5. Haz clic en Siguiente.
  6. En la página Detalles, haz 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.
    • Archivo: Elige un archivo WSDL en tu sistema de archivos. En los casos en que haya archivos adicionales dependientes, puedes seleccionarlos todos.
    • URL de ejemplo: Selecciona una de una lista de WSDL para los servicios web disponibles de forma pública. Son útiles para probar las funciones de proxy de SOAP o API de Edge.
    Proxy name

    Este es el nombre del proxy que estás creando.
    Ruta 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 base para hacer coincidir los mensajes de solicitud entrantes y enrutarlos 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 configuras la ruta base con el mismo valor que la ruta base de otro proxy de API, Edge anulará automáticamente la implementación de este proxy cuando lo guardes. 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 una breve descripción del proxy.
  7. Haz clic en 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 figura.

    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 adición.

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

    Nota: Edge hace una "mejor suposición" para determinar el método HTTP que se usará en cada operación. Por lo general, se prefiere GET porque las solicitudes GET se pueden almacenar en caché.
  11. De manera opcional, cambia la ruta de acceso de la API de REST para una operación. La ruta se usará 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 el entorno de despliegue.
  13. En la página Compilar, haz clic en Compilar e implementar. Edge genera e implementa el nuevo proxy de API según el WSDL.
  14. Ve a la página de resumen del nuevo proxy de API. Ten en cuenta que se creó un conjunto de recursos según 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 nueva API, sus operaciones y parámetros. Puedes pensar en esta representación como la documentación de referencia de la API. Edge genera esta vista del modelo de la API automáticamente. Solo tienes que expandir un recurso para ver su descripción y la información de la ruta.

Información 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. Después de generar un proxy basado en un WSDL, observa el flujo resultante en la vista Desarrollar 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 de AssignMessage 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 SOAP de la respuesta en una variable y establecer el mensaje de respuesta. Estas políticas (y otras) se agregan automáticamente cuando creas el proxy.

Especificación de OpenAPI: Para ver la especificación de OpenAPI generada automáticamente 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 transferencia a un servicio basado en SOAP

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

Descripción general

La opción de proxy de transferencia te permite crear un proxy que pase el mensaje SOAP en una solicitud al servicio de backend "sin modificaciones", lo que facilita mucho la creación de un proxy para un servicio web basado en SOAP. En segundo plano, Edge controla automáticamente las transformaciones y otras actividades del flujo. Por ejemplo, si la solicitud está en formato JSON, Edge toma medidas para convertirla en un mensaje SOAP XML válido con los espacios de nombres correctos antes de enviarla por POST al servicio. Del mismo modo, cuando el servicio muestra una respuesta SOAP basada en XML, Edge la vuelve a traducir a JSON antes de devolverla al cliente. Además, Edge configura el extremo de destino del backend, que puede variar según la operación SOAP.

En el caso de este tipo de proxy, Edge aloja el WSDL y crea un flujo en el proxy para permitirte acceder a él. La dirección de este WSDL alojado en Edge, 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

Edge

Para crear un proxy de transferencia a un servicio basado en SOAP con la IU de Edge, sigue estos pasos:

  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 del WSDL.
    Campo Descripción
    WSDL

    Selecciona la fuente del WSDL.

    • Desde la dirección web (URL): Ingresa o pega la URL del WSDL.
    • Desde mi computadora: Sube un archivo WSDL desde tu directorio local. Puedes subir varios archivos si hay dependencias.
    Nombre

    Nombre del proxy de API.
    Ruta base

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

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

    Después de la ruta base, se encuentran las URLs 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. Si más adelante editas este proxy y configuras su ruta base para que sea la misma que la de otro proxy de API, este proxy de API se anulará automáticamente cuando lo guardes. Debes editar la ruta base para poder 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 tus proxies 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 /**/.

    Nota: La ruta base del proxy de API se configura de forma predeterminada como el valor especificado para el campo Nombre convertido en minúsculas, a menos que edites de forma explícita el contenido del campo Ruta base.
    Descripción Es la descripción de la API (opcional).
  6. Haz clic en 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 en el menú desplegable para especificar qué conjunto de operaciones deseas usar. En WSDL, los elementos de tipo de puerto definen las operaciones a las que puedes llamar en un servicio web.
  10. Haz clic en 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 Información acerca de los hosts virtuales.
  12. Selecciona los entornos de implementación y haz clic en Crear e implementar.
    Tu proxy de API nuevo se crea y se implementa en el entorno seleccionado.
  13. Haz clic en Editar proxy para mostrar la página de detalles del proxy de API.

Edge clásico (nube privada)

Para crear un proxy de transferencia a un servicio basado en SOAP con 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 para compilar un proxy, selecciona el servicio de SOAP.
  5. Haz clic en Siguiente.
  6. En la página Detalles, haz 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.
    • Archivo: Elige un archivo WSDL en tu sistema de archivos. En los casos en los que haya archivos adicionales dependientes, puedes seleccionarlos todos.
    • URL de ejemplo: Selecciona una de una lista de WSDL para servicios web disponibles de forma pública. Son útiles para probar las funciones de proxy de SOAP o API de Edge.
    Proxy name

    Este es el nombre del proxy que estás creando.
    Ruta base del proxy La ruta de acceso 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 la ruta base para hacer coincidir los mensajes de solicitud entrantes y enrutarlos al proxy de API adecuado. (La ruta base se agrega 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: La ruta base del proxy se configura de forma predeterminada como el valor especificado para el nombre del proxy, convertido en minúsculas, a menos que edites explícitamente el contenido del campo Ruta base del proxy.
    Descripción Es una breve descripción del proxy.

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

    Nota: Aparece una tabla con cada operación de WSDL y su carga útil de SOAP correspondiente. Esta es la carga útil que se “pasa” al servicio SOAP del 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, se organiza por tipo de puerto.
  10. En la columna Tipo de puerto, selecciona el conjunto de operaciones que deseas usar. En 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 el entorno de despliegue.
  12. En la página Compilar, haz clic en Compilar e implementar. Edge genera e implementa el nuevo proxy de API según el WSDL.

Información acerca del proxy final

Cuando Edge genera un proxy de transferencia, 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 Develop 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 PreFlow del extremo de destino de un proxy de transferencia. En el lado de la solicitud, se usa una política de AssignMessage 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 SOAP de la respuesta en una variable y establecer el mensaje de respuesta. Estas políticas (y otras) se agregan automáticamente cuando creas el proxy.

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

WSDL alojado en Edge: Para ver el WSDL alojado en Edge que se genera 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 analizó la creación de un proxy de API de SOAP a REST con el asistente de proxy de API en Edge. Sin embargo, si deseas tener un control más detallado sobre la transformación de SOAP a REST, puedes omitir la automatización que proporciona el asistente y crear un proxy agregando y configurando manualmente políticas para obtener el comportamiento que deseas. Para obtener más información, consulta el Tutorial: Construcción manual de un proxy de API de SOAP a REST en Apigee Edge.