Marshal

El EIP Marshal convierte el formato interno (objetos o estructuras) a un formato externo (como JSON o XML) para comunicación o almacenamiento. Por ejemplo, puede convertir un objeto Java en una representación JSON o XML.

Diferencia entre Marshal y Unmarshal

Marshal y Unmarshal son procesos fundamentales para la manipulación de datos, permitiendo la interoperabilidad entre sistemas.

  • Marshal: es el proceso de transformar datos del formato interno de Camel a un formato externo estandarizado, como JSON, XML, CSV, u otros. Esta conversión es esencial para integrar el flujo con sistemas externos, enviar mensajes a APIs o almacenar información en archivos de forma estructurada.

  • Unmarshal: se refiere al proceso inverso, donde los datos recibidos en un formato externo (por ejemplo, JSON, XML, CSV) se convierten al formato interno utilizado por Camel. Este paso es necesario para que los mensajes puedan ser procesados, manipulados o enrutados dentro del flujo de integración de Camel.

Custom

En la lista de tipos de formatos de datos disponibles en Data Format Type, hay la opción Custom.

Con ella, usted puede utilizar Excel como referencia, lo que permite que el flujo de integración procese archivos en los formatos .xls y .xlsx.

Este data format convertirá las filas de la hoja de cálculo especificada en un array de objetos JSON. El objeto JSON generado para cada celda contendrá, además del valor, metadatos sobre el tipo de dato.

Los estilos visuales de la hoja de cálculo (color de la celda, color de la fuente, la negrita, los bordes y otros) no se importan.

Para usar el componente, considere estas indicaciones:

  • El setHeader SensediaExcelFormat indica si el archivo es .xls o .xlsx.

    • Si el valor proporcionado es diferente, el componente generará un error.

    • Si el setHeader no se envía, se asumirá .xlsx por defecto.

  • El setHeader SensediaExcelSheetNames proporciona una lista de nombres de hojas de cálculo, separadas por comas.

    • Solo se procesarán las hojas listadas en el setHeader.

    • Si algún nombre proporcionado no existe en la hoje de cálculo, se ignorará.

  • Si el setHeader SensediaExcelSheetNames existe pero ninguno de los nombres coincide con una hoja de cálculo, el componente generará un error.

  • El uso de fórmulas está permitido. Sin embargo, si la fórmula es incorrecta, la celda en Excel indicará un error.

Formato JSON

Después de la conversión de un archivo Excel a JSON, los datos se organizan de la forma mostrada en el siguiente JSON Schema:

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Excel spreadsheet data schema",
  "description": "Schema for a data structure representing one or more spreadsheets with rows and cells.",
  "properties": {
    "sheets": {
      "description": "An array containing data for each sheet",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The name of the sheet.",
            "type": "string"
          },
          "rows": {
            "description": "The rows within a single sheet",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "cells": {
                  "description": "The rows within a single row",
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "v": {
                        "description": "The value of the cell. Can be a string, a number, or a boolean.",
                        "oneOf": [
                          { "type": "string" },
                          { "type": "number" },
                          { "type": "boolean" }
                        ]
                      },
                      "addr": {
                        "description": "The address of the cell (e.g., 'A1').",
                        "type": "string"
                      },
                      "type": {
                        "description": "The data type of the cell.",
                        "type": "string",
                        "enum": [
                          "str",
                          "num",
                          "bool",
                          "blank",
                          "formula"
                        ],
                        "default": "str"
                      },
                      "fmt": {
                        "description": "The formatting string for the cell's value.",
                        "type": "string",
                        "default": "General"
                      }
                    },
                    "required": [
                      "addr"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "cells"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "name",
          "rows"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "sheets"
  ],
  "additionalProperties": false
}

Comparación entre Excel y JSON

Ahora, compare una hoje de cálculo com su versión en formato JSON:

Excel

planilha excel borda

JSON

{
  "sheets": [
    {
      "name": "Sheet1",
      "rows": [
        {
          "cells": [
            {
              "v": "Produto",
              "addr": "A1"
            },
            {
              "v": "Preço Unitário",
              "addr": "B1"
            },
            {
              "v": "Data/hora",
              "addr": "C1"
            },
            {
              "v": "Ativo",
              "addr": "D1"
            },
            {
              "v": "Quantidade",
              "addr": "E1"
            },
            {
              "v": "Desconto (%)",
              "addr": "F1"
            },
            {
              "v": "Preço Total",
              "addr": "G1"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Caneta",
              "addr": "A2"
            },
            {
              "type": "num",
              "v": 2.5,
              "addr": "B2"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C2",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": true,
              "addr": "D2",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 10,
              "addr": "E2"
            },
            {
              "type": "num",
              "v": 0,
              "addr": "F2"
            },
            {
              "type": "num",
              "v": 25,
              "addr": "G2"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Caderno",
              "addr": "A3"
            },
            {
              "type": "num",
              "v": 15,
              "addr": "B3"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C3",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": true,
              "addr": "D3",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 5,
              "addr": "E3"
            },
            {
              "type": "num",
              "v": 10,
              "addr": "F3"
            },
            {
              "type": "num",
              "v": 67.5,
              "addr": "G3"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Lápis",
              "addr": "A4"
            },
            {
              "type": "num",
              "v": 1.5,
              "addr": "B4"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C4",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": true,
              "addr": "D4",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 20,
              "addr": "E4"
            },
            {
              "type": "num",
              "v": 5,
              "addr": "F4"
            },
            {
              "type": "num",
              "v": 28.5,
              "addr": "G4"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Borracha",
              "addr": "A5"
            },
            {
              "type": "num",
              "v": 3,
              "addr": "B5"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C5",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": true,
              "addr": "D5",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 8,
              "addr": "E5"
            },
            {
              "type": "num",
              "v": 0,
              "addr": "F5"
            },
            {
              "type": "num",
              "v": 24,
              "addr": "G5"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Régua",
              "addr": "A6"
            },
            {
              "type": "num",
              "v": 4.5,
              "addr": "B6"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C6",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": false,
              "addr": "D6",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 3,
              "addr": "E6"
            },
            {
              "type": "num",
              "v": 15,
              "addr": "F6"
            },
            {
              "type": "num",
              "v": 11.475,
              "addr": "G6"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Total Geral",
              "addr": "A7"
            },
            {
              "type": "num",
              "v": 156.475,
              "addr": "G7"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Média Preço Unitário",
              "addr": "A8"
            },
            {
              "type": "num",
              "v": 5.3,
              "addr": "G8"
            }
          ]
        }
      ]
    }
  ]
}

Ejemplo de código

Este flujo expone un endpoint REST que, al ser llamado, descarga un archivo Excel de un servidor SFTP, convierte su contenido a JSON y devuelve el resultado.

El procesamiento ocurre de la siguiente manera:

  1. Recibe la solicitud REST.

  2. Registra en el log el inicio de la descarga del archivo vía SFTP.

  3. Descarga el archivo desde el servidor SFTP.

  4. Registra en el log la finalización de la descarga y la conversión a JSON.

  5. Convierte el contenido a byte[].

  6. Define en el setHeader las hojas de cálculo que se procesarán. (test1,test2).

  7. Utiliza el marshal con el data format excel (custom) para transformar el archivo en JSON.

  8. Define el setHeader Content-Type como application/json para la respuesta.

- from:
    uri: rest:get:/teste-excel
    steps:
      - log:
          message: "Iniciando o download do arquivo via SFTP."
      - pollEnrich:
          expression:
            simple: "sftp:eu-central-1.sftpcloud.io:22/download?username={{user}}&password={{pass}}&passiveMode=true&delete=false&fileName={{file}}&binary=true&knownHostsFile=/dev/null&strictHostKeyChecking=no"
      - log:
          message: "Download concluído. Convertendo para JSON."
      - convertBodyTo:
          type: byte[]
      - setHeader:
          name: SensediaExcelSheetNames
          expression:
            constant:
              expression: test1,test2
      - marshal:
          custom:
            ref: excel
      - setHeader:
          name: Content-Type
          constant: application/json

Excel también puede ser utilizado en flujos con el EIP unmarshal para transformar archivos JSON en Excel.

  • En este caso, el campo addr del JSON de entrada no será considerado.

  • Las filas y columnas se construirán únicamente según el orden de las filas y celdas.

  • El resultado del unmarshal será un array de bytes.

Ejemplos

Vea ejemplos de otros formatos:

  • CSV

    • El mensaje se convertirá a csv.

    • No se requiere ningún parámetro adicional.

- marshal:
    csv: {}

  • JSON

    • El mensaje se convertirá a json.

    • Se utilizará la biblioteca Jackson para serializar el cuerpo del mensaje.

- marshal:
    json:
      library: Jackson

  • XML

    • El mensaje se convertirá a XML.

    • El jacksonXml utiliza la biblioteca Jackson, pero también existe el formato genérico xml.

- marshal:
    jacksonXml: {}
- marshal:
    xml: {}

Vea cómo agregar un data format directamente desde el formulario del EIP en la pestaña Diagram:

marshal json

Al seleccionar el formato JSON, el campo Library se completa automáticamente con el valor predeterminado "Jackson". Como es el valor predeterminado, no se muestra en el script del flujo en la pestaña Source, y solo aparece si se cambia a un valor diferente.
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]