Microsoft Fabric
Parámetros de notebooks en Microsoft Fabric: patrones prácticos para pipelines reutilizables
Haz que un mismo notebook de Fabric sirva para muchas ejecuciones: celda de parámetros, parámetros base del pipeline, validación, ventanas de fechas, entornos, secretos, logging seguro y pruebas.
En este artículo
Un notebook que solo funciona para un cliente, una fecha y un entorno es un script que hay que editar antes de cada ejecución. En cuanto se ejecuta en un pipeline, cada edición se convierte en un riesgo: alguien cambia una fecha en una celda, la confirma en Git por accidente y producción procesa el día equivocado.
Los parámetros resuelven ese problema. La lógica del notebook se mantiene fija y revisada; los valores cambian en cada ejecución. Esta guía explica cómo funcionan realmente los parámetros de los notebooks de Fabric y, después, los patrones que los hacen seguros en producción: validación, ventanas de fechas, valores de entorno, secretos, logging y pruebas.
Cómo funcionan los parámetros de los notebooks de Fabric
Un notebook de Fabric tiene una celda de parámetros opcional. La marcas con Toggle parameter cell en el menú More commands de la celda. Las variables asignadas en esa celda son los parámetros del notebook, y sus valores son los valores predeterminados.
Cuando un pipeline ejecuta el notebook con una actividad Notebook, pasa valores en los parámetros base (Base parameters) de la pestaña Settings de la actividad. En tiempo de ejecución, Fabric inserta una nueva celda inmediatamente después de la celda de parámetros que asigna los valores recibidos. Todo lo que el pipeline no pasa conserva su valor predeterminado.
De ahí se derivan tres consecuencias:
- Los nombres deben coincidir. Un parámetro base llamado
RunDateno sobrescriberun_date. Crea una variable nueva y el valor predeterminado sigue vigente sin ningún aviso. - Los tipos son simples. Los parámetros de notebook admiten
int,float,boolystring. Las listas y los diccionarios no se admiten directamente; pásalos como una cadena JSON y analízalos en el notebook. - El código anterior a la celda de parámetros solo ve los valores predeterminados. Coloca la celda de parámetros cerca del principio, después de los imports, y haz todo el trabajo que dependa de los parámetros después de ella.
Cuando seleccionas un notebook en una actividad Notebook, Fabric puede rellenar automáticamente los parámetros base a partir de la celda de parámetros, con sus nombres, tipos y valores predeterminados. Solo detecta las variables de la celda de parámetros, lo que es otro motivo para mantener ahí todos los parámetros.
Una celda de parámetros mínima
Mantén la celda de parámetros aburrida: asignaciones simples, valores predeterminados seguros y nada de lógica.
# Parameters cell (toggle "parameter cell" on this cell)
client_id = ""
run_date = ""
window_days = 1
pipeline_run_id = ""
environment = "dev"
source_path = "Files/landing/orders"
target_table = "silver_orders"
dry_run = TrueLos valores predeterminados están elegidos para que una ejecución interactiva accidental sea inofensiva: un client_id vacío no supera la validación, y dry_run = True impide las escrituras. Una ejecución real debe pasar valores explícitos.
Pasar valores desde un pipeline
En la actividad Notebook, define cada parámetro base con un nombre y un tipo que coincidan. Los valores pueden ser literales, parámetros del pipeline o expresiones del lenguaje de expresiones de los pipelines, por ejemplo:
| Parámetro base | Tipo | Valor |
|---|---|---|
client_id |
String | @pipeline().parameters.client_id |
run_date |
String | @formatDateTime(pipeline().TriggerTime, 'yyyy-MM-dd') |
window_days |
Int | @pipeline().parameters.window_days |
environment |
String | un parámetro del pipeline o un valor de una Variable Library |
dry_run |
Bool | false |
Es preferible calcular las fechas de negocio en el pipeline a partir de la hora de activación, o pasarlas explícitamente en las reejecuciones, en lugar de consultar la hora actual dentro del notebook. Un notebook que lee la hora actual no se puede volver a ejecutar para el día anterior.
Pasa también un identificador de ejecución. @pipeline().RunId asigna a cada ejecución del pipeline un ID único; pasarlo al notebook como pipeline_run_id permite rastrear cada línea de log y cada fila de salida hasta la ejecución que la generó.
Valida primero los parámetros
Todo lo que llega desde fuera del notebook es una entrada, y las entradas necesitan validación. Coloca una celda de validación justo después de la celda de parámetros y falla rápido con un mensaje claro.
from datetime import date, timedelta
import re
ALLOWED_ENVIRONMENTS = {"dev", "test", "prod"}
CLIENT_ID_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-]{1,62}$")
TABLE_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,127}$")
def validate_parameters():
errors = []
if not CLIENT_ID_PATTERN.fullmatch(client_id or ""):
errors.append("client_id must be lowercase letters, digits or hyphens")
try:
start = date.fromisoformat(run_date)
except ValueError:
errors.append("run_date must be an ISO date such as 2026-10-01")
start = None
if not isinstance(window_days, int) or not 1 <= window_days <= 31:
errors.append("window_days must be an integer between 1 and 31")
if environment not in ALLOWED_ENVIRONMENTS:
errors.append(f"environment must be one of {sorted(ALLOWED_ENVIRONMENTS)}")
if not TABLE_PATTERN.fullmatch(target_table or ""):
errors.append("target_table must be a simple lowercase table name")
if errors:
raise ValueError("Invalid notebook parameters: " + "; ".join(errors))
return start, start + timedelta(days=window_days)
window_start, window_end = validate_parameters()La validación cumple tres funciones. Detecta pronto los errores de configuración del pipeline, antes de que se ejecute cualquier trabajo de Spark. Produce un mensaje de error con el que un ingeniero de guardia puede actuar. Y protege el código que construye rutas o nombres de tablas frente a valores que nunca debieron llegar hasta él. Nunca construyas SQL ni rutas concatenando cadenas sin validar.
Parámetros de fecha y de ventana
El manejo de fechas provoca más errores de reprocesamiento que cualquier otro parámetro. Unas pocas reglas lo hacen predecible:
- Pasa las fechas como cadenas ISO (
2026-10-01) y analízalas una sola vez, en la celda de validación. - Usa ventanas semiabiertas: incluye el inicio y excluye el final.
window_start <= event_date < window_endnunca cuenta dos veces un día límite. - Haz explícita la ventana.
run_datejunto conwindow_dayspermite que el mismo notebook procese un día, recupere una semana o reprocese un mes sin cambiar el código. - Haz que las escrituras sean idempotentes para la ventana. Volver a ejecutar la misma ventana debe producir el mismo resultado, lo que normalmente implica reemplazar o fusionar las filas de esa ventana en lugar de volver a anexarlas.
from pyspark.sql import functions as F
orders = (
spark.read.format("delta")
.load(source_path)
.where(F.col("client_id") == client_id)
.where(
(F.col("order_date") >= F.lit(window_start))
& (F.col("order_date") < F.lit(window_end))
)
)Filtrar por la ventana lo antes posible también permite que Delta omita los archivos y las particiones que no necesita, algo importante en tablas grandes.
Configuración del entorno y del runtime
No todos los valores deben ser parámetros del pipeline. Separa tres tipos de configuración:
- Parámetros de ejecución, que cambian en cada ejecución:
client_id,run_date,window_days,pipeline_run_id,dry_run. Su lugar es la celda de parámetros y la actividad Notebook. - Configuración del entorno, que cambia de un workspace a otro pero no de una ejecución a otra: ubicaciones de origen, ajustes de retención, interruptores de funcionalidades. Las Variable Libraries de Fabric están diseñadas para esto. Un notebook puede leerlas con
notebookutils.variableLibrary, y los pipelines pueden hacer referencia a variables de la biblioteca en contenido dinámico. El conjunto de valores activo sigue al entorno..getLibrary(“<library name>”) - Contexto del runtime, que Fabric ya conoce:
notebookutils.runtime.contextdevuelve propiedades de solo lectura como el ID y el nombre del workspace actual, el nombre del notebook, el Lakehouse predeterminado y si la ejecución procede de un pipeline (isForPipeline).
Mezclar estas categorías da lugar a notebooks frágiles. Un parámetro de ejecución environment que quien llama puede establecer en prod desde un workspace de desarrollo es un riesgo; derivar la configuración específica del entorno de una Variable Library vinculada al workspace es más seguro. En el despliegue, el cableado entre elementos, como los ID del Lakehouse predeterminado, es otra cuestión distinta, que resuelve el archivo de parámetros de la herramienta de despliegue, como se describe en CI/CD de Microsoft Fabric con fabric-cicd: de Git a DEV, QA y PROD.
Parámetros de tenant y de cliente
Los notebooks multicliente son donde más rinden los parámetros y donde más caros resultan los errores.
- Trata
client_idcomo un filtro que siempre debe aplicarse. Aplícalo al leer e inclúyelo en la condición de escritura, para que un error no pueda escribir los datos de un cliente en la partición de otro. - Valídalo contra una lista conocida cuando exista, no solo contra un patrón.
- Mantén el comportamiento específico de cada cliente en los datos, no en ramas del código. Una tabla de configuración con
client_idcomo clave es más fácil de revisar que bloquesif client_id == .... - Ejecuta los clientes por separado cuando el aislamiento importe más que el rendimiento. El fallo de un cliente no debería revertir a los demás.
Para el fan-out, un ForEach del pipeline sobre una lista de clientes que llama al mismo notebook es más fácil de monitorizar que un único notebook que itera internamente. Cada cliente obtiene su propia ejecución de actividad, su estado y su duración. Si muchas ejecuciones cortas de notebooks pagan un coste elevado de arranque de sesión, los session tags pueden permitir que las ejecuciones compatibles reutilicen una sesión de Spark.
Los secretos no son parámetros
Nunca pases contraseñas, claves ni cadenas de conexión como parámetros de notebook. Los valores de los parámetros aparecen en las definiciones del pipeline, en las entradas de las actividades y en el historial de ejecuciones, y acaban en Git cuando se confirma el pipeline.
En su lugar, pasa el nombre de un secreto y resuélvelo dentro del notebook:
api_key = notebookutils.credentials.getSecret(
"https://your-key-vault.vault.azure.net/",
"orders-api-key",
)La identidad que ejecuta el notebook necesita permisos sobre el Key Vault. La salida del notebook intenta ocultar un secreto recuperado si lo imprimes, pero Microsoft lo describe como una protección de mejor esfuerzo (best effort), no como un límite de seguridad. No imprimas, registres ni escribas valores de secretos, y evita incorporarlos a cadenas que después registras.
Registra los parámetros de forma segura
Registrar los parámetros de cada ejecución es una de las ayudas de depuración más baratas que puedes añadir. Cuando una cifra parece incorrecta, la primera pregunta siempre es: «¿qué se le pidió hacer a esta ejecución?».
import json
ctx = notebookutils.runtime.context
run_record = {
"pipeline_run_id": pipeline_run_id,
"notebook": ctx["currentNotebookName"],
"workspace_id": ctx["currentWorkspaceId"],
"is_pipeline_run": ctx["isForPipeline"],
"client_id": client_id,
"run_date": run_date,
"window_days": window_days,
"target_table": target_table,
"dry_run": dry_run,
}
print(json.dumps(run_record, default=str))Registra una lista explícita de parámetros permitidos, no globals(), para que un secreto o un dato personal nunca se filtre a los logs por accidente. Para un historial duradero, escribe el mismo registro en una tabla de log de ejecución, como se describe en Diseñar un registro de ejecución para pipelines de datos, y úsala junto con el monitoreo de pipelines y notebooks.
Devolver un valor al pipeline
Un notebook puede terminar con notebookutils.notebook.exit(value). El valor siempre es una cadena. El pipeline puede leerlo en la salida de la actividad Notebook y usarlo en actividades posteriores, por ejemplo para omitir un paso posterior cuando no se ha procesado ninguna fila. Devuelve una cadena JSON pequeña con recuentos o un estado, no datos.
Dos precauciones: no llames a exit() dentro de un bloque try/except, porque la salida no surte efecto cuando está envuelta en el manejo de excepciones; y recuerda que exit() termina la ejecución correctamente. Para que la actividad falle, lanza una excepción.
Reutilizar un notebook en varios pipelines
Un notebook bien parametrizado se convierte en un bloque reutilizable:
- Una transformación, muchas entradas. El mismo notebook procesa cada cliente, cada sistema de origen o cada región, guiado por parámetros.
- Notebooks hijos.
notebookutils.notebookejecuta otro notebook con argumentos y devuelve su valor de salida..run(“child_notebook”, 600, {“client_id”: client_id, “run_date”: run_date}) notebookutils.notebookpuede ejecutar varios notebooks con dependencias..runMultiple() - Configuración de la sesión. Una celda
%%configurese puede parametrizar para que un pipeline pase valores como los núcleos del driver en una ejecución pesada. Un notebook usa los valores predeterminados en las ejecuciones interactivas, y las ejecuciones programadas de notebooks no admiten la configuración de sesión parametrizada.
Sé honesto con la reutilización: si dos llamadores necesitan una lógica sustancialmente distinta, dos notebooks son más claros que uno lleno de indicadores de modo.
Probar combinaciones de parámetros
Los parámetros multiplican el número de formas en que puede ejecutarse un notebook. Prueba las combinaciones que importan:
- Valores predeterminados. Una ejecución interactiva con los valores predeterminados debe fallar en la validación o no hacer nada dañino.
- Ejecución típica. Un cliente, un día.
- Límites. El primer día de un mes, el último, un 29 de febrero, una ventana que cruza un cambio de mes o de año.
- Reprocesamiento. La misma ventana dos veces; el resultado no debe cambiar.
- Entrada vacía. Un cliente sin datos en la ventana debe terminar correctamente e informar de cero filas, no fallar de forma confusa.
- Entrada no válida. Cliente desconocido, fecha mal formada,
window_days = 0: cada caso debe fallar en la validación con un mensaje claro.
Mantén la lógica de validación y de ventanas en funciones de Python sencillas para poder hacerles pruebas unitarias sin Spark. Ejecuta una prueba de integración con un conjunto de datos pequeño en un workspace de desarrollo antes de fusionar cambios en el notebook.
Errores comunes
- Nombres de parámetros que no coinciden entre la actividad y la celda de parámetros, de modo que los valores predeterminados se imponen sin avisar.
- Lógica dentro de la celda de parámetros, que se ejecuta antes de los valores insertados y luego queda sobrescrita.
- Leer la fecha actual dentro del notebook, lo que hace imposibles las reejecuciones.
- Pasar secretos como parámetros y encontrarlos en el historial de ejecuciones y en Git.
- Sin validación, de modo que un valor mal formado falla en lo más profundo de un job de Spark con un error poco útil.
- Anexar al reejecutar, lo que duplica los datos de la ventana.
- Valores predeterminados inseguros como
environment = "prod"odry_run = False. - Pasar una lista como cadena sin analizarla, y acabar iterando sobre sus caracteres.
Recomendación
Diseña cada notebook de pipeline como una función: una celda de parámetros con valores predeterminados seguros, una celda de validación que falla rápido, ventanas de fechas semiabiertas explícitas, escrituras idempotentes y un registro estructurado de la ejecución. Guarda los secretos en Key Vault, la configuración del entorno en Variable Libraries y los valores de cada ejecución en la celda de parámetros.
Esa estructura hace que un mismo notebook se pueda llamar de forma segura desde muchos pipelines, sea fácil de volver a ejecutar y fácil de diagnosticar. Además, mantiene fuera del código las ediciones específicas de cada entorno, que es lo que permite que la integración con Git y el despliegue automatizado funcionen sin fricciones.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Sigue aprendiendo
- Guía rápidaDepurar pipelines de FabricDiagnostica los fallos de pipelines de Microsoft Fabric aislando la actividad que falló, separando los errores transitorios de los deterministas, validando parámetros e identidades, y usando reintentos, registro y re-ejecuciones controladas de forma segura.Abrir guía rápida
- ArtículoActividad Invoke Pipeline de Microsoft Fabric: crea pipelines modulares y reutilizablesUsa la actividad Invoke Pipeline de Microsoft Fabric para componer pipelines padre e hijo parametrizados entre áreas de trabajo, con conexiones seguras y monitorización práctica.Leer artículo
¿Qué debería crear después?
Estoy construyendo Javi Builds alrededor de problemas reales que enfrentan los ingenieros de datos. Dime qué tema te gustaría ver después.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.