Contexte d’exécution NotebookUtils pour Fabric

Utilisez notebookutils.runtime pour lire des informations contextuelles sur la session de notebook en cours. Vous pouvez récupérer des métadonnées telles que le nom du bloc-notes, les détails de l’espace de travail, la configuration par défaut de lakehouse, les indicateurs d’exécution de pipeline et la hiérarchie d’exécution de référence sans modifier d’état.

Utilisez le contexte d’exécution pour :

  • Configuration dynamique : adaptez le comportement du notebook en fonction de l’environnement d’exécution.
  • Logique conditionnelle : logique de branche selon que le notebook s’exécute dans un pipeline ou de manière interactive.
  • Débogage et surveillance : incluez les propriétés de contexte dans la sortie du journal et corrélez les exécutions associées.
  • Pistes d’audit : capturez les métadonnées d’exécution pour le suivi de conformité et de traçabilité.

Note

Le contexte d’exécution est disponible dans les notebooks Python, PySpark, Scala et R. Le contexte est en lecture seule : vous ne pouvez pas modifier les propriétés retournées par notebookutils.runtime.context. Certaines propriétés sont uniquement renseignées dans des contextes spécifiques, tels que des exécutions de référence ou des exécutions de pipeline, et peuvent retourner null ou des valeurs vides sinon.

Afficher le contexte de session

Utilisez notebookutils.runtime.context pour afficher des informations de contexte pour la session en cours, y compris le nom du bloc-notes, le lakehouse par défaut, les informations de l'espace de travail et si la session s'exécute dans un pipeline.

notebookutils.runtime.context

Le tableau suivant décrit les propriétés disponibles.

Propriété Catégorie Description Disponibilité
currentNotebookName Chaîne Nom du bloc-notes actuel. Tous les contextes
currentNotebookId Chaîne ID unique du bloc-notes actuel. Tous les contextes
currentWorkspaceName Chaîne Nom de l’espace de travail actuel. Tous les contextes
currentWorkspaceId Chaîne ID de l’espace de travail actuel. Tous les contextes
defaultLakehouseName Chaîne Nom d'affichage de la lakehouse par défaut, s'il est défini. Quand le lakehouse par défaut est raccordé
defaultLakehouseId Chaîne ID du lakehouse par défaut, s’il est défini. Quand le lakehouse par défaut est raccordé
defaultLakehouseWorkspaceName Chaîne Nom de l’espace de travail du lakehouse par défaut, s’il est défini. Quand le lakehouse par défaut est raccordé
defaultLakehouseWorkspaceId Chaîne ID d’espace de travail de la lakehouse par défaut, s’il est défini. Quand le lakehouse par défaut est raccordé
currentRunId Chaîne Dans une exécution de référence, l’ID d’exécution actuel. Exécutions de référence uniquement
parentRunId Chaîne Dans une exécution de référence avec des exécutions imbriquées, cet ID est l’ID d’exécution parent. Exécutions de référence imbriquées uniquement
rootRunId Chaîne Dans une exécution de référence avec des exécutions imbriquées, cet ID est l’ID d’exécution racine. Exécutions de référence imbriquées uniquement
isForPipeline Booléen Indique si l’exécution concerne un pipeline. Tous les contextes
isForInteractive Booléen Indique si l’exécution est une session interactive. Tous les contextes
isReferenceRun Booléen Indique si l’exécution actuelle est une exécution de référence. Tous les contextes
referenceTreePath Chaîne La structure d’arborescence des exécutions de référence imbriquées, utilisée uniquement pour la hiérarchie des instantanés dans la page de surveillance L2. Exécutions de référence imbriquées uniquement
rootNotebookId Chaîne ID du bloc-notes racine dans une exécution de référence. Exécutions de référence uniquement
rootNotebookName Chaîne Nom du bloc-notes racine dans le cadre d'une exécution de référence. Exécutions de référence uniquement
rootWorkspaceId Chaîne ID d’espace de travail du bloc-notes racine dans une exécution de référence. Exécutions de référence uniquement
rootWorkspaceName Chaîne Nom de l’espace de travail du bloc-notes racine dans une exécution de référence. Exécutions de référence uniquement
activityId Chaîne ID de travail Livy pour l’activité actuelle. Tous les contextes
hcReplId Chaîne L'ID REPL en mode haute concurrence. Mode de haute concurrence uniquement
clusterId Chaîne Identité du cluster Synapse Spark. Tous les contextes
poolName Chaîne Nom du pool Spark utilisé. Tous les contextes
environmentId Chaîne ID d’environnement où le travail est en cours d’exécution. Tous les contextes
environmentWorkspaceId Chaîne L'ID de l’espace de travail de l’environnement. Tous les contextes
userId Chaîne ID d’utilisateur de l’utilisateur actuel. Tous les contextes
userName Chaîne Nom d’utilisateur de l’utilisateur actuel. Tous les contextes
currentKernel Chaîne Nom du noyau de notebook actuel. Notebook Python uniquement
productType Chaîne Identificateur de type de produit (par exemple, Fabric). Tous les contextes

Exemples d’utilisation

Accéder aux informations de contexte de base

Cachez l’objet de contexte lorsque vous devez lire plusieurs propriétés.

context = notebookutils.runtime.context

print(f"Notebook: {context['currentNotebookName']}")
print(f"Workspace: {context['currentWorkspaceName']}")
print(f"Lakehouse: {context['defaultLakehouseName'] or 'None'}")

Vérifier le pipeline et l’exécution interactive

Utilisez le drapeau isForPipeline pour brancher la logique en fonction du mode d’exécution. Par exemple, vous pouvez appliquer une gestion des erreurs plus stricte dans les exécutions du pipeline.

context = notebookutils.runtime.context

if context['isForPipeline']:
    print("Pipeline mode: Strict error handling")
    error_handling = "strict"
    max_retries = 3
elif context['isReferenceRun']:
    print("Running as a referenced notebook")
    error_handling = "strict"
    max_retries = 2
else:
    print("Interactive mode: Lenient error handling")
    error_handling = "lenient"
    max_retries = 1

Conseil / Astuce

Utilisez isForPipeline et isReferenceRun ensemble pour implémenter une branche tridirectionnelle dans divers contextes d'exécution. Ce modèle vous permet de personnaliser les nombres de nouvelles tentatives, la journalisation détaillée et les stratégies de gestion des erreurs. Pour les charges de travail de production, les exécutions de pipeline et de référence nécessitent généralement une gestion des erreurs plus stricte que les sessions interactives.

Inspecter la hiérarchie d’exécution de référence

Lorsqu’un notebook s’exécute dans le cadre d’une exécution de run de référence imbriquée, vous pouvez tracer la hiérarchie complète depuis l’exécution actuelle jusqu’à la racine :

context = notebookutils.runtime.context

if context['isReferenceRun']:
    print("Reference Run Context:")
    print(f"  Current Run ID: {context['currentRunId']}")
    print(f"  Parent Run ID: {context['parentRunId']}")
    print(f"  Root Run ID: {context['rootRunId']}")
    print(f"  Root Notebook: {context['rootNotebookName']}")
else:
    print("Not a reference run")

Inclure le contexte dans la journalisation

Enrichir les messages de journal avec le contexte d’exécution pour faciliter le débogage et la surveillance :

context = notebookutils.runtime.context

run_id = context.get("currentRunId") or "interactive"
log_prefix = (
    f"[{context['currentWorkspaceName']}/{context['currentNotebookName']}]"
    f" run={run_id}"
)

print(f"{log_prefix} Processing started")
  • Last updated on