Parámetros de Data Factory en Microsoft Fabric

En este documento, se describe cómo usar parámetros en las canalizaciones para Data Factory en Fabric.

Procedimientos para usar parámetros, expresiones y funciones en canalizaciones para Data Factory en Fabric

En este documento, nos centraremos en aprender conceptos fundamentales con varios ejemplos para explorar la capacidad de crear canalizaciones de datos parametrizados dentro de Data Factory en Fabric. La parametrización y las expresiones dinámicas pueden ahorrar mucho tiempo y permiten una solución de extracción, transformación y carga de datos (ETL), o de extracción, carga de datos y transformación (ELT) mucho más flexible, lo que reduce drásticamente el costo del mantenimiento de la solución y acelera la implementación de nuevas características en las canalizaciones existentes. Estas mejoras se deben a que la parametrización reduce la cantidad de codificación de forma 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 ha pasado al recurso, no se puede cambiar. Mediante la parametrización de recursos, puede reutilizarlos con valores diferentes cada vez. Los parámetros se pueden utilizar individualmente o como parte de 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 devolver siempre otro valor de cadena. Aquí, password es un parámetro de canalización de la expresión. Si un valor de parámetro es una expresión, se extrae el cuerpo de la expresión quitando el signo arroba (@). Si se necesita una cadena literal que empiece por @, debe convertirse con @@. Los ejemplos siguientes muestran cómo se evalúan las expresiones.

Valor del parámetro	Resultado
"parameters"	Se devuelven los caracteres de "parameters".
"parameters[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 contienen \" \@\".

Las expresiones también pueden aparecer dentro de las cadenas mediante una característica llamada interpolación de cadenas, donde las expresiones se ajustan 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 cadena, el resultado siempre es una cadena. Por ejemplo, si ha definido 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.
"@{pipeline().parameters.myNumber}"	Devuelve 42 como una cadena.
"Answer is: @{pipeline().parameters.myNumber}"	Devuelve la cadena Answer is: 42.
"@concat('Answer is: ', string(pipeline().parameters.myNumber))"	Devuelve la cadena Answer is: 42.
"Answer is: @@{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; después, asígnele un nombre, un tipo de datos y un valor predeterminado:

Después, puede usar el parámetro en cualquier lugar de la canalización donde se admita el contenido dinámico. En este ejemplo, el parámetro se usa para proporcionar dinámicamente el nombre de un almacén de datos de tipo Almacén de lago de datos 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 de manera automática con la expresión correcta para hacer referencia al parámetro.

Ejemplo de expresión compleja

En el ejemplo siguiente se muestra un ejemplo complejo que hace referencia a un subcampo profundo de la salida 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 punto (.) (como en el caso de 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 contenido siguiente del 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 siguientes secciones 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 la variable	Descripción
@pipeline().DataFactory	Nombre de los datos o el área de trabajo de Synapse donde se realiza la ejecución de la canalización
@pipeline().Pipeline	Nombre de la canalización
@pipeline().RunId	Id. de la ejecución de canalización específica
@pipeline().TriggerId	Id. del desencadenador que ha invocado la canalización.
@pipeline().TriggerName	Nombre del desencadenador que ha invocado 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	Identificador del grupo al que pertenece la ejecución de canalización.
@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. Observe el signo de interrogación después de @pipeline()
@pipeline()?.TriggeredByPipelineRunId	Identificador 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. Observe 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 locales 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	Combina dos o más cadenas y devuelve la cadena combinada.
endsWith	Comprueba si una cadena termina con la subcadena especificada.
guid	Genera 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.
replace	Reemplaza una subcadena por la cadena especificada y devuelve la cadena actualizada.
split	Devuelve una matriz que contiene subcadenas, separadas por comas, de una cadena mayor en función de un carácter delimitador especificado en la cadena original.
startsWith	Comprueba si una cadena comienza con una subcadena especificada.
substring	Devuelve caracteres de una cadena, a partir de la posición especificada.
toLower	Devuelve una cadena en formato de minúsculas.
toUpper	Devuelve una cadena en formato de mayúsculas.
trim	Quita el espacio en blanco inicial y final de una cadena y devuelve la cadena actualizada.

Funciones de colección

Para trabajar con colecciones, por lo general matrices, cadenas y, en ocasiones, diccionarios, puede usar estas funciones de colección.

Función de colección	Tarea
contains	Comprueba si una colección contiene un elemento específico.
empty	Comprueba 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 matriz, 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 una 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 en las condiciones y se pueden usar para evaluar cualquier tipo de lógica.

Función de comparación lógica	Tarea
y	Comprueba si todas las expresiones son true.
equals	Comprueba si ambos valores son equivalentes.
greater	Comprueba si el primer valor es mayor que el segundo.
greaterOrEquals	Comprueba si el primer valor es mayor o igual que el segundo.
if	Comprueba si una expresión es true o false. En función del resultado, devuelve un valor especificado.
less	Comprueba si el primer valor es menor que el segundo.
lessOrEquals	Compruebe si el primer valor es menor o igual que el segundo valor.
not	Comprueba si una expresión es false.
or	Comprueba si al menos una expresión es true.

Funciones de conversión

Estas funciones se utilizan para convertir en cada uno de los tipos nativos del idioma:

• string
• integer
• FLOAT
• boolean
• arrays
• dictionaries

Función de conversión	Tarea
array	Devuelve una matriz a partir de una única entrada especificada. Para varias entradas, consulte createArray.
base64	Devuelve la versión de una cadena codificada en base64.
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 más parámetros.
createArray	Devuelve una matriz a partir 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 la dirección URL por caracteres de escape.
float	Devuelve un número de punto flotante de un valor de entrada.
int	Devuelve la versión como número entero de una cadena.
json	Devuelve el valor o el objeto de tipo Notación de objetos JavaScript (JSON) de una cadena o XML.
string	Devuelve la versión de cadena de un valor de entrada.
uriComponent	Devuelve la versión codificada con el URI de un valor de entrada mediante la sustitución de los caracteres no seguros de la dirección URL por caracteres de escape.
uriComponentToBinary	Devuelve la versión binaria de una cadena codificada con el URI.
uriComponentToString	Devuelve la versión de cadena de una cadena codificada con el URI.
xml	Devuelve la versión XML de una cadena.
xpath	Comprueba el código XML de los nodos o valores que coinciden con una expresión XPath (XML Path Language) y devuelve los nodos o valores coincidentes.

Funciones matemáticas

Estas funciones pueden utilizarse para ambos tipos de números: enteros y flotantes.

Función matemática	Tarea
agregar	Devuelve el resultado de sumar 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 desde un intervalo especificado.
range	Devuelve una matriz de enteros que comienza en un entero especificado.
sub	Devuelve el resultado de restar el segundo número del primero.

Funciones de fecha

Función de fecha u hora	Tarea
addDays	Agrega un número de días a una marca de tiempo.
addHours	Agrega un número de horas a una marca de tiempo.
addMinutes	Agrega un número de minutos a una marca de tiempo.
addSeconds	Agrega un número de segundos a una marca de tiempo.
addToTime	Agrega un número de unidades de tiempo a una marca de tiempo. Consulte también getFutureTime.
convertFromUtc	Convierte una marca de tiempo del formato Hora Universal Coordinada (UTC) a la zona horaria de destino.
convertTimeZone	Convierte una marca de tiempo de la zona horaria de origen a la zona horaria de destino.
convertToUtc	Convierte una marca de tiempo de la zona horaria de origen al formato Hora Universal Coordinada (UTC).
dayOfMonth	Devuelve el día del componente de mes de una marca de tiempo.
dayOfWeek	Devuelve el día del componente de semana de una marca de tiempo.
dayOfYear	Devuelve el día del componente de año de una marca de tiempo.
formatDateTime	Devuelve la marca de tiempo como 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.
startOfMonth	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 de una marca de tiempo especificada.
utcNow	Devuelve la marca de tiempo actual como una cadena.

Contenido relacionado

• Lenguaje de expresiones