Créer, développer et gérer des notebooks Synapse

Un notebook dans Azure Synapse Analytics (un notebook Synapse) est une interface web permettant de créer des fichiers contenant du code, des visualisations et du texte descriptif dynamiques. Les notebooks constituent un bon endroit où valider des idées et effectuer des expérimentations rapides pour extraire des insights de vos données. Les notebooks sont également largement utilisés pour la préparation et la visualisation de données, le Machine Learning et d’autres scénarios en lien avec le Big Data.

Avec un notebook Synapse, vous pouvez :

• Commencer à travailler sans le moindre effort de configuration.
• Aider à sécuriser les données avec des fonctionnalités de sécurité d’entreprise intégrées.
• Analyser des données dans des formats bruts (comme CSV, TXT et JSON), des formats de fichiers traités (comme Parquet, Delta Lake et ORC) et des fichiers de données tabulaires SQL sur Spark et SQL.
• Être productif grâce à des fonctionnalités de création améliorées et à la visualisation de données intégrée.

Cet article explique comment utiliser des notebooks dans Synapse Studio.

Créer un notebook

Vous pouvez créer un notebook ou en importer un dans un espace de travail Synapse à partir de l’Explorateur d’objets. Sélectionnez le menu Développer. Cliquez sur le bouton +, puis Notebook ou cliquez avec le bouton droit sur Notebooks, puis sélectionnez Nouveau notebook ou Importer. Les notebooks Synapse reconnaissent les fichiers IPYNB Jupyter Notebook standard.

Développer des notebooks

Les notebooks sont constitués de cellules qui sont des blocs individuels de code ou de texte que vous pouvez exécuter de façon indépendante ou en tant que groupe.

Les sections suivantes décrivent les opérations de développement de notebooks :

• Ajouter une cellule
• Définir un langage principal
• Utiliser plusieurs langages
• Utiliser des tables temporaires pour référencer des données dans plusieurs langages
• Utiliser IntelliSense de style IDE
• Utiliser des extraits de code
• Mettre en forme des cellules de texte à l’aide des boutons de barre d’outils
• Annuler ou rétablir une opération de cellule
• Commenter une cellule de code
• Déplacer une cellule
• Copier une cellule
• Supprimer une cellule
• Réduire l’entrée de cellule
• Réduire la sortie de cellule
• Utiliser une structure de notebook

Remarque

Dans les notebooks, une instance SparkSession est créée automatiquement pour vous et stockée dans une variable appelée spark. Il existe également une variable pour SparkContext appelée sc. Les utilisateurs peuvent accéder directement à ces variables, mais ne doivent pas modifier leurs valeurs.

Ajouter une cellule

Il existe plusieurs façons d’ajouter une cellule à un notebook :

• Placez le curseur sur l’espace entre deux cellules et sélectionnez Code ou Démarque.

  

• Utilisez les touches de raccourci en mode de commande. Sélectionnez la touche A pour insérer une cellule au-dessus de la cellule active. Sélectionnez la touche B pour insérer une cellule en dessous de la cellule active.

Définir un langage principal

Les notebooks Synapse prennent en charge quatre langages Apache Spark :

• PySpark (Python)
• Spark (Scala)
• Spark SQL
• .NET Spark (C#)
• SparkR (R)

Vous pouvez définir le langage principal des nouvelles cellules ajoutées dans la liste déroulante Langage de la barre de commandes supérieure.

Utiliser plusieurs langages

Vous pouvez utiliser plusieurs langages dans un même bloc-notes en spécifiant la commande magic du langage approprié au début d’une cellule. Le tableau suivant répertorie les commandes magic pour basculer les langages des cellules.

Commande magic	Langage	Description
%%pyspark	Python	Exécuter une requête Python sur SparkContext.
%%spark	Scala	Exécuter une requête Scala sur SparkContext.
%%sql	Spark SQL	Exécuter une requête Spark SQL sur SparkContext.
%%csharp	.NET pour Spark C#	Exécuter une requête .NET pour Spark C# sur SparkContext.
%%sparkr	R	Exécuter une requête R sur SparkContext.

L’image suivante illustre la façon d’écrire une requête PySpark à l’aide de la commande magic %%pyspark, ou une requête Spark SQL à l’aide de la commande magic %%sql dans un notebook Spark (Scala). Le langage principal du notebook est défini sur PySpark.

Utiliser des tables temporaires pour référencer des données dans plusieurs langages

Vous ne pouvez pas référencer des données ou variables directement dans différents langages dans un notebook Synapse. Dans Spark, vous pouvez référencer une table temporaire dans plusieurs langages. Voici un exemple illustrant comment lire un DataFrame Scala dans PySpark et Spark SQL à l’aide d’une table temporaire Spark en guise de solution de contournement :

1. Dans la cellule 1, lire un DataFrame à partir du connecteur de pool SQL en utilisant Scala, puis créer une table temporaire :

   %%spark
   val scalaDataFrame = spark.read.sqlanalytics("mySQLPoolDatabase.dbo.mySQLPoolTable")
   scalaDataFrame.createOrReplaceTempView( "mydataframetable" )
   

2. Dans la cellule 2, interroger les données en utilisant Spark SQL :

   %%sql
   SELECT * FROM mydataframetable
   

3. Dans la cellule 3, utiliser les données dans PySpark :

   %%pyspark
   myNewPythonDataFrame = spark.sql("SELECT * FROM mydataframetable")
   

Utiliser IntelliSense de style IDE

Les notebooks Synapse sont intégrés à l’éditeur Monaco pour doter l’éditeur de cellule de la fonctionnalité IntelliSense (de style IDE). Les fonctionnalités de mise en évidence de la syntaxe, de marqueur d’erreurs et de complétion automatique du code vous aident à écrire le code et à identifier les problèmes plus rapidement.

Les fonctionnalités IntelliSense sont à des niveaux de maturité différents pour les différents langages. Utilisez le tableau suivant pour voir ce qui est pris en charge.

Languages	Mise en surbrillance de la syntaxe	Marqueur des erreurs de syntaxe	Complétion de code de syntaxe	Complétion de code variable	Complétion de code de fonction système	Complétion de code de fonction utilisateur	Retrait intelligent	Pliage de code
PySpark (Python)	Oui	Oui	Oui	Oui	Oui	Oui	Oui	Oui
Spark (Scala)	Oui	Oui	Oui	Oui	Oui	Oui	No	Oui
Spark SQL	Oui	Oui	Oui	Oui	Oui	No	Non	Non
.NET pour Spark (C#)	Oui	Oui	Oui	Oui	Oui	Oui	Oui	Oui

Une session Spark active est requise pour tirer parti de la complétion de code de variable, de la complétion de code de fonction système et de la complétion de code de fonction utilisateur pour .NET pour Spark (C#).

Utiliser des extraits de code

Les notebooks Synapse fournissent des extraits de code qui facilitent l’entrée des modèles de code couramment utilisés. Ces modèles incluent la configuration de votre session Spark, la lecture de données en tant que DataFrame Spark et le dessin de graphiques à l’aide de Matplotlib.

Les extraits de code apparaissent dans Touches de raccourci d’IntelliSense de style IDE en combinaison avec d’autres suggestions. Le contenu des extraits de code s’aligne avec le langage des cellules de code. Vous pouvez voir les extraits de code disponibles en entrant extrait ou n’importe quel mot clé qui apparaît dans le titre de l’extrait dans l’éditeur de cellule de code. Par exemple, en entrant lire, vous pouvez voir la liste des extraits pour lire des données à partir de différentes sources de données.

Mettre en forme des cellules de texte à l’aide des boutons de barre d’outils

Vous pouvez utiliser les boutons de mise en forme dans la barre d’outils des cellules de texte pour effectuer des actions Markdown courantes. Ces actions incluent la mise en gras du texte, la mise en italique du texte, la création de paragraphes et de titres par le biais d’un menu déroulant, l’insertion de code, l’insertion d’une liste non ordonnée, l’insertion d’une liste ordonnée, l’insertion d’un lien hypertexte et l’insertion d’une image à partir d’une URL.

Annuler ou rétablir une opération de cellule

Pour révoquer les opérations de cellule les plus récentes, sélectionnez le bouton Annuler ou Rétablir, ou sélectionnez la touche Z ou Maj+Z. Actuellement, vous pouvez annuler ou rétablir jusqu’à dix opérations de cellule.

Les opérations de cellule prises en charge sont notamment :

• Insérer ou supprimer une cellule. Vous pouvez révoquer des opérations de suppression en sélectionnant Annuler. Cette action conserve le contenu du texte ainsi que la cellule.
• Réorganiser des cellules.
• Activer ou désactiver une cellule de paramètre.
• Effectuer une conversion entre une cellule de code et une cellule Markdown.

Remarque

Vous ne pouvez pas annuler des opérations de texte ou commenter des opérations dans une cellule.

Commenter une cellule de code

1. Sélectionnez le bouton Commentaires dans la barre d’outils du notebook pour ouvrir le volet Commentaires.

   

2. Sélectionnez le code dans la cellule de code, cliquez sur Nouveau dans le volet Commentaires, ajoutez des commentaires, puis sélectionnez le bouton Poster un commentaire.

   

3. Si nécessaire, vous pouvez effectuer les actions Modifier le commentaire, Résoudre le thread et Supprimer le thread en sélectionnant les points de suspension (...) Plus en regard de votre commentaire.

   

Déplacer une cellule

Pour déplacer une cellule, sélectionnez le côté gauche de la cellule et faites glisser la cellule vers la position souhaitée.

Copier une cellule

Pour copier une cellule, vous devez d’abord créer une cellule, puis sélectionner tout le texte de votre cellule d’origine, copier le texte et le coller dans la nouvelle cellule. Lorsque votre cellule est en mode édition, les raccourcis clavier traditionnels pour sélectionner tout le texte sont limités à la cellule.

Conseil

Les notebooks Synapse fournissent également des snippits de modèles de code couramment utilisés.

Supprimer une cellule

Pour supprimer une cellule, sélectionnez le bouton Supprimer à droite de la cellule.

Vous pouvez également utiliser des touches de raccourci en mode de commande. Sélectionnez Maj+D pour supprimer la cellule active.

Réduire l’entrée de cellule

Pour réduire l’entrée de la cellule actuelle, sélectionnez les points de suspension (...) Plus de commandes dans la barre d’outils de la cellule, puis Masquer l’entrée. Pour développer l’entrée, sélectionnez Afficher l’entrée quand la cellule est réduite.

Réduire la sortie de cellule

Pour réduire la sortie de la cellule actuelle, sélectionnez les points de suspension (...) Plus de commandes dans la barre d’outils de la cellule, puis Masquer la sortie. Pour développer la sortie, sélectionnez Afficher la sortie quand la sortie de la cellule est réduite.

Utiliser une structure de notebook

La structure (table des matières) présente le premier en-tête Markdown d’une cellule Markdown dans une barre latérale pour une navigation rapide. Vous pouvez redimensionner et réduire la barre latérale de structure pour qu’elle s’adapte au mieux à l’écran. Pour ouvrir ou masquer la barre latérale, sélectionnez le bouton Structure dans la barre de commandes du notebook.

Exécuter un notebook

Vous pouvez exécuter les cellules de code dans votre bloc-notes individuellement ou toutes en même temps. L’état et la progression de chaque cellule apparaissent dans le notebook.

Remarque

La suppression d’un notebook n’annule pas automatiquement les travaux en cours d’exécution. Si vous avez besoin d’annuler un travail, accédez au hub Surveiller et annulez-le manuellement.

Exécuter une cellule

Il existe plusieurs façons d’exécuter le code figurant dans une cellule :

• Pointez sur la cellule que vous souhaitez exécuter, puis sélectionnez le bouton Exécuter la cellule, ou sélectionnez Ctrl+Entrée.

  

• Utilisez les touches de raccourci en mode de commande. Sélectionnez Maj+Entrée pour exécuter la cellule active et sélectionner la cellule en dessous. Sélectionnez Alt+Entrée pour exécuter la cellule active et insérer une nouvelle cellule en dessous.

Exécuter toutes les cellules

Pour exécuter toutes les cellules du notebook actuel dans l’ordre, sélectionnez le bouton Tout exécuter.

Exécuter toutes les cellules au-dessus ou en dessous

Pour exécuter dans l’ordre toutes les cellules au-dessus de la cellule actuelle, développez la liste déroulante du bouton Tout exécuter, puis sélectionnez Exécuter les cellules au-dessus. Sélectionnez Exécuter les cellules en dessous pour exécuter dans l’ordre toutes les cellules sous la cellule active.

Annuler toutes les cellules en cours d’exécution

Pour annuler les cellules en cours d’exécution ou les cellules dans la file d’attente, sélectionnez le bouton Tout annuler.

Référencer un notebook

Pour référencer un autre notebook dans le contexte du notebook actuel, utilisez la commande magic %run <notebook path>. Toutes les variables définies dans le notebook de référence sont disponibles dans le notebook actuel.

Voici un exemple :

%run /<path>/Notebook1 { "parameterInt": 1, "parameterFloat": 2.5, "parameterBool": true, "parameterString": "abc" }

La référence de notebook fonctionne à la fois en mode interactif et dans les pipelines.

La commande magic %run présente les limitations suivantes :

• La commande prend en charge les appels imbriqués, mais pas les appels récursifs.
• La commande prend en charge le passage d’un chemin d’accès absolu ou d’un nom de notebook uniquement en tant que paramètre. Elle ne prend pas en charge les chemins relatifs.
• La commande prend actuellement en charge uniquement quatre types de valeur de paramètre : int, float, bool et string. Elle ne prend pas en charge les opérations de remplacement des variables.
• Les notebooks référencés doivent être publiés. Vous devez publier les notebooks pour les référencer, sauf si vous sélectionnez l’option permettant d’activer une référence de notebook non publié. Synapse Studio ne reconnaît pas les notebooks non publiés du référentiel Git.
• Les notebooks référencés ne prennent pas en charge les profondeurs d’instruction supérieures à cinq.

Utiliser l’Explorateur de variables

Un notebook Synapse fournit un explorateur de variables intégré sous la forme d’une table qui répertorie les variables dans la session Spark actuelle pour les cellules PySpark (Python). La table inclut des colonnes pour le nom, le type, la longueur et la valeur de la variable. D’autres variables apparaissent automatiquement à mesure qu’elles sont définies dans les cellules de code. La sélection de chaque en-tête de colonne permet de trier les variables de la table.

Pour ouvrir ou masquer l’Explorateur de variables, sélectionnez le bouton Variables dans la barre de commandes du notebook.

Remarque

L’Explorateur de variables prend uniquement en charge Python.

Utiliser l’indicateur d’état de cellule

Un état pas à pas d’une exécution de cellule apparaît sous la cellule pour vous aider à voir sa progression actuelle. Une fois l’exécution de la cellule terminée, un récapitulatif avec la durée totale et l’heure de fin s’affiche, et reste disponible pour référence ultérieure.

Utiliser l’indicateur de progression Spark

Un notebook Synapse est entièrement basé sur Spark. Les cellules de code s’exécutent sur le pool Apache Spark serverless à distance. Un indicateur de progression du travail Spark avec une barre de progression en temps réel vous permet de comprendre l’état d’exécution du travail.

Le nombre de tâches pour chaque travail ou phase vous aide à identifier le niveau parallèle de votre travail Spark. Vous pouvez également explorer plus en profondeur l’interface utilisateur Spark d’un travail (ou phase) spécifique en sélectionnant le lien sur le nom du travail (ou de la phase).

Configurer une session Spark

Dans le volet Configurer la session, que vous pouvez trouver en sélectionnant l’icône d’engrenage en haut du notebook, vous pouvez spécifier la durée du délai d’attente, le nombre d’exécuteurs et la taille des exécuteurs à donner à la session Spark en cours. Redémarrez la session Spark pour que les modifications apportées à la configuration prennent effet. Toutes les variables du bloc-notes mises en cache sont effacées.

Vous pouvez également créer une configuration à partir de la configuration Apache Spark ou sélectionner une configuration existante. Pour plus d’informations, consultez Gérer la configuration Apache Spark.

Commande magic pour la configuration d’une session Spark

Vous pouvez également spécifier des paramètres de session Spark via une commande magic %%configure. Pour que les paramètres prennent effet, redémarrez la session Spark.

Nous vous recommandons d’exécuter %%configure au début de votre notebook. Voici un exemple. Pour obtenir la liste complète des paramètres valides, consultez les informations Livy sur GitHub.

%%configure
{
    //You can get a list of valid parameters to configure the session from https://github.com/cloudera/livy#request-body.
    "driverMemory":"28g", // Recommended values: ["28g", "56g", "112g", "224g", "400g", "472g"]
    "driverCores":4, // Recommended values: [4, 8, 16, 32, 64, 80]
    "executorMemory":"28g",
    "executorCores":4, 
    "jars":["abfs[s]://<file_system>@<account_name>.dfs.core.windows.net/<path>/myjar.jar","wasb[s]://<containername>@<accountname>.blob.core.windows.net/<path>/myjar1.jar"],
    "conf":{
    //Example of a standard Spark property. To find more available properties, go to https://spark.apache.org/docs/latest/configuration.html#application-properties.
        "spark.driver.maxResultSize":"10g",
    //Example of a customized property. You can specify the count of lines that Spark SQL returns by configuring "livy.rsc.sql.num-rows".
        "livy.rsc.sql.num-rows":"3000" 
    }
}

Voici quelques points à prendre en compte pour la commande magic %%configure :

• Nous vous recommandons d’utiliser la même valeur pour driverMemory et executorMemory dans %%configure. Nous vous recommandons également d’affecter la même valeur à driverCores et executorCores.
• Vous pouvez utiliser %%configure dans les pipelines Synapse, mais si vous ne le définissez pas dans la première cellule de code, l’exécution du pipeline échoue, car elle ne peut pas redémarrer la session.
• La commande %%configure utilisée dans mssparkutils.notebook.run est ignorée, mais la commande utilisée dans %run <notebook> continue à s’exécuter.
• Vous devez utiliser les propriétés de configuration Spark standard dans le corps "conf". Nous ne prenons pas en charge les références de niveau supérieur pour les propriétés de configuration Spark.
• Certaines propriétés Spark spéciales ne prendront pas effet dans le corps "conf", notamment "spark.driver.cores", "spark.executor.cores", "spark.driver.memory", "spark.executor.memory" et "spark.executor.instances".

Configuration de session paramétrisée à partir d’un pipeline

Vous pouvez utiliser la configuration de session paramétrisée pour remplacer des valeurs dans la commande magic %%configure par des paramètres d’exécution de pipeline (activité notebook de). Lorsque vous préparez une cellule de code %%configure, vous pouvez remplacer les valeurs par défaut en utilisant un objet comme suit :

{
      "activityParameterName": "paramterNameInPipelineNotebookActivity",
      "defaultValue": "defaultValueIfNoParamterFromPipelineNotebookActivity"
} 

L’exemple suivant montre les valeurs par défaut 4 et "2000", qui sont également configurables :

%%configure  

{ 
    "driverCores": 
    { 
        "activityParameterName": "driverCoresFromNotebookActivity", 
        "defaultValue": 4 
    }, 
    "conf": 
    { 
        "livy.rsc.sql.num-rows": 
        { 
            "activityParameterName": "rows", 
            "defaultValue": "2000" 
        } 
    } 
} 

Le notebook utilise la valeur par défaut si vous l’exécutez en mode interactif directement ou si l’activité de notebook de pipeline ne fournit aucun paramètre correspondant à "activityParameterName".

Pendant le mode d’exécution du pipeline, vous pouvez utiliser l’onglet Paramètres pour configurer les paramètres d’une activité de notebook de pipeline.

Si vous voulez changer la configuration de session, le nom du paramètre d’activité de notebook du pipeline doit être identique à activityParameterName dans le notebook. Dans cet exemple, lors d’une exécution de pipeline, 8 remplace driverCores dans %%configure, et 4000 remplace livy.rsc.sql.num-rows.

Si une exécution de pipeline échoue après l’utilisation de la commande magic %%configure, vous pouvez obtenir plus d’informations sur les erreurs en exécutant la cellule magic %%configure dans le mode interactif du notebook.

Importer des données dans un bloc-notes

Vous pouvez charger des données à partir d’Azure Data Lake Storage Gen2, de Stockage Blob Azure et de pools SQL, comme illustré dans les exemples de code suivants.

Lire un fichier CSV à partir d’Azure Data Lake Storage Gen2 en tant que DataFrame Spark

from pyspark.sql import SparkSession
from pyspark.sql.types import *
account_name = "Your account name"
container_name = "Your container name"
relative_path = "Your path"
adls_path = 'abfss://%s@%s.dfs.core.windows.net/%s' % (container_name, account_name, relative_path)

df1 = spark.read.option('header', 'true') \
                .option('delimiter', ',') \
                .csv(adls_path + '/Testfile.csv')

Lire un fichier CSV à partir de Stockage Blob Azure en tant que DataFrame Spark

from pyspark.sql import SparkSession

# Azure storage access info
blob_account_name = 'Your account name' # replace with your blob name
blob_container_name = 'Your container name' # replace with your container name
blob_relative_path = 'Your path' # replace with your relative folder path
linked_service_name = 'Your linked service name' # replace with your linked service name

blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds(linked_service_name)

# Allow Spark to access from Azure Blob Storage remotely

wasb_path = 'wasbs://%s@%s.blob.core.windows.net/%s' % (blob_container_name, blob_account_name, blob_relative_path)

spark.conf.set('fs.azure.sas.%s.%s.blob.core.windows.net' % (blob_container_name, blob_account_name), blob_sas_token)
print('Remote blob path: ' + wasb_path)

df = spark.read.option("header", "true") \
            .option("delimiter","|") \
            .schema(schema) \
            .csv(wasbs_path)

Lire des données à partir du compte de stockage principal

Vous pouvez accéder aux données directement dans le compte de stockage principal. Il n’est pas nécessaire de fournir les clés secrètes. Dans l’Explorateur de données, cliquez avec le bouton droit sur un fichier et sélectionnez Nouveau notebook pour afficher un nouveau notebook avec un extracteur de données généré automatiquement.

Utiliser des widgets IPython

Les widgets sont des objets Python avec événements qui ont une représentation dans le navigateur, souvent en tant que contrôle comme un curseur ou une zone de texte. Les widgets IPython fonctionnent uniquement dans les environnements Python. Ils ne sont actuellement pas pris en charge dans d’autres langages (par exemple, Scala, SQL ou C#).

Étapes d’utilisation des widgets IPython

1. Importez le module ipywidgets pour utiliser l’infrastructure Jupyter Widgets :

   import ipywidgets as widgets
   

2. Utilisez la fonction display de niveau supérieur pour afficher un widget, ou laissez une expression de type widget sur la dernière ligne de la cellule de code :

   slider = widgets.IntSlider()
   display(slider)
   

   slider = widgets.IntSlider()
   slider
   

3. Exécutez la cellule. Le widget apparaît dans la zone de sortie.

   

Vous pouvez utiliser plusieurs appels display() pour afficher la même instance de widget plusieurs fois, mais ils restent synchronisés les uns avec les autres :

slider = widgets.IntSlider()
display(slider)
display(slider)

Pour afficher deux widgets indépendants l’un de l’autre, créez deux instances de widget :

slider1 = widgets.IntSlider()
slider2 = widgets.IntSlider()
display(slider1)
display(slider2)

Widgets pris en charge

Type de widget	Widgets
Numérique	IntSlider, FloatSlider, FloatLogSlider, IntRangeSlider, FloatRangeSlider, IntProgress, FloatProgress, BoundedIntText, BoundedFloatText, IntText, FloatText
Boolean	ToggleButton, Checkbox, Valid
Sélection	Dropdown, RadioButtons, Select, SelectionSlider, SelectionRangeSlider, ToggleButtons, SelectMultiple
Chaîne	Text, Text area, Combobox, Password, Label, HTML, HTML Math, Image, Button
Lecture (animation)	Date picker, Color picker, Controller
Conteneur/disposition	Box, HBox, VBox, GridBox, Accordion, Tabs, Stacked

Limitations connues

• Le tableau suivant répertorie les widgets qui ne sont actuellement pas pris en charge, ainsi que des solutions de contournement :

  Fonctionnalités	Solution de contournement
  Widget Output	Vous pouvez utiliser la fonction print() pour écrire du texte dans stdout.
  widgets.jslink()	Vous pouvez utiliser la fonction widgets.link() pour lier deux widgets similaires.
  Widget FileUpload	Aucune information n’est disponible.

• La fonction globale display fournie par Azure Synapse Analytics ne prend pas en charge l’affichage de plusieurs widgets dans un appel unique (autrement dit, display(a, b)). Ce comportement diffère de celui de la fonction display IPython.

• Si vous fermez un notebook qui contient un widget IPython, vous ne pouvez pas voir le widget ni interagir avec lui tant que vous ne réexécutez pas la cellule correspondante.

Enregistrer des blocs-notes

Vous pouvez enregistrer un seul notebook ou tous les notebooks dans votre espace de travail :

• Pour enregistrer les modifications apportées à un seul notebook, sélectionnez le bouton Publier dans la barre de commandes du notebook.

  

• Pour enregistrer tous les blocs-notes dans votre espace de travail, sélectionnez le bouton Publier tout dans la barre de commandes de l’espace de travail.

  

Dans le volet Propriétés du notebook, vous pouvez éventuellement configurer l’inclusion de la sortie de cellule lors de l’enregistrement.

Utiliser des commandes magic

Vous pouvez utiliser des commandes magic Jupyter connues dans les notebooks Synapse. Consultez les listes suivantes de commandes magic actuellement disponibles. Parlez-nous de vos cas d’usage sur GitHub pour nous permettre de continuer à créer des commandes magic supplémentaires afin de répondre à vos besoins.

Remarque

Seules les commandes magic suivantes sont prises en charge dans les pipelines Synapse : %%pyspark, %%spark, %%csharp, %%sql.

Commandes magic disponibles pour les lignes :

%lsmagic, %time, %timeit, %history, %run, %load

Commandes magic disponibles pour les cellules :

%%time, %%timeit, %%capture, %%writefile, %%sql, %%pyspark, %%spark, %%csharp, %%html, %%configure

Référencer un notebook non publié

Le référencement d’un notebook non publié est utile lorsque vous souhaitez déboguer localement. Lorsque vous activez cette fonctionnalité, une exécution de notebook extrait le contenu actuel à partir du cache web. Si vous exécutez une cellule qui inclut une instruction de notebook de référence, vous référencez les notebooks de présentation dans le navigateur de notebooks actuel au lieu d’une version enregistrée dans un cluster. D’autres notebooks peuvent référencer les modifications dans votre éditeur de notebook sans avoir à publier (mode Live) ou commiter (mode Git) les modifications. En adoptant cette approche, vous pouvez empêcher la pollution des bibliothèques courantes pendant le processus de développement ou de débogage.

Vous pouvez activer le référencement d’un notebook non publié en cochant la case appropriée dans le volet Propriétés.

Le tableau suivant compare les cas. Bien que %run et mssparkutils.notebook.run aient ici le même comportement, la table utilise %run en guise d’exemple.

Case	Disable	Activer
Mode Live
Nb1 (publié) %run Nb1	Exécuter la version publiée de Nb1	Exécuter la version publiée de Nb1
Nb1 (nouveau) %run Nb1	Error	Exécuter le nouveau Nb1
Nb1 (précédemment publié, modifié) %run Nb1	Exécuter la version publiée de Nb1	Exécuter la version modifiée de Nb1
Mode Git
Nb1 (publié) %run Nb1	Exécuter la version publiée de Nb1	Exécuter la version publiée de Nb1
Nb1 (nouveau) %run Nb1	Error	Exécuter le nouveau Nb1
Nb1 (non publié, commité) %run Nb1	Error	Exécuter le Nb1 validé
Nb1 (précédemment publié, commité) %run Nb1	Exécuter la version publiée de Nb1	Exécuter la version validée de Nb1
Nb1 (précédemment publié, nouveau dans la branche actuelle) %run Nb1	Exécuter la version publiée de Nb1	Exécuter le nouveau Nb1
Nb1 (non publié, précédemment commité, modifié) %run Nb1	Error	Exécuter la version modifiée de Nb1
Nb1 (précédemment publié et commité, modifié) %run Nb1	Exécuter la version publiée de Nb1	Exécuter la version modifiée de Nb1

En résumé :

• Si vous désactivez le référencement d’un notebook non publié, exécutez toujours la version publiée.
• Si vous activez le référencement d’un notebook non publié, l’exécution de référence adopte toujours la version actuelle du notebook qui s’affiche dans l’expérience utilisateur du notebook.

Gérer les sessions actives

Vous pouvez réutiliser vos sessions de notebook sans avoir à en démarrer de nouvelles. Dans les notebooks Synapse, vous pouvez gérer vos sessions actives dans une liste unique. Pour ouvrir la liste, sélectionnez les points de suspension (...), puis Gérer les sessions.

Le volet Sessions actives répertorie toutes les sessions de l’espace de travail actuel que vous avez démarrées à partir d’un notebook. La liste affiche les informations de session et les notebooks correspondants. Les actions Détacher du notebook, Arrêter la session et Voir dans la supervision sont disponibles ici. En outre, vous pouvez connecter votre notebook sélectionné à une session active qui a démarré à partir d’un autre notebook. La session est alors détachée du notebook précédent (s’il n’est pas inactif) et attachée au notebook actuel.

Utiliser des journaux Python dans un notebook

Vous pouvez trouver des journaux Python et définir différents niveaux de journaux et formats en suivant l’exemple de code ci-dessous :

import logging

# Customize the logging format for all loggers
FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
formatter = logging.Formatter(fmt=FORMAT)
for handler in logging.getLogger().handlers:
    handler.setFormatter(formatter)

# Customize the log level for all loggers
logging.getLogger().setLevel(logging.INFO)

# Customize the log level for a specific logger
customizedLogger = logging.getLogger('customized')
customizedLogger.setLevel(logging.WARNING)

# Logger that uses the default global log level
defaultLogger = logging.getLogger('default')
defaultLogger.debug("default debug message")
defaultLogger.info("default info message")
defaultLogger.warning("default warning message")
defaultLogger.error("default error message")
defaultLogger.critical("default critical message")

# Logger that uses the customized log level
customizedLogger.debug("customized debug message")
customizedLogger.info("customized info message")
customizedLogger.warning("customized warning message")
customizedLogger.error("customized error message")
customizedLogger.critical("customized critical message")

Afficher l’historique des commandes d’entrée

Les notebooks Synapse prennent en charge la commande magic %history pour imprimer l’historique des commandes d’entrée pour la session active. La commande magic %history est similaire à la commande Jupyter IPython standard, et fonctionne pour plusieurs contextes de langage dans un notebook.

%history [-n] [range [range ...]]

Dans le code précédent, -n correspond au numéro d’exécution d’impression. La valeur range peut être :

• N : imprimer le code de la Nth cellule exécutée.
• M-N : imprimer le code de la Mthà la Nth cellule exécutée.

Par exemple, pour imprimer l’historique des entrées de la première à la deuxième cellule exécutée, utilisez %history -n 1-2.

Intégrer un notebook

Ajouter un notebook à un pipeline

Pour ajouter un notebook à un pipeline existant ou créer un pipeline, sélectionnez le bouton Ajouter au pipeline dans le coin supérieur droit.

Désigner une cellule de paramètre

Pour paramétriser votre notebook, sélectionnez les points de suspension (…) afin d’accéder à des commandes supplémentaires dans la barre d’outils de la cellule. Sélectionnez ensuite Activer/désactiver la cellule de paramètre pour désigner la cellule comme cellule de paramètre.

Azure Data Factory recherche la cellule de paramètre et la traite comme cellule par défaut pour les paramètres transmis au moment de l’exécution. Le moteur d’exécution ajoute une nouvelle cellule sous la cellule de paramètre avec des paramètres d’entrée en vue de remplacer les valeurs par défaut.

Attribuer des valeurs de paramètres à partir d’un pipeline

Une fois que vous avez créé un notebook avec des paramètres, vous pouvez l’exécuter à partir d’un pipeline au moyen de l’activité de notebook Synapse. Après avoir ajouté l’activité à votre canevas de pipeline, vous pouvez définir les valeurs des paramètres dans la section Paramètres de base de l’onglet Paramètres.

Lors de l’attribution des valeurs de paramètres, vous pouvez utiliser le langage d’expression du pipeline ou des variables système.

Utiliser des touches de raccourci

Tout comme les notebooks Jupyter, les notebooks Synapse disposent d’une interface utilisateur modale. Le clavier effectue des actions différentes en fonction du mode dans lequel se trouve la cellule du notebook. Les notebooks Synapse prennent en charge les deux modes suivants pour une cellule de code :

• Mode de commande : une cellule est en mode de commande quand elle n’affiche aucun curseur texte vous invitant à taper. Quand une cellule est en mode de commande, vous pouvez modifier le notebook entier, mais pas taper dans des cellules spécifiques. Entrez en mode de commande en sélectionnant la touche Échap ou en utilisant la souris pour sélectionner en dehors de la zone de l’éditeur d’une cellule.

  

• Mode édition : lorsqu’une cellule est en mode édition, un curseur de texte vous invite à taper dans la cellule. Entrez en mode édition en sélectionnant la touche Entrée ou en utilisant la souris pour sélectionner la zone de l’éditeur d’une cellule.

  

Touches de raccourci en mode de commande

Action	Raccourci de notebook Synapse
Exécuter la cellule active et sélectionner la cellule en dessous	Maj + Entrée
Exécuter la cellule active et insérer en dessous	Alt + Entrée
Exécuter la cellule active	CTRL+ Enter
Sélectionner la cellule au-dessus	Haut
Sélectionner la cellule en dessous	Descendre
Sélectionner la cellule précédente	K
Sélectionner la cellule suivante	J
Insérer une cellule au-dessus	Un
Insérer une cellule en dessous	B
Supprimer les cellules sélectionnées	Maj + D
Basculer en mode d’édition	Entrez

Touches de raccourci en mode d’édition

Action	Raccourci de notebook Synapse
Déplacer le curseur vers le haut	Haut
Déplacer le curseur vers le bas	Descendre
Annuler	Ctrl+Z
Rétablir	Ctrl+Y
Commenter/Supprimer un commentaire	Ctrl+/
Supprimer le mot précédent	Ctrl+Retour arrière
Supprimer le mot suivant	Ctrl+Suppr
Atteindre le début de la cellule	Ctrl+Origine
Atteindre la fin de la cellule	Ctrl+Fin
Atteindre le mot à gauche	Ctrl+Gauche
Atteindre le mot à droite	Ctrl+Droite
Sélectionner tout	Ctrl+A
Retrait	Ctrl+]
Retrait négatif	Ctrl+[
Passer en mode de commande	Échap

Contenu connexe

• Exemples de notebooks Synapse
• Démarrage rapide : Créer un pool Apache Spark dans Azure Synapse Analytics avec des outils web
• Présentation d’Apache Spark dans Azure Synapse Analytics
• Utiliser .NET pour Apache Spark avec Azure Synapse Analytics
• Documentation .NET pour Apache Spark
• Documentation Azure Synapse Analytics