Parámetros para Data Factory en Microsoft Fabric

En este artículo se muestra cómo usar parámetros en las canalizaciones de Data Factory en Fabric para poder crear flujos de trabajo flexibles y reutilizables.

Uso de parámetros, expresiones y funciones en canalizaciones de Data Factory

En esta sección se describen los conceptos básicos de la creación de canalizaciones parametrizadas en Data Factory para Fabric, mediante ejemplos claros a lo largo del proceso. Los parámetros y las expresiones dinámicas ahorran tiempo y permiten crear soluciones flexibles de extracción, transformación, carga (ETL) o extracción, carga, transformación (ELT). Reducen la codificación rígida y permiten reutilizar objetos y procesos, lo que facilita el mantenimiento de las canalizaciones y permite enviar nuevas características más rápidamente.

Conceptos de parámetros y expresiones

Puede usar parámetros para pasar valores externos a las canalizaciones. Después de establecer un parámetro, su valor permanece igual a lo largo de la ejecución. Los parámetros permiten reutilizar la misma canalización con valores diferentes cada vez. Puede usar parámetros por sí solos o en expresiones, con valores fijos o calculados cuando se ejecuta la canalización.

Las expresiones pueden ir a cualquier parte de un valor de cadena y devolver siempre otro valor de cadena. Por ejemplo, si usa @password, la canalización trata la contraseña como parámetro. Si el valor es una expresión, quite la @ para obtener el contenido real. Para usar una cadena que comience por @, escedítelo escribiendo @@. En los ejemplos siguientes se muestra cómo funciona en la práctica.

Valor del parámetro Result
"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 contiene " @".

Las expresiones también pueden aparecer dentro de cadenas a través de la interpolación de cadenas, donde se encapsulan expresiones en @{ ... }. Por ejemplo, la cadena siguiente incluye valores de parámetro y valores de cadena literales:

Nombre: @{pipeline().parameters.firstName} Apellido: @{pipeline().parameters.lastName}

La interpolación de cadenas siempre devuelve una cadena. Por ejemplo, si define myNumber como 42 y myString como foo:

Valor del parámetro Result
"@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('La respuesta es: ', 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 expresiones de parámetro

Creación y uso de parámetros

Para crear parámetros, seleccione el fondo del lienzo del editor de canalizaciones y, a continuación, seleccione la pestaña Parámetros de la ventana de propiedades en la parte inferior. Seleccione + Nuevo para agregar un parámetro a la canalización y asígnele un nombre, un tipo de datos y un valor predeterminado:

Captura de pantalla que muestra el editor de parámetros en las páginas de propiedades de una canalización.

A continuación, puede usar el parámetro en cualquier lugar en el que la canalización admita contenido dinámico. En este ejemplo, el parámetro proporciona dinámicamente el nombre de un almacén de datos de lakehouse en la pestaña Origen de las páginas de propiedades de una actividad de copia.

Captura de pantalla que muestra la pestaña Origen de las páginas de propiedades de una actividad de copia, resaltando la opción Agregar contenido dinámico.

Se abre la ventana Agregar contenido dinámico. Úselo para especificar cualquier tipo de contenido dinámico, incluidos parámetros, variables del sistema, funciones o variables de canalización. En este ejemplo, se selecciona el parámetro que definió anteriormente y la ventana de contenido dinámico se rellena automáticamente con la expresión correcta para hacer referencia a él.

Captura de pantalla que muestra la ventana Agregar contenido dinámico con un parámetro de canalización seleccionado.

Parametrizar conexiones

Para parametrizar las conexiones en canalizaciones, use el identificador único global (GUID) de la conexión que desea reemplazar dinámicamente.

  1. Antes de modificar dinámicamente la conexión en la canalización, obtenga el GUID de la conexión que desea establecer.
  2. Vaya a Configuración>Administrar conexiones y puertas de enlace.
  3. Busque el nombre de conexión y seleccione los puntos suspensivos (...) situados junto a él.
  4. Seleccione Configuración y copie el identificador de conexión.
  5. Pegue el GUID en un parámetro de cadena y haga referencia a ese parámetro en la expresión dinámica.

Ejemplo de expresión compleja

La expresión siguiente hace referencia a un subcampo anidado del resultado de la actividad. Para hacer referencia a un parámetro de canalización cuyo valor se evalúa como un subcampo, use la sintaxis [] en lugar del operador de punto (.), como en 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

Puede hacer referencia a estas variables del sistema en cualquier parte del JSON de la canalización.

Nombre de variable Description
@pipeline().DataFactory Nombre del área de trabajo en la que se ejecuta la canalización
@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. Este valor es el momento en que el activador se activó realmente para iniciar la ejecución de la canalización, y podría diferir ligeramente de la hora programada del activador.
@pipeline().GroupId ID del grupo al que pertenece la ejecución de la canalización. En Microsoft Fabric, un grupo es una colección de recursos relacionados que administra conjuntamente. Los grupos organizan y controlan 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 aplica cuando la actividad Execute Pipeline desencadena una ejecución de la canalización. Da como resultado Null en los demás casos. Observe 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 aplica cuando una actividad Ejecutar una canalización desencadena la ejecución de la canalización. Da como resultado Null en otros casos. Fíjese en el signo de interrogación después de @pipeline().

Note

Las variables del sistema de fecha y hora relacionadas con el desencadenador (en ámbitos de canalización y desencadenador) devuelven fechas de hora universal coordinada (UTC) en formato ISO 8601, por ejemplo, 2017-06-01T22:20:00.4061448Z.

Funciones de cadena

Para trabajar con cadenas, use estas funciones de cadena y también algunas funciones de colección. Las funciones de cadena solo funcionan en cadenas.

Función de cadena Task
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.
replace 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.
startsWith 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 como matrices, cadenas y diccionarios, use estas funciones de colección.

Función de colección Task
contains Compruebe si una colección tiene un elemento específico.
empty 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

Use estas funciones dentro de condiciones para evaluar cualquier tipo de lógica.

Función de comparación lógica Task
and Compruebe si todas las expresiones son verdaderas.
equals Compruebe si ambos valores son equivalentes.
greater Compruebe si el primer valor es mayor que el segundo.
greaterOrEquals Compruebe si el primer valor es mayor o igual que el segundo.
if Verifique si una expresión es verdadera o falsa. En función del resultado, devuelva un valor especificado.
less Compruebe si el primer valor es menor que el segundo.
lessOrEquals Compruebe si el primer valor es menor o igual que el segundo.
not Compruebe si una expresión es falsa.
or Compruebe si al menos una expresión es verdadera.

Funciones de conversión

Use estas funciones para convertir entre cada uno de los tipos nativos del lenguaje:

  • string
  • integer
  • float
  • boolean
  • arrays
  • dictionaries
Función de conversión Task
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

Use estas funciones con ambos tipos de números: enteros y floats.

Función matemática Task
add 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 Task
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 a 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 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.
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 para una marca de tiempo especificada.
utcNow Devuelve la marca de tiempo actual como una cadena.

Contenido relacionado

  • Last updated on