Modernice su servidor legado SOAP con Amazon API Gateway y AWS Lambda – Parte 3

Vamos a crear la solución utilizando AWS SAM

Como se detalla en la Parte 2 de la serie de publicaciones del blog, para esta implementación, existen los siguientes requisitos previos:

• NodeJS 14.x o superior (usaremos NodeJS 16.x en este ejemplo)
• NPM (administrador de paquetes NodeJS) versión 6x o posterior
• AWS SAM versión 1.53.0 o posterior
• Docker (es opcional, obligatorio solo si quieres probar tu API localmente)
• curl — curl es una herramienta de línea de comandos de código abierto para transferir datos y realizar solicitudes web utilizando varios protocolos de red. La usaremos para probar nuestra API tanto a nivel local como en AWS. Si no está familiarizado con curl, puede usar Postman, Insomnia, HttPie, SoapUI u otro software similar.

Seguiremos utilizando AWS Cloud 9 como IDE y, si no sabe cómo crear este entorno de desarrollo virtual, usted encontrará una explicación aquí en este enlace.

Comencemos a crear el paso 1 realizando las siguientes actividades:

1. Abra el servicio Cloud9 en la consola de administración de AWS (consola de AWS)
2. En la terminal o usando los menús, cree una carpeta para el proyecto llamada NumberToWordsMicroservice incluyendo una subcarpeta llamada ./src. El subdirectorio ./src contendrá el código Lambda necesario para esta solución.

mkdir numberToWordsMicroservice && cd numberToWordsMicroservice && mkdir src

3. Cree los siguientes archivos en blanco:

   • ./template.yaml

   • ./src/app.js

   • ./src/package.json

touch template.yaml ./src/app.js ./src/package.json

4. 4. 4. 4. Abra el archivo plantilla.yaml y copie el siguiente contenido en el archivo:
         

<pre><code class="lang-yaml"># © 2022 Amazon Web Services, Inc. or its affiliates. All Rights Reserved.

# This AWS Content is provided subject to the terms of the AWS Customer Agreement
# available at http://aws.amazon.com/agreement or other written agreement between
# Customer and Amazon Web Services, Inc.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Microservice -&gt; NumberToWords

Globals:
  Function:
    Timeout: 3

Resources:
  NumberToWordsMicroServiceFunction:
    Type: AWS::Serverless::Function 
    Properties:
      CodeUri: src/
      Handler: app.handler
      Runtime: nodejs14.x
      Events:
        NumberToWords:
          Type: Api 
          Properties:
            Path: /
            Method: post

Outputs:
  NumberToWords:
    Description: "Test API Gateway endpoint URL for Prod stage for NumberToWords"
    Value: !Sub "curl -i -X POST https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/ -d '{\"data\": \"12\"}'"</code></pre>

En esta plantilla SAM de AWS, estamos definiendo una función de Lambda denominada numberToWordsFunction (descrita en la línea 16) y una puerta de enlace (Gateway) de API REST que expone el método /post (líneas 23-27). El código fuente de la función Lambda se definirá en la carpeta /src (línea 19), en un archivo llamado app.js (línea 20), que contendrá la función llamada «handler». En las líneas 30 a 33 definimos los resultados de nuestra solución.

Recuerde salvar el archivo.

5. El siguiente paso es copiar el código fuente de nuestra función Lambda. Abra el archivo app.js en la carpeta ./src y copia el siguiente código:

// © 2022 Amazon Web Services, Inc. or its affiliates. All Rights Reserved.

// This AWS Content is provided subject to the terms of the AWS Customer Agreement
// available at http://aws.amazon.com/agreement or other written agreement between
// Customer and Amazon Web Services, Inc.

var writtenNumberinWords = require('written-number');

exports.handler = async (event, context) => {
    let response;    
    
    const body = JSON.parse(event.body);
    const valueToConvert = body.data;
    
    try {
        let returnWords = writtenNumberinWords(valueToConvert);
        response = {'statusCode': 200, 'body': JSON.stringify({"message": returnWords})};
                    
    } catch (err) {
        return err;
    }
    
    return response;
};

No olvidar aquí, también salvar el archivo.

Esta función de Lambda implementa un microservicio muy simple, recibir una cadena que representa un entero en formato JSON en el campo «body.data» (línea 12).  Esta función descompone este valor convirtiéndolo a un formato numérico y utiliza una biblioteca llamada WrittenNumberInWords (línea 7) para convertir el valor entero a su descripción en texto completo (en idioma inglés), similar al servicio del servidor SOAP descrito en la parte 2 de esta publicación del blog.

En pocas palabras, lo que hace este código es que si envías un entero como «548» en formato JSON, te devolverá una cadena (string) que contendrá el número descrito en idioma inglés «five hundred and forty-eigh».

6. Como estamos usando una biblioteca externa en el código Lambda, debemos actualizar el archivo package.json y ejecutar el comando «npm install» posteriormente. Ábra la carpeta ./src y el archivo package.json y copie el siguiente contenido:

{
  "name": "numberToWords",
  "version": "1.0.0",
  "description": "Microservice to convert a integer into ",
  "main": "app.js",
  "author": "Daniel Abib",
  "license": "MIT",
  "dependencies": {
    "written-number": "^0.11.1"
  }
}

7. En la terminal de Cloud9, cambiese el directorio ./src y ejecute el siguiente comando para instalar las bibliotecas externas:

cd src && npm install

Observará que hay 1 dependencia y que la carpeta node_modules se creó bajo el directorio ./src para incluir dicha biblioteca.

8. Antes de probar la aplicación, necesitamos compilar los artefactos necesarios para ejecutar el proyecto con el comando «sam build» en el directorio raíz.

cd .. && sam build

El comando «sam build» procesa el archivo de plantilla SAM de AWS, así como el código fuente de la aplicación y cualquier archivo y dependencia específicos del idioma. El comando crea y copia artefactos en el formato y la ubicación esperados (directorio.aws-sam) para los pasos posteriores del flujo de trabajo.

Usted puede especificar las dependencias en un archivo de manifiesto que incluya en su aplicación, como requirements.txt para las funciones de Python o package.json para las funciones de NodeJS.

El resultado del comando «sam build» debe ser similar al de la siguiente imagen:

9. Ahora es el momento de ejecutar nuestra aplicación de forma local para probarla. AWS SAM le permite ejecutar su aplicación sin servidor (serverless) de forma local para realizar el desarrollo y las pruebas de manera rápida. Cuando usted ejecuta el siguiente comando en un directorio que contiene sus funciones y su archivo de plantilla de SAM de AWS, se creará un servidor HTTP local (usando Docker) que alojará todas sus funciones.

Puede usar el comando «sam local start-api» para emular la ejecución de un Amazon API Gateway y recibir la solicitud localmente, sin embargo,  es obligatorio que Docker se ejecute en su entorno local.

sam local start-api

**IMPORTANTE** Si usted no tiene Docker ejecutándose localmente en su máquina, omita este paso e implemente la aplicación como se define en la continuación de este blog. En Cloud9, Docker se ejecuta de forma predeterminada.

Puede abrir otra terminal (haga clic en el botón + a la derecha de la «pestaña Immediate» y elija New Terminal) para mostrar la ejecución de la llamada a la API REST (método de solicitud POST mediante curl) y mantener abierta la primera terminal para mostrar cómo docker crea el contenedor para ejecutar Amazon API Gateway y la función de AWS Lambda.

10. Puedes probar tu API local con el siguiente comando curl (post):

curl -i -X POST localhost:3000/ -H "Content-Type: application/json" -d '{"data": "548"}'

La salida debe ser similar a la siguiente imagen:

Lo que hemos creado hasta ahora es solo un microservicio que convierte un número  entero en su descripción de texto larga, utilizando Amazon API Gateway como puerta de acceso a la solicitud HTTP/REST y AWS Lambda para realizar la lógica de conversión simple.

Vamos a publicar este microservicio en AWS, ya que necesitaremos que esta solución funcione para que sea posible implementar el proxy de conversión de protocolos (SOAP a REST).

1. Ejecute los siguientes pasos:

• Presione Control+C en el terminal que ejecuta el comando «sam local start-api», use un segundo terminal o abra una nueva para ejecutar el comando «sam deploy -g»

sam deploy -g

• Llene los siguientes valores cuando se le solicite:

Este comando (sam deploy -g) implementa la aplicación en la nube de AWS. Toma los artefactos que se crearon, los empaqueta y los carga en un depósito de Amazon Simple Storage Service (Amazon S3) que el servicio de AWS CloudFormation utilizará para crear la aplicación.

Al final de la ejecución de sam deploy, usted verá un mensaje similar al de la siguiente imagen:

12. Puede usar el siguiente comando para probar su solución directamente en la nube de AWS:

curl -i -X POST https://6f3wn533n0.execute-api.us-east-1.amazonaws.com/Prod/ -d '{"data": "1122"}'

(OBS1: Usted puede reemplazar la URL por la que generó en su implementación)

(OBS2: Usted puede copiar el comando anterior en la sesión de salida «sam deploy»)

Listo, la primera parte de nuestra solución se ha finalizado. Ya tenemos el microservicio que se utilizará para el proceso de conversión de los protocolos SOAP a REST, lo que le permitirá seguir utilizando su cliente SOAP legado en soluciones que exponen sus interfaces en REST.

Paso 2

Ahora que tenemos un microservicio REST que opera en la nube de AWS, comencemos la segunda parte de la solución, llevando a cabo las siguientes actividades para crear la arquitectura que se destaca en la siguiente figura:

13. En la terminal o mediante los menús, cree una carpeta para el proyecto llamada ProxySoapClient con una subcarpeta llamada ./src. El subdirectorio ./src contendrá el código Lambda necesario para esta solución.

mkdir proxySoapClient && cd proxySoapClient && mkdir src

14. Cree los siguientes archivos en blanco:

    • ./template.yaml

    • ./src/app.js

    • ./src/package.json

touch template.yaml ./src/app.js ./src/package.json

15. 15. 15. 15. Abra el archivo plantilla.yaml y copie el siguiente contenido en el archivo:
           

# © 2022 Amazon Web Services, Inc. or its affiliates. All Rights Reserved.

# This AWS Content is provided subject to the terms of the AWS Customer Agreement
# available at http://aws.amazon.com/agreement or other written agreement between
# Customer and Amazon Web Services, Inc.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: ProxySoapClient

Globals:
  Function:
    Timeout: 3
    Environment:
      Variables:
        NumberToWordMicroservice: !Ref URLForNumberToWordMicroservice
        
Parameters:
  URLForNumberToWordMicroservice:
    Type: String

Resources:
  ProxySoapClientWordsFunction:
    Type: AWS::Serverless::Function 
    Properties:
      CodeUri: src/
      Handler: app.handler
      Runtime: nodejs16.x
      Events:
        NumberToWords:
          Type: Api 
          Properties:
            Path: /
            Method: post
          Response:
            headers:
              Content-Type: "'text/xml'"

Outputs:

  LegacyIntegrationNumberToWords:
    Description: "To test the API Gateway endpoint URL for Prod stage for LegacyIntegrationNumberToWords"
    Value: !Sub "curl -i -X POST -H \"Content-Type: text/xml\" https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/ --data @clientSoapEnvelope.xml"

La estructura de esta plantilla SAM de AWS es muy similar a las demás presentes en la parte 2 de esta serie de publicaciones de blog y también a la plantilla presentada en el paso 1. La principal diferencia es la necesidad de declarar cuál es la URL del servicio que haremos el proxy.

Este archivo le pide que llene ésta URL en el parámetro URLForNumberToWordMicroservice, definido en la línea 19. En la sección de parámetros, los objetos declarados obligan al usuario a realizar una solicitud de entrada de parámetros durante la ejecución del comando «deploy -g». Para ver los parámetros de ejemplo y las solicitudes correspondientes, consulte la documentación de referencia de comandos de CLI.

Más adelante completaremos este parámetro con la URL del microservicio NumberToWords que se creó en el punto 12 del paso 1 de este blog.

El resto del archivo de plantilla SAM de AWS no debería ser muy diferente de lo que ya se ha visto en esta secuencia de publicaciones.

Recuerde salvar el archivo.

16. El siguiente paso es copiar el código fuente de nuestra función Lambda. Abra el archivo app.js en la carpeta ./src y copia el siguiente código:

//  © 2022 Amazon Web Services, Inc. or its affiliates. All Rights Reserved.

//  This AWS Content is provided subject to the terms of the AWS Customer Agreement
//  available at http://aws.amazon.com/agreement or other written agreement between
//  Customer and Amazon Web Services, Inc.

var parseString = require('xml2js').parseString;
const axios = require('axios');

exports.handler = async (event, context) => {
    // let response; 
    var valueNumber;
    
    try {
        
        parseString(event.body, function (err, result) {
            if (!err) {
                valueNumber = result['soap:Envelope']['soap:Body'][0]['ConvertNumberToWordsSoapIn'][0]['NumberToWordsRequest'][0];
            } else { 
                console.log (err);
                throw (err);
            }
        });

        var jsonObject = {
            "data" : valueNumber
        };
        
        const headers = { 
            'Content-Type': 'Application/json'
        };
        
        var resultNumberToWords = await axios.post(process.env.NumberToWordMicroservice, jsonObject, { headers });
        
        var resp =  create_response (JSON.stringify(resultNumberToWords.data.message));

        let response = {'statusCode': 200, 
                        headers: {"content-type": "text/xml"}, 
                        'body': JSON.stringify(resp)
        };
        
        return response;
        
    } catch (err) {
        console.log ("Error: " + err);
        let response = {'statusCode': 500, headers: {"content-type": "text/xml"}, 'body': err};
        return response;
    }
};

function create_response(numberInWords) {
  return '<?xml version="1.0" encoding="utf-8"?> \
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">\
            <soap:Body>\
              <m:ConvertNumberToWordsResponse xmlns:m="http://www.dataaccess.com/webservicesserver/"> \
                  <m:ConvertNumberToWordsResponseResult>' + numberInWords + '</m:ConvertNumberToWordsResponseResult> \
              </m:ConvertNumberToWordsResponse> \
            </soap:Body>\
            </soap:Envelope>';
}

Recuerde salvar también el archivo.

De forma análoga a la implementada en la parte 2 de este blog, esta función de Lambda tiene 4 acciones principales.

La primera es recibir de la aplicación cliente la carga útil en formato XML (obligatorio para el protocolo SOAP) y convertirla al formato JSON (representado en las líneas 16 a 27).

La segunda parte consiste en convertir el encabezado Content-Type de «Text/XML» (también obligatorio en el protocolo SOAP) a «Application/JSON» (líneas 29 a 31).

La tercera parte es la llamada del microservicio NumberToWords a través de una llamada HTTP que pasa la carga que ya está en formato JSON y el encabezado Content-Type ya convertido (línea 33).

La última parte es el ensamblaje del XML de devolución, esperado por el protocolo SOAP, que contiene los datos convertidos de la aplicación REST NumberToWords (línea 35). Para este paso, se creó una función auxiliar para crear la estructura XML esperada por el cliente SOAP.

17. Como estamos usando bibliotecas externas en el código Lambda, debemos actualizar el archivo package.json y ejecutar el comando «npm install» más adelante. Ábra la carpeta ./src y el archivo package.json y copie el siguiente contenido:

{
  "name": "ProxySoapClient",
  "version": "1.0.0",
  "description": "Applicatio to proxy a SOAP client request into REST",
  "main": "app.js",
  "author": "Daniel Abib",
  "license": "MIT",
  "dependencies": {
    "axios": "^0.21.4",
    "xml2js": "^0.4.23"
  }
}

18. En la terminal de Cloud9, cambie el directorio a ./src y ejecute el siguiente comando para instalar las bibliotecas externas:

cd src && npm install && cd ..

Observará que hay 2 dependencias y que la carpeta node_modules se creó en ./src para incluir estas bibliotecas.

19. Antes de probar la aplicación, necesitamos compilar los artefactos usando el comando «sam build» en el directorio raíz del proyecto.

cd .. && sam build

El comando «sam build» procesa el archivo de plantilla SAM de AWS, así como el código fuente de la aplicación, los archivos y dependencias específicos del idioma elegido. El comando crea y copia artefactos en el formato y la ubicación esperados (directorio .aws-sam) para los pasos posteriores del flujo de trabajo.

Usted puede especificar dependencias en un archivo de manifiesto que incluya en su aplicación, como requirements.txt para las funciones de Python o package.json para las funciones de NodeJS.

El resultado del comando «sam build» debe ser similar al de la siguiente imagen:

20. Ahora es el momento de ejecutar nuestra aplicación de forma local para probarla. AWS SAM le permite ejecutar su aplicación sin servidor (serverless) de forma local para un desarrollo y pruebas rápidos. Cuando ejecuta el siguiente comando en un directorio que contiene las funciones y la plantilla de AWS SAM, se crea un servidor HTTP local (mediante Docker) que aloja todas sus funciones.

Dado que el cliente SOAP necesita un XML que contenga los datos de la solicitud en formato SOAPEnvelope para el servidor, crearemos un archivo local con la estructura de carga útil que se enviará a nuestro proxy. Para ello, cree un archivo y copie el siguiente contenido en él.

touch clientSoapEnvelope.xml

Puede usar el comando «sam local start-api» para emular la ejecución de un Amazon API Gateway y recibir la solicitud localmente, pero es obligatorio que Docker se ejecute en su entorno local.

A diferencia de lo que ya se ha presentado en este blog, dado que nuestra aplicación necesita conocer la URL del microservicio NumberToWords que simula nuestro servidor REST, necesitaremos pasar un parámetro adicional en el comando sam local start-api.

sam local start-api --parameter-overrides URLForNumberToWordMicroservice=https://6f3wn533n0.execute-api.us-east-1.amazonaws.com/Prod/

Recuerde reemplazar la URL del punto final (endpoint) del microservicio NumberToWords por la que se generó en el paso 12 de esta publicación de blog.

**IMPORTANTE** Si no tiene Docker ejecutándose localmente en su máquina, omita este paso e implemente la aplicación como se define en la continuación de este blog. En Cloud9, Docker se ejecuta de forma predeterminada.

Puede abrir otra terminal (haga clic en el botón + a la derecha de la «pestaña Immediate» y elija New terminal) para mostrar la ejecución de la llamada a la API REST (método de solicitud POST mediante curl) y mantener abierta la primera terminal para mostrar cómo docker crea el contenedor para ejecutar Amazon API Gateway y la función Lambda.

21. Usted puede probar su API local con el siguiente comando curl (post):

(NOTA: Recuerde cambiar al directorio que contiene el archivo clientSoapEnvelope.xml ejecutando el comando cd ProxySoapClient)

curl -i -X POST -H 'Content-type: text/xml'  -d @clientSoapEnvelope.xml http://localhost:3000

La salida debe ser similar a la siguiente imagen:

El resultado de la llamada del cliente (curl) es un XML que contiene la respuesta SOAP, con una etiqueta que contiene el resultado «one thousand five hundred and nineteen», un valor que se pasó en el archivo de solicitud en formato numérico.

Para finalizar nuestra solución, publicaremos esta solución (SOAP Proxy for REST) en AWS y, por lo tanto, completaremos los 2 pasos para crear un microservicio REST llamado NumberToWords y una solución SOAP Proxy for REST que permita que una aplicación envíe una solicitud con una carga XML y un encabezado. Tipo de contenido «Texto/XML» y será respondido por un servidor REST después de todas las conversiones de formato.

22. Lleve a cabo los siguientes pasos:

• • Presiona Control+C en el terminal que ejecuta el comando «sam local start-api», usa un segundo terminal o abre uno nuevo para ejecutar el comando «sam deploy -g»

sam deploy -g

• Llene los siguientes valores cuando se le solicite:

Vale la pena mencionar, como se mencionó en el paso 20, que se espera un parámetro adicional en el proceso de implementación (deploy). Tenemos que indicar a AWS SAM la URL del microservicio NumberToWord para que se pueda usar en el código Lambda y llamar a este servicio de forma adecuada. La flecha roja de la figura anterior representa este valor y debe sustituirse por la que se generó en el paso 12 de esta publicación de blog.

Este comando (sam deploy -g) implementa la aplicación en la nube de AWS. Toma los artefactos que se crearon, los empaqueta y los carga en un depósito de Amazon Simple Storage Service (Amazon S3) que AWS CloudFormation utilizará para crear la aplicación.

23. Puede usar el siguiente comando para probar la solución:

curl -i -X POST -H "Content-Type: text/xml"  https://zes5gb8xxl.execute-api.us-east-1.amazonaws.com/Prod/ --data  @clientSoapEnvelope.xml

(OBS1: Usted debe reemplazar la URL por la que generó en su implementación)

(OBS2: Usted puede copiar el comando anterior en la sesión de salida «sam deploy»)

Aunque tuvimos que hacer varios pasos, la complejidad del proceso de conversión de protocolos se vio facilitada por el uso de Amazon API Gateway y también por la facilidad de creación de la función lambda.

Es posible que usted haya notado que en ningún momento necesitamos crear, configurar o administrar servidores, porque todos los servicios presentados aquí son sin servidor (serverless).

Limpiar la carga de trabajo generada

Al usar el servicio sin servidor de AWS (AWS Serverless), los clientes pagan solo por lo que usan. Si no hay ninguna solicitud de AWS Lambda o Amazon API Gateway, no se le cobrará.

Ambos servicios utilizados aquí tienen una capa gratuita como se explica a continuación:

Sin embargo, si quiere limpiar su cuenta de AWS, simplemente ejecute el comando delete de SAM de AWS:

sam delete

Debe confirmar la eliminación de la aplicación, así como los artefactos almacenados en S3. Este sería el resultado:

Si tiene otros casos de uso para modernizar arquitecturas SOAP legadasdas y quiere compartirlo conmigo, póngase en contacto conmigo en LinkedIn e intentaré ayudarlo. https://www.linkedin.com/in/danielabib/

Acerca del autor

Daniel Abib es arquitecto de soluciones empresariales en AWS, con más de 25 años trabajando en gestión de proyectos, arquitecturas de soluciones escalables, desarrollo de sistemas y CI/CD, microservicios, Serverless y seguridad.  Trabaja apoyando a los clientes corporativos, ayudándolos en su viaje a la nube.