Microsoft Fabric
Paramètres des notebooks Microsoft Fabric : modèles pratiques pour des pipelines réutilisables
Faites servir un même notebook Fabric à de nombreuses exécutions : cellule de paramètres, paramètres de base du pipeline, validation, fenêtres de dates, environnements, secrets, journalisation sûre et tests.
Dans cet article
Un notebook qui ne fonctionne que pour un client, une date et un environnement est un script qu’il faut modifier avant chaque exécution. Dès qu’il tourne dans un pipeline, chaque modification devient un risque : quelqu’un change une date dans une cellule, la valide par erreur, et la production traite le mauvais jour.
Les paramètres règlent ce problème. La logique du notebook reste fixe et relue ; seules les valeurs changent à chaque exécution. Ce guide explique comment fonctionnent réellement les paramètres des notebooks Fabric, puis présente les modèles qui les rendent sûrs en production : validation, fenêtres de dates, valeurs d’environnement, secrets, journalisation et tests.
Comment fonctionnent les paramètres des notebooks Fabric
Un notebook Fabric possède une cellule de paramètres facultative. Vous la désignez avec Toggle parameter cell dans le menu More commands de la cellule. Les variables affectées dans cette cellule sont les paramètres du notebook, et leurs valeurs sont les valeurs par défaut.
Lorsqu’un pipeline exécute le notebook avec une activité Notebook, il transmet des valeurs dans les paramètres de base (Base parameters) de l’onglet Settings de l’activité. Au moment de l’exécution, Fabric injecte une nouvelle cellule juste après la cellule de paramètres, qui affecte les valeurs transmises. Tout ce que le pipeline ne transmet pas conserve sa valeur par défaut.
Trois conséquences en découlent :
- Les noms doivent correspondre. Un paramètre de base nommé
RunDatene remplace pasrun_date. Il crée une nouvelle variable, et la valeur par défaut reste silencieusement en vigueur. - Les types sont simples. Les paramètres de notebook prennent en charge
int,float,booletstring. Les listes et les dictionnaires ne sont pas pris en charge directement ; transmettez-les sous forme de chaîne JSON et analysez-les dans le notebook. - Le code situé avant la cellule de paramètres ne voit que les valeurs par défaut. Placez la cellule de paramètres en haut du notebook, après les imports, et effectuez tout le travail qui dépend des paramètres après elle.
Lorsque vous sélectionnez un notebook dans une activité Notebook, Fabric peut renseigner automatiquement les paramètres de base à partir de la cellule de paramètres, avec leurs noms, types et valeurs par défaut. Il ne découvre que les variables de la cellule de paramètres, ce qui est une raison de plus pour y regrouper tous les paramètres.
Une cellule de paramètres minimale
Gardez la cellule de paramètres ennuyeuse : de simples affectations, des valeurs par défaut sûres, aucune logique.
# 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 = TrueLes valeurs par défaut sont choisies pour qu’une exécution interactive accidentelle soit sans danger : un client_id vide échoue à la validation, et dry_run = True empêche les écritures. Une véritable exécution doit transmettre des valeurs explicites.
Transmettre des valeurs depuis un pipeline
Dans l’activité Notebook, définissez chaque paramètre de base avec un nom et un type correspondants. Les valeurs peuvent être des littéraux, des paramètres de pipeline ou des expressions du langage d’expressions des pipelines, par exemple :
| Paramètre de base | Type | Valeur |
|---|---|---|
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 paramètre de pipeline ou une valeur de Variable Library |
dry_run |
Bool | false |
Calculez de préférence les dates métier dans le pipeline à partir de l’heure de déclenchement, ou transmettez-les explicitement pour les réexécutions, plutôt que d’appeler « maintenant » dans le notebook. Un notebook qui lit l’heure courante ne peut pas être réexécuté pour la veille.
Transmettez aussi un identifiant d’exécution. @pipeline().RunId attribue un identifiant unique à chaque exécution du pipeline ; le transmettre au notebook sous le nom pipeline_run_id permet de rattacher chaque ligne de journal et chaque ligne produite à l’exécution qui l’a générée.
Valider les paramètres en premier
Tout ce qui vient de l’extérieur du notebook est une entrée, et une entrée doit être validée. Placez une cellule de validation juste après la cellule de paramètres et échouez rapidement avec un message clair.
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 validation remplit trois rôles. Elle détecte tôt les erreurs de configuration du pipeline, avant le moindre travail Spark. Elle produit un message d’erreur sur lequel un ingénieur d’astreinte peut agir. Et elle protège le code qui construit des chemins ou des noms de tables contre des valeurs qui n’auraient jamais dû y parvenir. Ne construisez jamais de requêtes SQL ou de chemins en concaténant des chaînes non validées.
Paramètres de date et de fenêtre
La gestion des dates provoque plus de bogues de retraitement que n’importe quel autre paramètre. Quelques règles la rendent prévisible :
- Transmettez les dates sous forme de chaînes ISO (
2026-10-01) et analysez-les une seule fois, dans la cellule de validation. - Utilisez des fenêtres semi-ouvertes : incluez le début, excluez la fin.
window_start <= event_date < window_endne compte jamais deux fois un jour de bordure. - Rendez la fenêtre explicite.
run_datecombiné àwindow_dayspermet au même notebook de traiter un jour, de rattraper une semaine ou de retraiter un mois sans modifier le code. - Rendez les écritures idempotentes pour la fenêtre. Réexécuter la même fenêtre doit produire le même résultat, ce qui signifie généralement remplacer ou fusionner les lignes de cette fenêtre au lieu de les ajouter une nouvelle fois.
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))
)
)Filtrer sur la fenêtre le plus tôt possible permet aussi à Delta d’ignorer les fichiers et les partitions dont il n’a pas besoin, ce qui compte sur les grandes tables.
Configuration de l’environnement et de l’exécution
Toutes les valeurs ne doivent pas être des paramètres de pipeline. Distinguez trois types de configuration :
- Les paramètres d’exécution, qui changent à chaque exécution :
client_id,run_date,window_days,pipeline_run_id,dry_run. Leur place est dans la cellule de paramètres et dans l’activité Notebook. - La configuration d’environnement, qui change d’un espace de travail à l’autre mais pas d’une exécution à l’autre : emplacements des sources, paramètres de rétention, commutateurs de fonctionnalités. Les Variable Libraries de Fabric sont conçues pour cela. Un notebook peut les lire avec
notebookutils.variableLibrary, et les pipelines peuvent référencer des variables de bibliothèque dans du contenu dynamique. Le jeu de valeurs actif suit l’environnement..getLibrary(“<library name>”) - Le contexte d’exécution, que Fabric connaît déjà :
notebookutils.runtime.contextrenvoie des propriétés en lecture seule comme l’identifiant et le nom de l’espace de travail courant, le nom du notebook, le Lakehouse par défaut et l’indication que l’exécution provient ou non d’un pipeline (isForPipeline).
Confondre ces catégories produit des notebooks fragiles. Un paramètre d’exécution environment que l’appelant peut définir à prod depuis un espace de travail de développement constitue un risque ; dériver les paramètres propres à l’environnement d’une Variable Library liée à l’espace de travail est plus sûr. Lors du déploiement, le câblage entre éléments, comme les identifiants du Lakehouse par défaut, est encore une autre question, traitée par le fichier de paramètres de l’outil de déploiement, comme décrit dans CI/CD Microsoft Fabric avec fabric-cicd : de Git vers DEV, QA et PROD.
Paramètres de tenant et de client
C’est dans les notebooks multiclients que les paramètres rapportent le plus, et que les erreurs coûtent le plus cher.
- Traitez
client_idcomme un filtre qui doit toujours s’appliquer. Appliquez-le à la lecture et incluez-le dans la condition d’écriture, afin qu’un bogue ne puisse pas écrire les données d’un client dans la partition d’un autre client. - Validez-le par rapport à une liste connue lorsqu’elle existe, et pas seulement par rapport à un motif.
- Placez le comportement propre à chaque client dans les données, pas dans des branches de code. Une table de configuration indexée par
client_idest plus facile à relire que des blocsif client_id == .... - Exécutez les clients séparément lorsque l’isolation compte davantage que le débit. L’échec d’un client ne doit pas annuler les autres.
Pour la distribution (fan-out), une boucle ForEach de pipeline sur une liste de clients qui appelle le même notebook est plus facile à superviser qu’un notebook qui boucle en interne. Chaque client obtient sa propre exécution d’activité, son propre statut et sa propre durée. Si de nombreuses exécutions courtes de notebooks paient un coût de démarrage de session élevé, les session tags peuvent permettre à des exécutions compatibles de réutiliser une session Spark.
Les secrets ne sont pas des paramètres
Ne transmettez jamais de mots de passe, de clés ou de chaînes de connexion comme paramètres de notebook. Les valeurs des paramètres apparaissent dans les définitions de pipeline, les entrées d’activité et l’historique des exécutions, et elles finissent dans Git lorsque le pipeline est validé.
Transmettez plutôt le nom d’un secret et résolvez-le dans le notebook :
api_key = notebookutils.credentials.getSecret(
"https://your-key-vault.vault.azure.net/",
"orders-api-key",
)L’identité d’exécution doit disposer d’autorisations sur le Key Vault. La sortie du notebook tente de masquer un secret récupéré si vous l’affichez, mais Microsoft présente ce mécanisme comme une protection au mieux (best effort), pas comme une frontière de sécurité. N’affichez pas, ne journalisez pas et n’écrivez pas les valeurs des secrets, et évitez de les intégrer à des chaînes que vous journalisez ensuite.
Journaliser les paramètres en toute sécurité
Journaliser les paramètres de chaque exécution est l’une des aides au débogage les moins coûteuses que vous puissiez ajouter. Lorsqu’un chiffre semble faux, la première question est toujours : « qu’a-t-on demandé à cette exécution de faire ? ».
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))Journalisez une liste explicite de paramètres autorisés, pas globals(), afin qu’un secret ou une valeur personnelle ne fuie jamais par accident dans les journaux. Pour un historique durable, écrivez le même enregistrement dans une table de journal d’exécution, comme décrit dans Concevoir un journal d’exécution pour les pipelines de données, et utilisez-la en complément de la supervision des pipelines et des notebooks.
Renvoyer une valeur au pipeline
Un notebook peut se terminer par notebookutils.notebook.exit(value). La valeur est toujours une chaîne. Le pipeline peut la lire dans la sortie de l’activité Notebook et l’utiliser dans les activités suivantes, par exemple pour ignorer une étape en aval lorsqu’aucune ligne n’a été traitée. Renvoyez une petite chaîne JSON contenant des compteurs ou un statut, pas des données.
Deux mises en garde : n’appelez pas exit() dans un bloc try/except, car la sortie ne prend pas effet lorsqu’elle est enveloppée dans une gestion d’exceptions ; et n’oubliez pas que exit() termine l’exécution avec succès. Pour faire échouer l’activité, levez une exception.
Réutiliser un notebook dans plusieurs pipelines
Un notebook bien paramétré devient une brique réutilisable :
- Une transformation, de nombreuses entrées. Le même notebook traite chaque client, chaque système source ou chaque région, piloté par des paramètres.
- Notebooks enfants.
notebookutils.notebookexécute un autre notebook avec des arguments et renvoie sa valeur de sortie..run(“child_notebook”, 600, {“client_id”: client_id, “run_date”: run_date}) notebookutils.notebookpeut exécuter plusieurs notebooks avec des dépendances..runMultiple() - Configuration de session. Une cellule
%%configurepeut être paramétrée pour qu’un pipeline transmette des valeurs comme le nombre de cœurs du driver pour une exécution lourde. Un notebook utilise les valeurs par défaut lors des exécutions interactives, et les exécutions planifiées de notebooks ne prennent pas en charge la configuration de session paramétrée.
Restez honnête sur la réutilisation : si deux appelants ont besoin d’une logique sensiblement différente, deux notebooks sont plus clairs qu’un seul notebook rempli d’indicateurs de mode.
Tester les combinaisons de paramètres
Les paramètres multiplient le nombre de façons dont un notebook peut s’exécuter. Testez les combinaisons qui comptent :
- Valeurs par défaut. Une exécution interactive avec les valeurs par défaut doit échouer à la validation ou ne rien faire de dangereux.
- Exécution typique. Un client, un jour.
- Cas limites. Le premier jour d’un mois, le dernier jour, un 29 février, une fenêtre qui chevauche deux mois ou deux années.
- Retraitement. La même fenêtre deux fois ; le résultat ne doit pas changer.
- Entrée vide. Un client sans données dans la fenêtre doit réussir et signaler zéro ligne, pas échouer de manière obscure.
- Entrée non valide. Client inconnu, date mal formée,
window_days = 0: chaque cas doit échouer à la validation avec un message clair.
Gardez la logique de validation et de fenêtre dans de simples fonctions Python afin de pouvoir les tester unitairement sans Spark. Exécutez un test d’intégration avec un petit jeu de données dans un espace de travail de développement avant de fusionner des modifications du notebook.
Erreurs courantes
- Noms de paramètres différents entre l’activité et la cellule de paramètres, si bien que les valeurs par défaut l’emportent silencieusement.
- De la logique dans la cellule de paramètres, qui s’exécute avant les valeurs injectées puis se retrouve écrasée.
- Lire la date courante dans le notebook, ce qui rend les réexécutions impossibles.
- Transmettre des secrets comme paramètres et les retrouver dans l’historique des exécutions et dans Git.
- Aucune validation, si bien qu’une valeur mal formée échoue au fond d’un job Spark avec une erreur peu utile.
- Ajouter des lignes lors d’une réexécution, ce qui duplique les données de la fenêtre.
- Des valeurs par défaut dangereuses comme
environment = "prod"oudry_run = False. - Transmettre une liste sous forme de chaîne sans l’analyser, puis itérer sur ses caractères.
Recommandation
Concevez chaque notebook de pipeline comme une fonction : une cellule de paramètres avec des valeurs par défaut sûres, une cellule de validation qui échoue rapidement, des fenêtres de dates semi-ouvertes explicites, des écritures idempotentes et un enregistrement structuré de l’exécution dans les journaux. Gardez les secrets dans Key Vault, les paramètres d’environnement dans les Variable Libraries et les valeurs propres à chaque exécution dans la cellule de paramètres.
Cette structure permet d’appeler un même notebook en toute sécurité depuis de nombreux pipelines, de le réexécuter facilement et de le diagnostiquer facilement. Elle tient aussi les modifications propres à l’environnement hors du code, ce qui permet à l’intégration Git et au déploiement automatisé de fonctionner proprement.
Ce contenu vous a-t-il été utile ?
Que pourrions-nous améliorer ?
Merci — cela m’aide à améliorer Javi Builds.
Continuer à apprendre
- Aide-mémoireSuperviser les pipelines et notebooks FabricSupervisez les pipelines et notebooks Microsoft Fabric avec le Monitoring hub, Workspace Monitoring, la supervision Spark, KQL, les alertes et la télémétrie de capacité afin de rendre observables les échecs et les régressions de performances.Ouvrir l’aide-mémoire
- ArticleActivité Invoke Pipeline de Microsoft Fabric : créer des pipelines modulaires et réutilisablesUtilisez l’activité Invoke Pipeline de Microsoft Fabric pour composer des pipelines parents et enfants paramétrés entre espaces de travail, avec connexions sécurisées et supervision pratique.Lire l’article
Que devrais-je créer ensuite ?
Je développe Javi Builds autour des problèmes concrets rencontrés par les data engineers. Dites-moi quel sujet vous aimeriez voir ensuite.
Restez au courant
Recevez uniquement les nouvelles de Javi Builds qui vous intéressent.
Consultez votre boîte de réception
Je vous ai envoyé un lien de confirmation. Votre abonnement sera actif après confirmation.