Creación de asignaciones para transformar datos en Azure Logic Apps con Visual Studio Code

Artículo
11/22/2023

Se aplica a: Azure Logic Apps (estándar)

Para intercambiar mensajes que tienen formatos XML o JSON diferentes en un flujo de trabajo de Azure Logic Apps, debe transformar los datos de un formato a otro, especialmente si tiene lagunas entre las estructuras de esquema de origen y de destino. La transformación de datos le ayuda a salvar esas brechas. Para esta tarea, debe crear una asignación que defina la transformación entre los elementos de datos en los esquemas de origen y de destino.

Para crear y editar visualmente un mapa, puede usar Visual Studio Code con la extensión Azure Logic Apps (Estándar) en el contexto de un proyecto de aplicación lógica Estándar. La herramienta Asignador de datos proporciona una experiencia unificada para la asignación y transformación de XSLT mediante gestos de arrastrar y colocar, una biblioteca de funciones precompilada para crear expresiones y una manera de probar manualmente las asignaciones que se crean y usan en los flujos de trabajo.

Después de crear la asignación, puede llamar directamente a esa asignación desde un flujo de trabajo en el proyecto de aplicación lógica o desde un flujo de trabajo en Azure Portal. Para esta tarea, es posible usar la acción Operaciones del asignador de datos denominada Transformación mediante XSLT del asignador de datos en el flujo de trabajo.

En esta guía paso a paso se muestra cómo crear un mapa de datos en blanco, elegir los esquemas de origen y destino, seleccionar elementos de esquema para iniciar la asignación, crear varias asignaciones, guardar y probar el mapa y, a continuación, llamar al mapa desde un flujo de trabajo en el proyecto de aplicación lógica.

Limitaciones y problemas conocidos

Asignador de datos actualmente solo funciona en Visual Studio Code con sistemas operativos Windows.
Asignador de datos solo está disponible actualmente en Visual Studio Code, no en Azure Portal, y solo desde proyectos de aplicación lógica Estándar, no en proyectos de aplicación lógica de Consumo.
Asignador de datos no admite actualmente archivos de valores separados por comas (.csv).
El panel vista Código del Asignador de datos es actualmente de solo lectura.
El diseño de la asignación y la posición del elemento son actualmente automáticos y de solo lectura.
Para llamar a asignaciones creadas con la herramienta Asignador de datos, solo puede usar la acción Operaciones del asignador de datos denominada Transformación mediante XSLT del asignador de datos. Para las asignaciones creadas por cualquier otra herramienta, use la acción Operaciones XML denominada Transformar XML.
Para usar los mapas que cree con la herramienta Asignador de datos, pero en Azure Portal, debe agregarlos directamente al recurso de aplicación lógica Estándar.

Requisitos previos

Visual Studio Code y la extensión de Azure Logic Apps (Estándar) para crear flujos de trabajo de aplicaciones lógicas Estándar.

Nota:

Ahora, la extensión Asignador de datos anteriormente independiente se combina con la extensión Azure Logic Apps (Estándar). Para evitar conflictos, se quita cualquier versión existente de la extensión Asignador de datos al instalar o actualizar la extensión Azure Logic Apps (Estándar). Después de instalar o actualizar la extensión, reinicie Visual Studio Code.
Los archivos de esquema de origen y destino que describen los tipos de datos que se van a transformar. Estos archivos pueden tener los siguientes formatos:
- Un archivo de definición de esquema XML con la extensión de archivo .xsd
- Un archivo de notación de objetos JavaScript con la extensión de archivo .json
Un proyecto de aplicación lógica estándar que incluye un flujo de trabajo con estado o sin estado con al menos un desencadenador. Si no tiene un proyecto, siga estos pasos en Visual Studio Code:
1. Conéctese a la cuenta de Azure, si todavía no lo ha hecho.
2. Cree una carpeta local, un proyecto de aplicación lógica estándar local y un flujo de trabajo con estado o sin estado. Durante la creación del flujo de trabajo, seleccione Abrir en la ventana actual.
Datos de entrada de ejemplo si desea probar el mapa y comprobar que la transformación funciona según lo previsto.
Para usar la función Run XSLT, los fragmentos de código XSLT deben existir en archivos que usen la extensión de nombre de archivo .xml o .xslt. Debe colocar los fragmentos de código XSLT en la carpeta InlineXslt en la estructura de carpetas del proyecto local: Artifacts>DataMapper>Extensions>InlineXslt. Si esta estructura de carpetas no existe, cree las carpetas que faltan.

Creación de una asignación de datos

En el menú izquierdo de Visual Studio Code, seleccione el icono de Azure.
En el panel Azure, en la sección Asignador de datos, seleccione Crear nuevo mapa de datos.
Proporcione un nombre para el mapa de datos.
Para especificar los esquemas de origen y destino, siga estos pasos:
1. En la superficie del mapa, seleccione Agregar un esquema de origen.
2. En el panel Configurar que se abre, seleccione Agregar nuevo>Examinar.
3. Busque y seleccione el archivo de esquema de origen y, a continuación, seleccione Agregar.
  
  Si el esquema de origen no aparece en la ventana Abrir, en la lista de tipos de archivo, cambie archivo XSD (*.xsd) a Todos los archivos (*.*).
  
  La superficie de asignación ahora muestra los tipos de datos del esquema de origen. Para ver los ejemplos de esta guía,
4. En la superficie del mapa, seleccione Agregar un esquema de destino.
5. En el panel Configurar que se abre, seleccione Agregar nuevo>Examinar.
6. Busque y seleccione el archivo de esquema de destino y, a continuación, seleccione Agregar.
  
  Si el esquema de destino no aparece en la ventana Abrir, en la lista de tipos de archivo, cambie archivo XSD (*.xsd) a Todos los archivos (*.*).
  
  La superficie de asignación ahora muestra los tipos de datos del esquema de destino.
Como alternativa, también puede agregar los archivos de esquema de origen y de destino localmente al proyecto de aplicación lógica en la carpeta Artifacts/Esquemas, para que aparezcan en Visual Studio Code. En este caso, puede especificar el esquema de origen y destino en la herramienta Asignador de datos en el panel Configurar seleccionando Seleccionar existente, en lugar de Agregar nuevo.

Cuando haya terminado, la asignación tendrá un aspecto parecido al siguiente ejemplo:

En la tabla siguiente se describen los posibles tipos de datos que pueden aparecer en un esquema:

Símbolo	Tipo	Más información
	Matriz	Contiene elementos o nodos de elementos repetidos
	Binario
	Booleano	Solo true o false
	Complex	Objeto XML con propiedades secundarias, similar al tipo de objeto JSON
	DateTime
	Decimal
	Entero	Solo números enteros
	Null	No es un tipo de datos, pero aparece cuando existe un error o un tipo no válido
	Número	Un entero o decimal JSON
	Object	Objeto JSON con propiedades secundarias, similar al tipo XML Complex
	String

Navegue por la asignación

Para moverse por la asignación, tiene las siguientes opciones:

Para el desplazamiento lateral, arrastre el puntero alrededor de la superficie de la asignación. O bien, mantenga presionada la rueda del mouse mientras mueve el mouse o el trackball.

Después de moverse un nivel hacia abajo en la asignación, en la esquina inferior izquierda de ella, aparece una barra de navegación donde puede seleccionar entre las siguientes opciones:

Screenshot showing map navigation bar.

Opción	Gesto alternativo
Alejamiento	En la superficie de la asignación, presione MAYÚS + doble selección. O bien Desplácese hacia abajo con la rueda del mouse.
Acercamiento	En la superficie de la asignación, seleccione doble. O bien Desplácese hacia arriba con la rueda del mouse.
Zoom hasta ajustar	None
Mostrar (Ocultar) miniasignación	None

Para subir un nivel en la asignación, en la ruta de navegación de la parte superior del mapa, seleccione un nivel anterior.

Selección de elementos de destino y origen para asignar

En la superficie del mapa, a partir del lado derecho, en el área de esquema de destino, seleccione el elemento de destino que desea asignar. Si el elemento que desea es un elemento secundario de un elemento primario, busque y expanda primero el elemento primario.
Ahora, en el lado izquierdo, en el área de esquema de origen, seleccione Seleccionar elemento.
En la ventana Esquema de origen que aparece, seleccione uno o varios elementos de origen para mostrar en la asignación.
- Para incluir elementos primarios y secundarios directos, abra el menú contextual del elemento primario y seleccione Agregar elementos secundarios.
- Para incluir un elemento primario y todos los elementos secundarios de ese elemento primario, incluidos los secundarios, abra el menú contextual del elemento primario de nivel superior y seleccione Agregar elementos secundarios (recursivos).
Cuando haya terminado, puede cerrar la ventana de esquema de origen. Siempre puede añadir más elementos fuente más adelante. En la asignación, en la esquina superior izquierda, seleccione Mostrar esquema de origen ().

Crear una asignación directa entre elementos

Para una transformación sencilla entre elementos con el mismo tipo en los esquemas de origen y destino, siga estos pasos:

Para revisar lo que sucede en el código mientras crea la asignación, en la esquina superior derecha de la asignación, seleccione Mostrar código.
Si aún no lo ha hecho, en la asignación, seleccione los elementos de destino y, a continuación, los elementos de origen que desea asignar.
Mueva el puntero sobre el elemento de origen para que aparezca un círculo y un signo más (+).
Arrastre una línea al elemento de destino para que la línea se conecte al círculo que aparece.

Ahora ha creado una asignación directa entre ambos elementos.

La ventana de vista de código refleja la relación de asignación que ha creado:

Nota:

Si crea una asignación entre elementos en los que sus tipos de datos no coinciden, aparece una advertencia en el elemento de destino, por ejemplo:

Screenshot showing direct mapping between mismatching data types.

Crear una asignación compleja entre elementos

Para una transformación más compleja entre los elementos de los esquemas de origen y destino, como los elementos que desea combinar o que tienen diferentes tipos de datos, puede usar una o varias funciones para realizar tareas para esa transformación.

En la tabla siguiente se enumeran los grupos de funciones disponibles y las funciones de ejemplo que puede usar:

Grupo	Funciones de ejemplo
Collection	Average, Count, Direct Access, Distinct values, Filter, Index, Join, Maximum, Minimum, Reverse, Sort, Subsequence, Sum
Conversión	To date, To integer, To number, To string
Fecha y hora	Sumar días
Comparación lógica	Equal, Exists, Greater, Greater or equal, If, If else, Is nil, Is null, Is number, Is string, Less, Less or equal, Logical AND, Logical NOT, Logical OR, Not equal
Matemáticas	Absolute, Add, Arctangent, Ceiling, Cosine, Divide, Exponential, Exponential (base 10), Floor, Integer divide, Log, Log (base 10), Module, Multiply, Power, Round, Sine, Square root, Subtract, Tangent
String	El código apunta a string, Concat, Contains, Ends with, Length, Lowercase, Name, Regular expression matches, Regular expression replace, Replace, Starts with, String to code-points, Substring, Substring after, Substring before, Trim, Trim left, Trim right, Uppercase
Utilidad	Copy, Error, Execute XPath, Format date-time, Format number, Run XSLT

En la asignación, la etiqueta de la función es similar a la del ejemplo siguiente y está codificada por colores en función del grupo de funciones. En el lado izquierdo del nombre de la función, aparece un símbolo para la función. En el lado derecho del nombre de la función, aparece un símbolo para el tipo de datos de la salida de la función.

Screenshot showing example function label.

Agregar una función sin una relación de asignación

El ejemplo de esta sección transforma el tipo de elemento de origen de tipo String a tipo DateTime, que coincide con el tipo de elemento de destino. En el ejemplo se usa la función To date, que toma una sola entrada.

Para revisar lo que sucede en el código mientras crea la asignación, en la esquina superior derecha de la asignación, seleccione Mostrar código.
Si aún no lo ha hecho, en la asignación, seleccione los elementos de destino y, a continuación, los elementos de origen que desea asignar.
En la esquina superior izquierda de la asignación, seleccione Mostrar funciones ().
En la lista de funciones que se abre, busque y seleccione la función que desea usar, que agrega la función a la asignación. Si la función no aparece visible en la asignación, pruebe a alejar la superficie de ella.

En este ejemplo se selecciona la función To date . También puede encontrar y seleccionar cualquier función personalizada de la misma manera. Para obtener más información, consulte Creación de una función personalizada.

Nota:

Si no existe ninguna línea de asignación o se selecciona al agregar una función a la asignación, la función aparece en la asignación, pero se desconecta de cualquier elemento u otras funciones, por ejemplo:
Expanda la forma de la función para mostrar los detalles y los puntos de conexión de la función. Para expandir la forma de función, seleccione dentro de la forma.
Conecte la función a los elementos de origen y destino.
1. Arrastre y dibuje una línea entre los elementos de origen y el borde izquierdo de la función. Puede iniciar desde los elementos de origen o desde la función.
2. Arrastre y dibuje una línea entre el borde derecho de la función y el elemento de destino. Puede iniciar desde el elemento de destino o desde la función.
En la pestaña Propiedades de la función, confirme o edite la entrada que se va a usar.

Para algunos tipos de datos, como matrices, el ámbito de la transformación también podría aparecer disponible. Este ámbito suele ser el elemento inmediato, como una matriz, pero en algunos escenarios, el ámbito puede existir más allá del elemento inmediato.

La ventana de vista de código refleja la relación de asignación que ha creado:

Por ejemplo, para iterar los elementos de matriz, consulte Creación de un bucle entre matrices. Para realizar una tarea cuando el valor de un elemento cumple una condición, vea Agregar una condición entre elementos.

Adición de una función a una relación de asignación existente

Cuando ya existe una relación de asignación entre los elementos de origen y de destino, puede agregar la función siguiendo estos pasos:

En el mapa, seleccione la línea de la asignación que ha creado.
Mueva el puntero sobre la línea seleccionada y seleccione signo más Insertar función (+) que aparece, por ejemplo:
En la lista de funciones que se abre, busque y seleccione la función que desea usar.

La función aparece en la asignación y se conecta automáticamente entre los elementos de origen y de destino.

Adición de una función con varias entradas

En el ejemplo de esta sección se concatenan varios tipos de elementos de origen para que pueda asignar los resultados al tipo de elemento de destino. En el ejemplo se usa la función Concat, que toma varias entradas.

Para revisar lo que sucede en el código mientras crea la asignación, en la esquina superior derecha de la asignación, seleccione Mostrar código.
Si aún no lo ha hecho, en la asignación, seleccione los elementos de destino y, a continuación, los elementos de origen que desea asignar.
En la esquina superior izquierda de la asignación, seleccione Mostrar funciones ().
En la lista de funciones que se abre, busque y seleccione la función que desea usar, que agrega la función a la asignación. Si la función no aparece visible en la asignación, pruebe a alejar la superficie de ella.

En este ejemplo se selecciona la función Concat:

Nota:

Si no existe ninguna línea de asignación o se selecciona al agregar una función a la asignación, la función aparece en el mapa, pero se desconecta de cualquier elemento u otras funciones. Si la función requiere configuración, aparece un punto rojo en la esquina superior derecha de la función, por ejemplo:
Expanda la forma de la función para mostrar los detalles y los puntos de conexión de la función. Para expandir la forma de función, seleccione dentro de la forma.
En el panel de información de la función, en la pestaña Propiedades, en Entradas, seleccione los elementos de datos de origen que se usarán como entradas.

En este ejemplo se seleccionan los elementos de origen FirstName y LastName como entradas de función, que agregan automáticamente las conexiones respectivas en la asignación.
Para completar la asignación, arrastre y dibuje una línea entre el borde derecho de la función y el elemento de destino. Puede iniciar desde el elemento de destino o desde la función.

La ventana de vista de código refleja la relación de asignación que ha creado:

Creación de un bucle entre matrices

Si los esquemas de origen y destino incluyen matrices, puede crear una relación de asignación de bucles que itere los elementos de esas matrices. El ejemplo de esta sección recorre en bucle una matriz de origen Employee y una matriz de destino Person.

Para revisar lo que sucede en el código mientras crea la asignación, en la esquina superior derecha de la asignación, seleccione Mostrar código.
En la asignación, en el área de esquema de destino, seleccione el elemento de matriz de destino y los elementos de elemento de matriz de destino que desea asignar.
En la asignación, en el área de esquema de destino, expanda el elemento de matriz de destino y los elementos de matriz.
En el área de esquema de origen, agregue el elemento de matriz de origen y los elementos de elemento de matriz al mapa.
Crear una asignación directa entre los elementos de origen y de destino.

Cuando se crea por primera vez una relación de asignación entre un par coincidente de elementos de matriz, se crea automáticamente una relación de asignación en el nivel de matriz principal.

La ventana de vista de código refleja la relación de asignación que ha creado:
Continúe asignando los demás elementos de matriz.

Configurar una condición y una tarea para realizar entre elementos

Para agregar una relación de asignación que evalúe una condición y realice una tarea cuando se cumpla la condición, puede usar varias funciones, como la función If, una función de comparación como Greater y la tarea que se va a realizar, como Multiply.

En el ejemplo de esta sección se calcula un descuento que se aplicará cuando la cantidad de compra supere los 20 artículos mediante las siguientes funciones:

Greater: compruebe si la cantidad de artículos es mayor que 20.
If: compruebe si la función Greater devuelve true.
Multiply: calcule el descuento multiplicando el precio del artículo en un 10% y la cantidad de artículos.

Para revisar lo que sucede en el código mientras crea la asignación, en la esquina superior derecha de la asignación, seleccione Mostrar código.
Si aún no lo ha hecho, en la asignación, seleccione los elementos de destino y, a continuación, los elementos de origen que desea asignar.

En este ejemplo se seleccionan los siguientes elementos:
En la esquina superior izquierda de la asignación, seleccione Mostrar funciones ().
Agregue las siguientes funciones a la asignación: Greater, If y Multiply
Expanda todas las formas de función para mostrar los detalles de la función y los puntos de conexión.
Conecte los elementos de origen, las funciones y los elementos de destino de la siguiente manera:
- Elemento ItemPrice del esquema de origen al elemento ItemPrice del esquema de destino
- Elemento ItemQuantity del esquema de origen al campo Value de la función Greater
- Salida de la función Greater en el campo Condition de la función If
- Elemento ItemPrice del esquema de origen al campo Multiplicand 0* de la función Multiply
- Salida de la función Multiply al campo Value de la función If
- Salida de la función If al elemento ItemDiscount del esquema de destino
Nota

En la función If, la palabra ANY aparece a la derecha del nombre de la función, lo que indica que puede asignar el valor de salida a cualquier elemento.

En las funciones siguientes, en la pestaña Propiedades, especifique los valores siguientes:

Función	Parámetro y valor de entrada
Superior	- Value #1: elemento de origen denominado ItemQuantity - Value #2: 20
Multiplicar	- Multiplicand #1: Elemento de origen denominado ItemPrice - Multiplicand #2: .10
If	- Condition: is-greater-than(ItemQuantity,20) - Value: multiply(ItemPrice, .10)

En el siguiente mapa se muestra el ejemplo finalizado:

Screenshot showing finished condition example.

La ventana de vista de código refleja la relación de asignación que ha creado:

Screenshot showing code view with conditional mapping between source and target elements using the functions, Greater, If, and Multiply.

Guardar el mapa

Cuando esté listo, en la barra de herramientas de asignación, seleccione Guardar.

Visual Studio Code guarda la asignación como los siguientes artefactos:

Un < archivo your-map-name>.yml en la carpeta del proyecto Artifacts>MapDefinitions
Un < archivo your-map-name>.xslt en la carpeta del proyecto Artifacts>Maps

Generar archivo XSLT en cualquier momento

Para generar el archivo <your-map-name>.xslt en cualquier momento, en la barra de herramientas del mapa, seleccione Generar XSLT.

Prueba de la asignación

Para confirmar que la transformación funciona según lo previsto, necesitará datos de entrada de ejemplo.

Antes de probar el mapa, asegúrese de generar el archivo <your-map-name>.xslt más reciente.
En la barra de herramientas del mapa, seleccione Probar.
En el panel Asignación de pruebas, en la ventana Entrada, pegue los datos de entrada de ejemplo y, a continuación, seleccione Probar.

El panel de pruebas cambia a la pestaña Salida y muestra el código de estado y el cuerpo de la respuesta de la prueba.

Llamada a la asignación desde un flujo de trabajo del proyecto

En el menú izquierdo de Visual Studio Code, seleccione Explorer (icono de archivos) para ver la estructura del proyecto de la aplicación lógica.
Expanda la carpeta que tiene el nombre del flujo de trabajo. En el menú contextual del archivo workflow.json, seleccione Abrir diseñador.
En el diseñador de flujos de trabajo, siga estos pasos generales para agregar las Operaciones del Asignador de datos de acción integrada denominada Transformar mediante XSLT del Asignador de datos.
En el diseñador, seleccione la acción Transformar mediante XSLT del Asignador de datos.
En el panel de información de acción que aparece, especifique el valor de Contenido y deje Origen de mapa establecido en Aplicación lógica. En la lista Nombre de asignación, seleccione el archivo de asignación (.xslt) que desea usar.

Para usar la misma acción Transformar mediante XSLT del Asignador de datos en Azure Portal, debe agregar la asignación al recurso aplicación lógica Estándar.

Creación de una función personalizada

Para crear su propia función que puede usar con la herramienta Asignador de datos, siga estos pasos:

Cree un archivo XML (.xml) que tenga un nombre significativo que describa el propósito de la función.

Si tiene varias funciones relacionadas, puede usar un único archivo para estas funciones. Aunque puede usar cualquier nombre de archivo, un nombre de archivo o una categoría significativos facilita la identificación, búsqueda y detección de las funciones.

En el archivo XML, debe usar el esquema siguiente para la definición de función:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="customfunctions">
      <xs:complexType>
         <xs:sequence>
            <xs:element maxOccurs="unbounded" name="function">
               <xs:complexType>
                  <xs:sequence>
                     <xs:element maxOccurs="unbounded" name="param">
                        <xs:complexType>
                            <xs:attribute name="name" type="xs:string" use="required" />
                            <xs:attribute name="as" type="xs:string" use="required" />
                        </xs:complexType>
                     </xs:element>
                     <xs:any minOccurs="0" />
                  </xs:sequence>
                  <xs:attribute name="name" type="xs:string" use="required" />
                  <xs:attribute name="as" type="xs:string" use="required" />
                  <xs:attribute name="description" type="xs:string" use="required" />
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Cada elemento XML denominado "function" implementa una función de estilo XSLT3.0 con algunos atributos más. La lista de funciones del Asignador de datos incluye el nombre de la función, la descripción, los nombres de parámetro y los tipos de parámetro.

En el ejemplo siguiente se muestra la implementación de un archivo SampleFunctions.xml:

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<customfunctions>
   <function name="age" as="xs:float" description="Returns the current age.">
      <param name="inputDate" as="xs:date"/> 
      <value-of select="round(days-from-duration(current-date() - xs:date($inputDate)) div 365.25, 1)"/>
   </function> 
   <function name="custom-if-then-else" as="xs:string" description="Evaluates the condition and returns corresponding value.">
      <param name="condition" as="xs:boolean"/>
      <param name="thenResult" as="xs:anyAtomicType"/>
      <param name="elseResult" as="xs:anyAtomicType"/>
      <choose>
         <when test="$condition">
            <value-of select="$thenResult"></value-of>
         </when>
         <otherwise>
            <value-of select="$elseResult"></value-of>
         </otherwise>
      </choose>
   </function>
</customfunctions>

En el equipo local, abra la carpeta del proyecto de aplicación lógica Estándar.
Abra la carpeta Artifacts y cree la siguiente estructura de carpetas, si no existe ninguna: DataMapper>Extensions>Functions.
En la carpeta Functions, guarde el archivo XML de la función.
Para buscar la función personalizada en la lista de funciones de la herramienta Asignador de datos, busque la función o expanda la colección de Funciones personalizadas.

Pasos siguientes

Para ver transformaciones de datos mediante operaciones B2B en Azure Logic Apps, consulte Incorporación de asignaciones para transformaciones en flujos de trabajo con Azure Logic Apps

Compartir vía