Ejemplo: escribir datos en Protocol Buffers
Este ejemplo muestra cómo escribir datos en archivos binarios cifrados en formato Protocol Buffers. En este ejemplo, los datos de origen provienen de una base de datos SQLite (Nanonull.sqlite); sin embargo, puede usar un método parecido para extraer datos de otros formatos compatibles con MapForce, como XML, EDI, JSON, entre otros.
La BD de origen de ejemplo almacena datos sobre personas, sus direcciones y productos que compraron en una tienda. El requisito empresarial es extraer información de los pedidos de la BD y generar varios archivos binarios en formato Protocol Buffers. Se debe generar un archivo binario con extensión .dat por cada pedido. El nombre del archivo generado debe contener el ID único del pedido, por ejemplo Order1.dat, Order2.dat, etc. Además, cada archivo binario debe incluir el ID del pedido, el nombre de la persona y su dirección de correo electrónico, la fecha del pedido y la dirección de entrega. Más concretamente, el archivo .proto que describe la estructura de un pedido tiene este aspecto:
syntax="proto3";
package mapforce.demo;
message Order { int32 id = 1; string name = 2; string email = 3; DateType entry_date = 4; // An order can have multiple addresses (shipping, billing) repeated AddressType address = 5; }
message DateType { // Must be from 1 to 9999 int32 year = 1; // Must be from 1 to 12 int32 month = 2; // Must be from 1 to 31, and valid for the year and month int32 day = 3; }
message AddressType { string city = 1; string street = 2; int32 number = 3; bool shipping = 5; bool billing = 4; } |
orders.proto
Tanto la BD Nanonull.sqlite como el archivo orders.proto se encuentran en el directorio <Documentos>\Altova\MapForce2023\MapForceExamples\Tutorial\. El archivo del diseño de la asignación que lleva a cabo la transformación se llama GenerateOrders.mfd y se encuentra en el mismo directorio. Puede abrir y ejecutar la asignación directamente o seguir los pasos que describimos a continuación para crearla desde cero.
GenerateOrders.mfd
Como ilustra la imagen anterior, la asignación consiste en un componente de origen (la BD SQLite) y uno de destino (el componente binario). En la BD de origen, la tabla más relevante para esta asignación es la de pedidos (orders).
Observe que la tabla users está anidada bajo la tabla orders porque MapForce detectó automáticamente una relación de clave foránea entre esas dos tablas. Asimismo, la tabla addresses está anidada bajo users. Todas las conexiones que se originen en ese tipo de tablas anidadas garantizan que la asignación conserve las relaciones de claves. Para más información, consulte el apartado Gestionar relaciones de BD.
En el lado de destino, el elemento Archivo<dynamic> ilustra cómo el componente binario está definido para que genere dinámicamente archivos de instancia basándose en la información que recibe de la asignación. Para que un componente de destino genere dinámicamente archivos, haga clic en el botón 
y seleccione Usar nombres de archivo dinámicos dados por la asignación del menú contextual. Para más información sobre nombres de archivo dinámicos consulte el apartado Procesar varios archivos de entrada o salida simultáneamente.
En esta asignación, por cada id de la tabla de BD orders se genera un archivo nuevo, como se muestra en la conexión al elemento File: <dynamic>. El nombre de cada uno de los archivos generados se crea con ayuda de la función concat. Esta función une la cadena "Order" con el ID único del pedido de la BD y con la extensión ".dat". Por tanto, los archivos generador obtendrán nombres como Order1.dat, Order2.dat, etc.
La función concat es llamada una segunda vez por la asignación. Esta vez devuelve el nombre de la persona. Para ello concatena el nombre y el apellido e inserta un espacio entre ambos.
Por último, el componente "GetDate" del medio es una función definida por el usuario que rellena los campos de fecha del archivo binario. Esta función toma como entrada una fecha expresada como una cadena, la analiza y devuelve el año, el mes y el día por separado como valores enteros. Esta conversión es necesaria para que se mantenga el formato de fecha definido por el archivo .proto. Si hace doble clic en la barra del título de la función en la asignación, puede ver o cambiar la definición de la misma.
Función definida por el usuario "GetDate"
Como ilustra la imagen anterior, la función definida por el usuario "GetDate" analiza el valor de entrada con ayuda de la función integrada parse-dateTime. La máscara [Y]-[M]-[D] [H]:[m]:[s] se corresponde con el formato de fecha de la BD, por ejemplo 2017-10-19 08:09:54. Para más información sobre máscaras de formato, consulte la descripción de la función parse-dateTime. A continuación se llama a varias funciones integradas para extraer y devolver las partes importantes de la fecha analizada.
Crear la asignación
Para crear la anterior asignación (o una similar) desde cero, siga estos pasos:
1.Inserte la BD de origen.
2.Inserte el archivo de destino .proto; véase Agregar archivos binarios a la asignación.
3.Configure el componente de destino para que se generen los nombres de los archivos de forma dinámica cuando se ejecute la asignación. Para ello, haga clic en el botón 
y seleccione Usar nombres de archivo dinámicos dados por la asignación en el menú contextual. A continuación, conecte el elemento Archivo<dynamic> con una entrada que proporcione el nombre del archivo. En este ejemplo, el nombre del archivo se obtiene con ayuda de la función concat, como explicábamos más arriba. Para más información sobre nombres de archivo dinámicos consulte el apartado Procesar varios archivos de entrada o salida simultáneamente.
4.También puede añadir cualquiera de las funciones integradas de MapForce y conectar sus entradas. En este ejemplo, la función concat se usa en dos ocasiones. Para más información consulte el apartado Agregar una función integrada a una asignación de datos. Observe que, cuando llama a funciones integradas, como concat, es posible que algunos de los datos de entrada provengan de constantes de cadena. Para más información sobre cómo añadir este tipo de constantes consulte el apartado Agregar una constante a una asignación de datos.
5.También puede añadir cualquier función definida por el usuario que necesite. De esta forma puede abstraerse de algunos detalles de la asignación y centrarse en la visión de conjunto. En este ejemplo, la función definida por el usuario "GetDate" convierte una cadena en partes de la fecha, como hemos explicado, y su lógica de implementación está oculta en la asignación principal. Para más información sobre la creación de funciones personalizadas consulte el apartado Funciones definidas por el usuario.
Si acaba de empezar a usar MapForce, consulte el capítulo Tutoriales, donde encontrará ejemplos simples explicados paso a paso.
Ejecutar la asignación
Como explicamos al principio de este apartado, se espera de la asignación que produzca varios archivos .dat. Para obtener una vista previa de los archivos generados, haga clic en la pestaña Resultados.
Como se aprecia en la asignación anterior, el panel Resultados muestra todos los archivos generados, por los que puede navegar haciendo clic en los botones bidireccionales o escogiendo un elemento de la lista desplegable. Puede guardar los resultados generados de dos formas:
•En el menú Resultados, haga clic en Guardar todos los archivos de salida ( 
).
•Haga clic en el botón de la barra de herramientas Guardar todos los resultados generados ( ).
En la vista previa de los archivos binarios generados con MapForce, su estructura se muestra en formato JSON, ya que este formato es de lectura humana directa, al contrario que los archivos binarios. Esta vista en JSON sirve para que pueda comprobar la asignación. Sin embargo, cuando guarde el archivo de salida, este se almacenará como archivo binario. |
Automatización con MapForce Server
Si cuenta con una licencia de MapForce Server puede ejecutar la asignación desde la línea de comandos, tanto en equipos Linux como macOS o Windows, como sigue:
1.Compile la asignación en un archivo de ejecución de MapForce Server (.mfx) con el comando de menú Archivo | Compilar en archivo de ejecución de MapForce Server (véase también el apartado Compilar asignaciones en archivos de ejecución de MapForce Server).
2.Copie el archivo .mfx en el equipo servidor.
3.Como esta asignación lee datos de un archivo de BD SQLite, copie el archivo de BD Nanonull.sqlite en el mismo directorio que contiene el archivo .mfx en el servidor. Para otros tipos de BD, consulte el apartado Bases de datos en MapForce.
4.Ejecute MapForce Server con el siguiente comando.
mapforceserver run GenerateOrders.mfx |
Notas:
•mapforceserver es la ruta de acceso al ejecutable de MapForce Server en función de su sistema operativo.
•Cambie la ruta de acceso al archivo .mfx o copie el archivo .mfx en la misma carpeta que el ejecutable.
En la ejecución del servidor puede ejecutar asignaciones como una llamada API o como trabajos de FlowForce, ya sea en el momento o de forma recurrente. Para más información consulte el apartado Automatización con MapForce Server.