Parámetros para Data Factory en Microsoft Fabric
En este documento se describe cómo usar parámetros en las canalizaciones de Data Factory en Fabric.
Cómo usar parámetros, expresiones y funciones en canalizaciones para Data Factory en Fabric
En este documento, nos centramos en aprender conceptos fundamentales con varios ejemplos para explorar la capacidad de crear canalizaciones de datos con parámetros en Data Factory en Fabric. La parametrización y las expresiones dinámicas pueden ahorrar una gran cantidad de tiempo y permitir una solución mucho más flexible de extracción, transformación, carga (ETL) o extracción, carga, transformación (ELT). Esto reduce drásticamente el costo de mantenimiento de la solución y acelera la implementación de nuevas funciones en las canalizaciones existentes. Estas mejoras se deben a que la parametrización minimiza la cantidad de codificación rígida y aumenta el número de objetos y procesos reutilizables en una solución.
Conceptos de parámetros y expresiones
Puede usar parámetros para pasar valores externos a canalizaciones. Una vez que el parámetro se pasa al recurso, no se puede cambiar. Al parametrizar recursos, puede reutilizarlos con valores diferentes cada vez. Los parámetros se pueden usar individualmente o como parte de las expresiones. Los valores de parámetro de la definición pueden ser literales o expresiones que se evalúan en tiempo de ejecución.
Las expresiones pueden aparecer en cualquier lugar de un valor de cadena y siempre generar otro valor de cadena. Aquí, la contraseña es un parámetro de canalización en la expresión. Si un valor de parámetro es una expresión, el cuerpo de la expresión se extrae quitando el signo at-sign (@). Si se necesita una cadena literal que empiece por @, debe convertirse con @@. En los ejemplos siguientes se muestra cómo se evalúan las expresiones.
| Valor del parámetro | Resultado |
|---|---|
| parámetros | Se devuelven los caracteres de "parameters". |
| parámetros[1] | Se devuelven los caracteres de "parameters[1]". |
| "@@" | Se devuelve una cadena de 1 carácter que contiene '@'. |
| " @" | Se devuelve una cadena de 2 caracteres que contiene " @". |
Las expresiones también pueden aparecer dentro de cadenas, mediante una característica denominada interpolación de cadenas donde las expresiones se encapsulan en @{ ... }. Por ejemplo, la cadena siguiente incluye valores de parámetro y valores de cadena literales:
"First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"
Con la interpolación de cadenas, el resultado siempre es una cadena. Por ejemplo, si definió myNumber como 42 y myString como foo:
| Valor del parámetro | Resultado |
|---|---|
| "@pipeline().parameters.myString" | Devuelve foo como una cadena. |
| "@{pipeline().parameters.myString}" | Devuelve foo como una cadena. |
| "@pipeline().parameters.myNumber" | Devuelve 42 como un número de . |
| "@{pipeline().parameters.myNumber}" | Devuelve 42 como una cadena de . |
| "La respuesta es: @{pipeline().parameters.myNumber}" | Devuelve la cadena Answer is: 42. |
| "@concat('Answer is: ', string(pipeline().parameters.myNumber))" | Devuelve la cadena Answer is: 42 |
| "La respuesta es: @@{pipeline().parameters.myNumber}" | Devuelve la cadena Answer is: @{pipeline().parameters.myNumber}. |
Ejemplos de uso de parámetros en expresiones
Creación y uso de parámetros
Para crear parámetros, seleccione el fondo del lienzo del editor de canalizaciones y, después, la pestaña Parámetros de la ventana de propiedades en la parte inferior. Seleccione el botón + Nuevo para agregar un nuevo parámetro a la canalización, asígnele un nombre, un tipo de datos y un valor predeterminado:
A continuación, puede usar el parámetro en cualquier parte de la canalización donde se admita el contenido dinámico. En este ejemplo, el parámetro se utiliza para proporcionar de forma dinámica el nombre de un almacén de datos tipo Lakehouse en la pestaña Origen de las páginas de propiedades de una actividad de copia.
Se muestra la ventana Agregar contenido dinámico, lo que permite especificar cualquier tipo de contenido dinámico, incluidos los parámetros, variables del sistema, funciones o variables de canalización. En este ejemplo, se selecciona el parámetro definido anteriormente y la ventana de contenido dinámico se rellena automáticamente con la expresión correcta para hacer referencia al parámetro.
Ejemplo de expresión compleja
En el siguiente ejemplo se muestra uno complejo que hace referencia a un subcampo avanzado del resultado de la actividad. Para hacer referencia a un parámetro de canalización que se evalúa como un subcampo, use la sintaxis [] en lugar del operador dot(.) (como con subfield1 y subfield2)
@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*
Editor de contenido dinámico
El editor de contenido dinámico convierte automáticamente los caracteres de escape en el contenido cuando finaliza la edición. Por ejemplo, el siguiente contenido en el editor de contenido es una interpolación de cadenas con una función de expresión:
@{toUpper('myData')}
El editor de contenido dinámico convierte el contenido anterior en la siguiente expresión:
MYDATA
Uso de funciones y variables en expresiones
Puede llamar a funciones y usar variables dentro de expresiones. En las secciones siguientes se proporciona información sobre las funciones que se pueden usar en una expresión.
Variables de ámbito de canalización
Se puede hacer referencia a estas variables del sistema en cualquier JSON de la canalización.
| Nombre de variable | Descripción |
|---|---|
| @pipeline().DataFactory | Nombre de los datos o área de trabajo de Synapse en la que se ejecuta el pipeline |
| @pipeline().Pipeline | Nombre de la canalización |
| @pipeline().RunId | ID de la ejecución de canalización específica |
| @pipeline().TriggerId | Identificador del desencadenador que invocó la canalización |
| @pipeline().TriggerName | Nombre del desencadenador que invocó la canalización |
| @pipeline().TriggerTime | Hora de la ejecución de desencadenador que ha invocado la canalización. Esta es la hora a la que el desencadenador realmente se activó para invocar la ejecución de la canalización y puede diferir ligeramente de la hora programada del desencadenador. |
| @pipeline().GroupId | ID del grupo al que pertenece la ejecución de canalización. En Microsoft Fabric, un "grupo" hace referencia a una colección de recursos relacionados que se pueden administrar juntos. Los grupos se usan para organizar y controlar el acceso a los recursos, lo que facilita la administración de permisos y la supervisión de actividades en varias canalizaciones. |
| @pipeline()?.TriggeredByPipelineName | Nombre de la canalización que desencadena la ejecución de canalización. Se puede aplicar cuando una actividad ExecutePipeline desencadena la ejecución de canalización. Se evalúa como NULL cuando se usa en otras circunstancias. Anote el signo de interrogación después de @pipeline() |
| @pipeline()?.TriggeredByPipelineRunId | ID de ejecución de la canalización que desencadena la ejecución de canalización. Se puede aplicar cuando una actividad ExecutePipeline desencadena la ejecución de canalización. Se evalúa como NULL cuando se usa en otras circunstancias. Anote el signo de interrogación después de @pipeline() |
Nota
Las variables del sistema de fecha y hora relacionadas con el desencadenador (en los ámbitos de la canalización y el desencadenador) devuelven las fechas UTC en formato ISO 8601; por ejemplo, 2017-06-01T22:20:00.4061448Z.
Funciones de cadena
Para trabajar con cadenas, puede usar estas funciones de cadena y también algunas funciones de colección. Las funciones de cadena solo funcionan en cadenas.
| Función de cadena | Tarea |
|---|---|
| concat | Combine dos o más cadenas y devuelva la cadena combinada. |
| endsWith | Compruebe si una cadena termina con la subcadena especificada. |
| guid | Genere un identificador único global (GUID) como una cadena. |
| indexOf | Devuelve la posición inicial de una subcadena. |
| lastIndexOf | Devuelve la posición inicial de la última repetición de una subcadena. |
| reemplazar | Reemplace una subcadena por la cadena especificada y devuelva la cadena actualizada. |
| split | Devuelve una matriz que contiene subcadenas, separadas por comas, de una cadena mayor basada en un carácter delimitador especificado en la cadena original. |
| comienzaCon | Compruebe si una cadena comienza con una subcadena específica. |
| substring | Devuelve caracteres de una cadena a partir de la posición especificada. |
| toLower | Devuelve una cadena en formato en minúsculas. |
| toUpper | Devuelve una cadena en formato mayúscula. |
| trim | Quite el espacio en blanco inicial y final de una cadena y devuelva la cadena actualizada. |
Funciones de colección
Para trabajar con colecciones, generalmente matrices, cadenas y, a veces, diccionarios, puede usar estas funciones de colección.
| Función de colección | Tarea |
|---|---|
| contiene | Compruebe si una colección tiene un elemento específico. |
| vacío | Compruebe si una colección está vacía. |
| first | Devuelve el primer elemento de una colección. |
| intersection | Devuelve una colección que tiene solo los elementos comunes en las colecciones especificadas. |
| join | Devuelve una cadena que tiene todos los elementos de una lista, separados por el carácter especificado. |
| last | Devuelve el último elemento de una colección. |
| length | Devuelve el número de elementos de una cadena o matriz. |
| skip | Quita elementos del principio de una colección y devuelve todos los demás elementos. |
| take | Devuelve elementos del principio de una colección. |
| union | Devuelve una colección que tiene todos los elementos de las colecciones especificadas. |
Funciones lógicas
Estas funciones son útiles dentro de las condiciones, se pueden usar para evaluar cualquier tipo de lógica.
| Función de comparación lógica | Tarea |
|---|---|
| y | Compruebe si todas las expresiones son verdaderas. |
| es igual a | Compruebe si ambos valores son equivalentes. |
| greater | Compruebe si el primer valor es mayor que el segundo. |
| mayor o igual que | Compruebe si el primer valor es mayor o igual que el segundo. |
| si | Verifique si una expresión es verdadera o falsa. En función del resultado, devuelva un valor especificado. |
| menos | Compruebe si el primer valor es menor que el segundo. |
| menor o igual que | Compruebe si el primer valor es menor o igual que el segundo. |
| no | Compruebe si una expresión es falsa. |
| o | Compruebe si al menos una expresión es verdadera. |
Funciones de conversión
Estas funciones se usan para convertir entre cada uno de los tipos nativos en el lenguaje:
- string
- integer
- float
- boolean
- arrays
- Diccionarios
| Función de conversión | Tarea |
|---|---|
| array | Devuelve una matriz de una sola entrada especificada. Para varias entradas, consulte createArray. |
| base64 | Devuelve la versión codificada en base64 para una cadena. |
| base64ToBinary | Devuelve la versión binaria de una cadena codificada en base64. |
| base64ToString | Devuelve la versión de cadena de una cadena codificada en base64. |
| binary | Devuelve la versión binaria de un valor de entrada. |
| bool | Devuelve la versión booleana de un valor de entrada. |
| coalesce | Devuelve el primer valor distinto de NULL de uno o varios parámetros. |
| createArray | Devuelve una matriz de varias entradas. |
| dataUri | Devuelve el URI de datos de un valor de entrada. |
| dataUriToBinary | Devuelve la versión binaria de un URI de datos. |
| dataUriToString | Devuelve la versión de cadena de un URI de datos. |
| decodeBase64 | Devuelve la versión de cadena de una cadena codificada en base64. |
| decodeDataUri | Devuelve la versión binaria de un URI de datos. |
| decodeUriComponent | Devuelve una cadena que reemplaza los caracteres de escape por versiones descodificadas. |
| encodeUriComponent | Devuelve una cadena que reemplaza los caracteres no seguros de dirección URL por caracteres de escape. |
| float | Devuelve un número de punto flotante para un valor de entrada. |
| int | Devuelve la versión de entero de una cadena. |
| json | Devuelve el valor de tipo de notación de objetos JavaScript (JSON) o el objeto para una cadena o XML. |
| string | Devuelve la versión de cadena de un valor de entrada. |
| uriComponent | Devuelve la versión codificada con URI para un valor de entrada reemplazando los caracteres no seguros de dirección URL por caracteres de escape. |
| uriComponentToBinary | Devuelve la versión binaria de una cadena codificada por URI. |
| uriComponentToString | Devuelve la versión de cadena de una cadena codificada por URI. |
| xml | Devuelve la versión XML de una cadena. |
| xpath | Compruebe XML en busca de nodos o valores que coincidan con una expresión XPath (lenguaje de ruta de acceso XML) y devuelva los nodos o valores coincidentes. |
Funciones matemáticas
Estas funciones se pueden usar para cualquiera de los tipos de números: enteros y floats.
| Función matemática | Tarea |
|---|---|
| agregar | Devuelve el resultado de agregar dos números. |
| div | Devuelve el resultado de dividir dos números. |
| max | Devuelve el valor más alto de un conjunto de números o una matriz. |
| min | Devuelve el valor más bajo de un conjunto de números o una matriz. |
| mod | Devuelve el resto de dividir dos números. |
| mul | Devuelve el producto de multiplicar dos números. |
| rand | Devuelve un entero aleatorio a partir de un intervalo especificado. |
| range | Devuelve una matriz de enteros que comienza a partir de un entero especificado. |
| sub | Devuelve el resultado de restar el segundo número del primer número. |
Funciones de fecha
| Función de fecha u hora | Tarea |
|---|---|
| addDays | Agregue un número de días a una marca de tiempo. |
| addHours | Agregue un número de horas a una marca de tiempo. |
| addMinutes | Agregue un número de minutos a una marca de tiempo. |
| addSeconds | Agregue un número de segundos a una marca de tiempo. |
| addToTime | Agregue una serie de unidades de tiempo a una marca de tiempo. Consulte también getFutureTime. |
| convertFromUtc | Convierta una marca de tiempo de la hora universal coordinada (UTC) a la zona horaria de destino. |
| convertTimeZone | Convierta una marca de tiempo de la zona horaria de origen en la zona horaria de destino. |
| convertToUtc | Convierta una marca de tiempo de la zona horaria de origen en Universal Time Coordinated (UTC). |
| díaDelMes | Devuelve el día del componente de mes de una marca de tiempo. |
| díaDeLaSemana | Devuelve el día del componente de semana de una marca de tiempo. |
| díaDelAño | Devuelve el día del componente de año de una marca de tiempo. |
| formatDateTime | Devuelve la marca de tiempo como una cadena en formato opcional. |
| getFutureTime | Devuelve la marca de tiempo actual más las unidades de tiempo especificadas. Consulte también addToTime. |
| getPastTime | Devuelve la marca de tiempo actual menos las unidades de tiempo especificadas. Consulte también subtractFromTime. |
| startOfDay | Devuelve el inicio del día de una marca de tiempo. |
| startOfHour | Devuelve el inicio de la hora de una marca de tiempo. |
| inicioDelMes | Devuelve el inicio del mes de una marca de tiempo. |
| subtractFromTime | Resta un número de unidades de tiempo de una marca de tiempo. Consulte también getPastTime. |
| ticks | Devuelve el valor de la propiedad ticks para una marca de tiempo especificada. |
| utcNow | Devuelve la marca de tiempo actual como una cadena. |