Creación, desarrollo y mantenimiento de cuadernos de Synapse

Un cuaderno de Azure Synapse Analytics (un cuaderno de Synapse) es una interfaz web que le permite crear archivos que contengan código dinámico, visualizaciones y texto narrativo. Los cuadernos son un buen lugar para validar ideas y aplicar experimentos rápidos para sacar conclusiones a partir de los datos. Los cuadernos también se usan ampliamente en la preparación de datos, la visualización de datos, el aprendizaje automático y otros escenarios de macrodatos.

Con un cuaderno de Synapse, puede hacer lo siguiente:

• Empezar a trabajar sin esfuerzo alguno de configuración.
• Ayude a proteger los datos con características de seguridad empresariales integradas.
• Analice datos en formatos sin procesar (como CSV, TXT y JSON), formatos de archivo procesados (como Parquet, Delta Lake y ORC) y archivos de datos tabulares de SQL en Spark y SQL.
• Ser productivo con funcionalidades de creación mejoradas y visualización de datos integrada.

En este artículo se describe cómo usar cuadernos en Synapse Studio.

Creación de un cuaderno

Puede crear un cuaderno nuevo o importar un cuaderno existente a un área de trabajo de Synapse desde Explorador de objetos. Seleccione el menú Desarrollar. Seleccione el botón + y luego Cuaderno o haga clic con el botón derecho en Cuadernos y, después, seleccione Nuevo cuaderno o Importar. Los cuadernos de Synapse reconocen los archivos IPYNB estándar de Jupyter Notebook.

Desarrollo de cuadernos

Los cuadernos constan de celdas, que son bloques individuales de código o texto que se pueden ejecutar de forma independiente o como grupo.

En las secciones siguientes se describen las operaciones para desarrollar cuadernos:

• Adición de una celda
• Definición del lenguaje principal
• Uso de varios lenguajes
• Usar tablas temporales para hacer referencia a datos entre idiomas
• Usar IntelliSense de estilo IDE
• Uso de fragmentos de código
• Formato de celdas de texto mediante botones de barra de herramientas
• Deshacer o rehacer una operación de celda
• Comentario en una celda de código
• Movimiento de una celda
• Copiar una celda
• Eliminación de una celda
• Contraer entrada de celda
• Contraer salida de celda
• Usar un esquema de cuaderno

Nota:

En los cuadernos, se crea automáticamente una instancia de SparkSession y se almacena en una variable denominada spark. También hay una variable para SparkContext denominada sc. Los usuarios pueden acceder a estas variables directamente, pero no deben cambiar los valores de estas variables.

Agregar una celda

Hay varias maneras de agregar una nueva celda al cuaderno:

• Mantenga el puntero sobre el espacio entre dos celdas y seleccione Código o Markdown.

  

• Use teclas de método abreviado en el modo de comando. Seleccione la tecla A para insertar una celda encima de la celda actual. Seleccione la tecla B para insertar una celda debajo de la celda actual.

Establecer un idioma principal

Los cuadernos de Synapse admiten cuatro lenguajes de Apache Spark:

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

Puede establecer el idioma principal para las celdas recién agregadas desde la lista desplegable Idioma en la barra de comandos superior.

Usar varios idiomas

Para usar varios lenguajes en un cuaderno, puede especificar el comando magic de lenguaje correcto al principio de una celda. En la tabla siguiente se enumeran los comandos magic para cambiar el lenguaje de las celdas.

Comando magic	Idioma	Descripción
%%pyspark	Python	Ejecute una consulta de Python en SparkContext.
%%spark	Scala	Ejecute una consulta de Scala en SparkContext.
%%sql	Spark SQL	Ejecute una consulta de Spark SQL en SparkContext.
%%csharp	.NET para Spark C#	Ejecute una consulta de .NET para Spark C# en SparkContext.
%%sparkr	R	Ejecute una consulta de R en SparkContext.

En la imagen siguiente se muestra un ejemplo de cómo puede escribir una consulta de PySpark mediante el comando magic %%pyspark o una consulta Spark SQL mediante el comando magic de %%sql en un cuaderno de Spark (Scala). El idioma principal del cuaderno se establece en PySpark.

Usar tablas temporales para hacer referencia a datos entre idiomas

No puede hacer referencia a datos ni variables directamente en distintos lenguajes de un cuaderno de Synapse. En Spark, puede hacer referencia a una tabla temporal entre idiomas. Este es un ejemplo de cómo leer un Dataframe de Scala en PySpark y Spark SQL mediante una tabla temporal de Spark como solución alternativa:

1. En la celda 1, lea un DataFrame desde un conector de grupo de SQL mediante Scala y cree una tabla temporal:

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

2. En la celda 2, consulte los datos mediante Spark SQL:

   %%sql
   SELECT * FROM mydataframetable
   

3. En la celda 3, use los datos de PySpark:

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

Usar IntelliSense de estilo IDE

Los cuadernos de Synapse se integran en el editor Monaco para incluir la funcionalidad IntelliSense de estilo IDE en el editor de celdas. Las características de resaltado de sintaxis, marcador de error y finalización automática de código le ayudan a escribir código e identificar problemas más rápido.

Las características de IntelliSense tienen distintos niveles de madurez para distintos lenguajes. Use la siguiente tabla para ver lo que se admite.

Lenguajes	Resaltado de sintaxis	Creador de errores de sintaxis	Finalización de código de sintaxis	Finalización de código de variables	Finalización de código de función del sistema	Finalización de código de funciones del usuario	Sangría inteligente	Plegado de código
PySpark (Python)	Sí	Sí	Sí	Sí	Sí	Sí	Sí	Sí
Spark (Scala)	Sí	Sí	Sí	Sí	Sí	Sí	No	Sí
Spark SQL	Sí	Sí	Sí	Sí	Sí	No	N.º	No
.NET para Spark ( C# )	Sí	Sí	Sí	Sí	Sí	Sí	Sí	Sí

Se requiere una sesión de Spark activa para beneficiarse de la finalización de código variable, la finalización del código de función del sistema y la finalización del código de función de usuario para .NET para Spark (C#).

Usar fragmentos de código

Los cuadernos de Synapse proporcionan fragmentos de código que facilitan la entrada de patrones de código usados habitualmente. Estos patrones incluyen la configuración de la sesión de Spark, la lectura de datos como un Dataframe de Spark y los gráficos de dibujo mediante Matplotlib.

Los fragmentos de código aparecen en teclas de método abreviado de IntelliSense de estilo IDE mezcladas con otras sugerencias. El contenido de los fragmentos de código se alinea con el lenguaje de celda de código. Para ver los fragmentos de código disponibles, escriba fragmento de código o cualquier palabra clave que aparezca en el título del fragmento de código en el editor de celdas de código. Por ejemplo, al escribir leer, puede ver la lista de fragmentos de código para leer datos de varios orígenes de datos.

Formato de celdas de texto mediante botones de barra de herramientas

Puede usar los botones de formato de la barra de herramientas de celda de texto para realizar acciones comunes de Markdown. Estas acciones incluyen hacer negrita de texto, hacer cursiva de texto, crear párrafos y encabezados a través de un menú desplegable, insertar código, insertar una lista desordenada, insertar una lista ordenada, insertar un hipervínculo e insertar una imagen desde una dirección URL.

Deshacer o rehacer una operación de celda

Para revocar las operaciones de celda más recientes, seleccione el botón Deshacer o Rehacer o seleccione la tecla Z o Mayús+Z. Ahora puede deshacer o rehacer hasta 10 operaciones históricas de celda.

Las operaciones de celda admitidas incluyen:

• Insertar o eliminar una celda. Para revocar las operaciones de eliminación, seleccione Deshacer. Esta acción mantiene el contenido del texto junto con la celda.
• Reordenar las celdas.
• Active o desactive una celda de parámetro.
• Convertir entre una celda de código y una celda Markdown.

Nota:

No se pueden deshacer las operaciones de texto ni las operaciones de comentarios en una celda.

Comentario en una celda de código

1. Seleccione el botón Comentarios de la barra de herramientas del cuaderno para abrir el panel de Comentarios.

   

2. Seleccione código en la celda de código, seleccione Nuevo en el panel Comentarios, agregue comentarios y, a continuación, seleccione el botón Publicar comentario.

   

3. Si es necesario, puede realizar Editar comentario, Resolver subproceso, y acciones Eliminar subprocesos seleccionando los puntos suspensivos Más (...) junto al comentario.

   

Mover una celda

Para mover una celda, seleccione el lado izquierdo de la celda y arrastre la celda a la posición deseada.

Copiar una celda

Para copiar una celda, cree primero una nueva celda y, a continuación, seleccione todo el texto de la celda original, cópielo y péguelo en la nueva celda. Cuando la celda está en modo de edición, los métodos abreviados de teclado tradicionales para seleccionar todo el texto se limitan a la celda.

Sugerencia

Los cuadernos de Synapse también proporcionan fragmentos de patrones de código usados habitualmente.

Eliminar una celda

Para eliminar una celda, seleccione el botón Eliminar situado a la derecha de la celda.

También se pueden utilizar las teclas de método abreviado en el modo de comando. Seleccione Mayús+D para eliminar la celda actual.

Contraer entrada de celda

Para contraer la entrada de la celda actual, seleccione el Más comandos puntos suspensivos (...) en la barra de herramientas de celda y, a continuación, seleccione Ocultar entrada. Para expandir la entrada, seleccione Mostrar entrada mientras se contrae la celda.

Contraer salida de celda

Para contraer la salida de la celda actual, seleccione los Más comandos puntos suspensivos (...) en la barra de herramientas de celda y, a continuación, seleccione Ocultar salida. Para expandir la salida, seleccione Mostrar salida mientras la salida de la celda está oculta.

Usar un esquema de cuaderno

El esquema (tabla de contenido) presenta el primer encabezado Markdown de cualquier celda Markdown en una ventana de barra lateral para la navegación rápida. La barra lateral de contorno es redimensionable y contraíble para ajustarse a la pantalla de la mejor manera posible. Para abrir u ocultar la barra lateral, seleccione el botón Esquema de la barra de comandos del cuaderno.

Ejecutar un cuaderno

Puede ejecutar las celdas de código en el cuaderno individualmente o todas a la vez. El estado y el progreso de cada celda aparece en el cuaderno.

Nota:

Al eliminar un cuaderno, no se cancelan automáticamente los trabajos que se están ejecutando actualmente. Si necesita cancelar un trabajo, vaya al centro de Monitor y cancele manualmente.

Ejecución de una celda

Hay varias maneras de ejecutar el código en una celda:

• Mantenga el puntero sobre la celda que desea ejecutar y, a continuación, seleccione el botón Ejecutar celda o presione Ctrl+Entrar.

  

• Use teclas de método abreviado en el modo de comando. Seleccione Mayús+Entrar para ejecutar la celda actual y seleccione la celda debajo de ella. Seleccione Alt+Entrar para ejecutar la celda actual e insertar una nueva celda debajo de ella.

Ejecución de todas las celdas

Para ejecutar todas las celdas del cuaderno actual en secuencia, seleccione el botón Ejecutar todo.

Ejecución de todas las celdas encima o debajo

Para ejecutar todas las celdas situadas encima de la celda actual en secuencia, expanda la lista desplegable del botón Ejecutar todo y, a continuación, seleccione Ejecutar celdas encima de. Seleccione Ejecutar celdas debajo de para ejecutar todas las celdas debajo de la actual en secuencia.

Cancelación de todas las celdas en ejecución

Para cancelar las celdas en ejecución o las celdas que esperan en la cola, seleccione el botón Cancelar todo.

Hacer referencia a un cuaderno

Para hacer referencia a otro cuaderno dentro del contexto del cuaderno actual, use el comando magic %run <notebook path>. Todas las variables definidas en el cuaderno de referencia están disponibles en el cuaderno actual.

Este es un ejemplo:

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

La referencia del cuaderno funciona tanto en modo interactivo como en canalizaciones.

El comando %run magic tiene estas limitaciones:

• El comando admite llamadas anidadas, pero no llamadas recursivas.
• El comando admite pasar una ruta de acceso absoluta o un nombre de bloc de notas solo como parámetro. No admite rutas de acceso relativas.
• Actualmente, el comando solo admite cuatro tipos de valor de parámetro: int, float, bool, y string. No admite operaciones de reemplazo de variables.
• Los cuadernos a los que se hace referencia deben publicarse. Debe publicar los cuadernos para hacer referencia a ellos, a menos que seleccione la opción para habilitar una referencia de cuaderno no publicada. Synapse Studio no reconoce los cuadernos no publicados desde el repositorio de Git.
• Los cuadernos a los que se hace referencia no admiten profundidades de instrucciones superiores a cinco.

Uso del explorador de variables

Un cuaderno de Synapse proporciona un explorador de variables integrado en forma de tabla que enumera variables en la sesión actual de Spark para celdas de PySpark (Python). La tabla incluye columnas para el nombre de variable, el tipo, la longitud y el valor. Aparecen automáticamente más variables a medida que se definen en las celdas de código. Al seleccionar cada encabezado de columna, se ordenan las variables de la tabla.

Para abrir u ocultar el explorador de variables, seleccione el botón Variables de la barra de comandos del cuaderno.

Nota:

El explorador de variables solo admite Python.

Usar el indicador de estado de la celda

Un estado paso a paso de una ejecución de celda aparece debajo de la celda para ayudarle a ver su progreso actual. Una vez finalizada la ejecución de la celda, aparece un resumen con la duración total y la hora de finalización y permanece allí para futuras referencias.

Uso del indicador de progreso de Spark

Un cuaderno de Synapse se basa exclusivamente en Spark. Las celdas de código se ejecutan en el grupo de Apache Spark sin servidor de forma remota. Un indicador de progreso del trabajo de Spark con una barra de progreso en tiempo real le ayuda a comprender el estado de ejecución del trabajo.

El número de tareas de cada trabajo o fase le ayuda a identificar el nivel paralelo del trabajo de Spark. También puede profundizar en la interfaz de usuario de Spark de un trabajo o fase específicos mediante la selección del vínculo del nombre del trabajo o de la fase.

Configurar una sesión de Spark

En el panel Configurar sesión, que puede encontrar seleccionando el icono de engranaje en la parte superior del cuaderno, puede especificar la duración del tiempo de espera, el número de ejecutores y el tamaño de los ejecutores que se van a proporcionar a la sesión de Spark actual. Reinicie la sesión de Spark para que los cambios de configuración surtan efecto. Se borran todas las variables del cuaderno almacenadas en la memoria caché.

También puede crear una configuración a partir de la configuración de Apache Spark o seleccionar una configuración existente. Para más información, consulte Administración de la configuración de Apache Spark.

Comando Magic para configurar una sesión de Spark

También puede especificar la configuración de la sesión de Spark mediante el comando magic %%configure. Para que la configuración surta efecto, reinicie la sesión de Spark.

Se recomienda ejecutar %%configure al principio del cuaderno. Este es un ejemplo. Para obtener la lista completa de parámetros válidos, consulte la información de Livy en 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" 
    }
}

Estas son algunas consideraciones para el comando magic de %%configure:

• Se recomienda usar el mismo valor para driverMemory y executorMemory en %%configure. También se recomienda que driverCores y executorCores tengan el mismo valor.
• Puede usar %%configure en canalizaciones de Synapse, pero si no lo establece en la primera celda de código, se producirá un error en la ejecución de la canalización porque no puede reiniciar la sesión.
• Se omite el comando %%configure usado en mssparkutils.notebook.run, pero el comando usado en %run <notebook> continúa ejecutándose.
• Debe usar las propiedades de configuración estándar de Spark en el cuerpo del "conf". No se admiten referencias de primer nivel para las propiedades de configuración de Spark.
• Algunas propiedades especiales de Spark no surtirán efecto en "conf" cuerpo, incluidos "spark.driver.cores", "spark.executor.cores", "spark.driver.memory", "spark.executor.memory", y "spark.executor.instances".

Configuración de sesión con parámetros desde una canalización

Puede usar la configuración de sesión parametrizada para reemplazar los valores del comando magic de %%configure por parámetros de ejecución de canalización (actividad de cuaderno). Al preparar una celda de código de %%configure, puede invalidar los valores predeterminados mediante un objeto similar al siguiente:

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

En el ejemplo siguiente se muestran los valores predeterminados de 4 y "2000", que también se pueden configurar:

%%configure  

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

El cuaderno usa el valor predeterminado si ejecuta el cuaderno en modo interactivo directamente o si la actividad del cuaderno de canalización no proporciona un parámetro que coincida con "activityParameterName".

Durante el modo de ejecución de canalización, puede usar la pestaña Configuración para configurar las opciones de una actividad de cuaderno de canalización.

Si desea cambiar la configuración de sesión, el nombre del parámetro de actividad del cuaderno de canalización debe ser el mismo que activityParameterName en el cuaderno. En este ejemplo, durante una ejecución de canalización, 8 reemplaza driverCores en %%configure, y 4000 reemplaza livy.rsc.sql.num-rows.

Si se produce un error en una ejecución de canalización después de usar el comando magic de %%configure, puede obtener más información de error ejecutando la celda magic %%configure en el modo interactivo del cuaderno.

Traslado de los datos a un cuaderno

Puede cargar datos de grupos de Azure Data Lake Storage Gen 2, Azure Blob Storage y SQL, como se muestra en los ejemplos de código siguientes.

Lectura de un archivo CSV de Azure Data Lake Storage Gen2 como DataFrame de 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')

Lectura de un archivo CSV de Azure Blob Storage como DataFrame de 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)

Lectura de datos desde la cuenta de almacenamiento principal

Puede tener acceso directamente a los datos de la cuenta de almacenamiento principal. No hay necesidad de proporcionar las claves secretas. En el Explorador de datos, haga clic con el botón derecho en un archivo y seleccione Nuevo cuaderno para ver un nuevo cuaderno con un extractor de datos generado automáticamente.

Uso de widgets de IPython

Los widgets son objetos de Python con eventos que tienen una representación en el explorador, a menudo como un control como un control deslizante o un cuadro de texto. Los widgets de IPython solo funcionan en entornos de Python. Actualmente no se admiten en otros lenguajes (por ejemplo, Scala, SQL o C#).

Pasos para usar widgets de IPython

1. Importe el módulo ipywidgets para usar el marco de trabajo de Widgets de Jupyter:

   import ipywidgets as widgets
   

2. Use la función display de nivel superior para representar un widget o deje una expresión de widget tipo en la última línea de la celda de código:

   slider = widgets.IntSlider()
   display(slider)
   

   slider = widgets.IntSlider()
   slider
   

3. Ejecute la celda. El widget aparece en el área de salida.

   

Puede usar varias llamadas de display() para representar la misma instancia del widget varias veces, pero permanecen sincronizadas entre sí:

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

Para representar dos widgets independientes entre sí, cree dos instancias de widget:

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

Widgets admitidos

Tipo de widget	Widgets
Numeric	IntSlider, FloatSlider, FloatLogSlider, IntRangeSlider, FloatRangeSlider, IntProgress, FloatProgress, BoundedIntText, BoundedFloatText, IntText, FloatText
Booleano	ToggleButton, Checkbox, Valid
Selección	Dropdown, RadioButtons, Select, SelectionSlider, SelectionRangeSlider, ToggleButtons, SelectMultiple
Cadena	Text, Text area, Combobox, Password, Label, HTML, HTML Math, Image, Button
Reproducir (animación)	Date picker, Color picker, Controller
Contenedor/Diseño	Box, HBox, VBox, GridBox, Accordion, Tabs, Stacked

Restricciones conocidas

• En la tabla siguiente se enumeran los widgets que no se admiten actualmente, junto con soluciones alternativas:

  Funcionalidad	Solución alternativa
  Widget Output	Puede usar la función print() en su lugar para escribir texto en stdout.
  widgets.jslink()	Puede usar la función widgets.link() para vincular dos widgets similares.
  Widget FileUpload	Ninguno disponible.

• La función global display que proporciona Azure Synapse Analytics no admite la visualización de varios widgets en una llamada (es decir, display(a, b)). Este comportamiento es diferente de la función display de IPython.

• Si cierra un cuaderno que contiene un widget de IPython, no podrá ver ni interactuar con el widget hasta que vuelva a ejecutar la celda correspondiente.

Guardado de cuadernos

Puede guardar un único cuaderno o todos los cuadernos del área de trabajo:

• Para guardar los cambios realizados en un único cuaderno, seleccione el botón Publicar en la barra de comandos del cuaderno.

  

• Para guardar todos los cuadernos en el área de trabajo, seleccione el botón Publicar todo en la barra de comandos del área de trabajo.

  

En el panel Propiedades del cuaderno, puede configurar si se debe incluir la salida de celda al guardar.

Usar comandos magic

Puede usar los comandos magic de Jupyter que ya conoce en los cuadernos de Synapse. Revise las siguientes listas de comandos magic disponibles actualmente. Díganos sus casos de uso en GitHub para que podamos seguir creando más comandos magic para satisfacer sus necesidades.

Nota:

Solo se admiten los siguientes comandos magic en canalizaciones de Synapse: %%pyspark, %%spark, %%csharp, %%sql.

Comandos mágicos disponibles para líneas:

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

Comandos mágicos disponibles para celdas:

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

Hacer referencia a un cuaderno no publicado

Hacer referencia a un cuaderno no publicado es útil cuando desea depurar localmente. Al habilitar esta característica, una ejecución de cuaderno captura el contenido actual en la memoria caché web. Si ejecuta una celda que incluye una instrucción de cuaderno de referencia, haga referencia a los cuadernos de presentación en el explorador de cuadernos actual en lugar de una versión guardada en un clúster. Otros cuadernos pueden hacer referencia a los cambios en el editor de cuadernos sin necesidad de publicar (modo en directo) ni confirmar (modo Git) los cambios. Mediante este enfoque, puede evitar la contaminación de bibliotecas comunes durante el proceso de desarrollo o depuración.

Para habilitar la referencia a un bloc de notas no publicado, active la casilla adecuada en el panel Propiedades.

En la tabla siguiente se comparan los casos. Aunque %run y mssparkutils.notebook.run tienen el mismo comportamiento aquí, la tabla usa %run como ejemplo.

Caso	Disable	Habilitar
Modo directo
- Nb1 (publicado) %run Nb1	Ejecución de la versión publicada de Nb1	Ejecución de la versión publicada de Nb1
- Nb1 (nuevo) %run Nb1	Error	Ejecución del nuevo Nb1
Nb1 (publicado anteriormente, editado) %run Nb1	Ejecución de la versión publicada de Nb1	Ejecución de la versión editada de Nb1
Modo Git
- Nb1 (publicado) %run Nb1	Ejecución de la versión publicada de Nb1	Ejecución de la versión publicada de Nb1
- Nb1 (nuevo) %run Nb1	Error	Ejecución del nuevo Nb1
Nb1 (no publicado, confirmado) %run Nb1	Error	Ejecución de Nb1 confirmado
Nb1 (publicado anteriormente, confirmado) %run Nb1	Ejecución de la versión publicada de Nb1	Ejecución de la versión confirmada de Nb1
Nb1 (publicado anteriormente, nuevo en la rama actual) %run Nb1	Ejecución de la versión publicada de Nb1	Ejecución del nuevo Nb1
Nb1 (no publicado, confirmado previamente, editado) %run Nb1	Error	Ejecución de la versión editada de Nb1
Nb1 (publicado anteriormente y confirmado, editado) %run Nb1	Ejecución de la versión publicada de Nb1	Ejecución de la versión editada de Nb1

En resumen:

• Si deshabilita la referencia a un cuaderno no publicado, ejecute siempre la versión publicada.
• Si habilita la referencia a un cuaderno no publicado, la ejecución de referencia siempre adopta la versión actual del cuaderno que aparece en la experiencia del usuario del cuaderno.

Administrar sesiones activas

Puede reutilizar las sesiones de cuaderno sin tener que iniciar nuevas. En los cuadernos de Synapse, puede administrar las sesiones activas en una sola lista. Para abrir la lista, seleccione los puntos suspensivos (...) y, a continuación, seleccione Administrar sesiones.

En el panel Sesiones activas se enumeran todas las sesiones del área de trabajo actual que ha iniciado desde un cuaderno. La lista muestra la información de sesión y los cuadernos correspondientes. Las Desasociar con cuadernos, Detener la sesión, y Ver en las acciones de supervisión están disponibles aquí. Además, puede conectar el cuaderno seleccionado a una sesión activa que se inició desde otro cuaderno. A continuación, la sesión se desasocia del cuaderno anterior (si no está inactiva) y se adjunta a la actual.

Uso de registros de Python en un cuaderno

Puede encontrar registros de Python y establecer distintos niveles y formatos de registro mediante el código de ejemplo siguiente:

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")

Visualización del historial de comandos de entrada

Los cuadernos de Synapse admiten el comando magic %history para imprimir el historial de comandos de entrada para la sesión actual. El comando magic de %history es similar al comando estándar de Jupyter IPython y funciona para varios contextos de lenguaje en un cuaderno.

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

En el código anterior, -n es el número de ejecución de impresión. El valor de range puede ser:

• N: imprimir código de la celda ejecutada del Nth.
• M-N: Imprima código desde el Mth a la celda ejecutada Nth.

Por ejemplo, para imprimir el historial de entrada desde la primera a la segunda celda ejecutada, use %history -n 1-2.

Integración de un cuaderno

Adición de un cuaderno a una canalización

Para agregar un cuaderno a una canalización existente o crear una nueva canalización, seleccione el botón Agregar a la canalización de la esquina superior derecha.

Designar una celda de parámetro

Para parametrizar el cuaderno, seleccione los puntos suspensivos (...) para acceder a más comandos en la barra de herramientas de celda. A continuación, seleccione celda del parámetro Toggle para designar la celda como la celda de parámetro.

Azure Data Factory busca la celda de parámetros y trata esta celda como valor predeterminado para los parámetros pasados en tiempo de ejecución. El motor de ejecución agrega una nueva celda debajo de la celda de parámetros con parámetros de entrada para sobrescribir los valores predeterminados.

Asignación de valores de parámetros de una canalización

Después de crear un cuaderno con parámetros, puede ejecutarlo desde una canalización mediante una actividad de cuaderno de Synapse. Después de agregar la actividad al lienzo de la canalización, puede establecer los valores parámetro en la sección Parámetros base de la pestaña Configuración.

Al asignar valores de parámetro, puede usar el lenguaje de expresiones de canalización o variables del sistema.

Usar teclas de método abreviado

De forma similar a los cuadernos de Jupyter Notebook, los cuadernos de Synapse tienen una interfaz de usuario modal. El teclado hace diferentes cosas, dependiendo del modo en el que se encuentra la celda del cuaderno. Los cuadernos de Synapse admiten los dos modos siguientes para una celda de código:

• Modo comando: Una celda está en modo de comando cuando no se le pide que escriba ningún cursor de texto. Cuando una celda está en modo de comando, puede editar el cuaderno como un todo, pero no escribir en celdas individuales. Escriba el modo de comando seleccionando la tecla Esc o usando el mouse para seleccionar fuera del área del editor de una celda.

  

• Modo de edición: Cuando una celda está en modo de edición, un cursor de texto le pide que escriba en la celda. Escriba el modo de edición seleccionando la tecla Entrar o usando el mouse para seleccionar el área del editor de una celda.

  

Teclas de método abreviado en modo de comando

Action	Acceso directo del cuaderno de Synapse
Ejecutar la celda actual y seleccionar la que está a continuación	Mayús+Entrar
Ejecutar la celda actual e insertar una a continuación	Alt+Entrar
Ejecutar celda actual	Ctrl+Entrar
Seleccionar la celda anterior	Arriba
Seleccionar la celda siguiente	Bajar
Seleccionar celda anterior	K
Seleccionar celda siguiente	J
Insertar una celda encima	A
Insertar una celda debajo	B
Eliminar celdas seleccionadas	Mayús+D
Cambiar al modo de edición	Escriba

Teclas de método abreviado en modo de edición

Action	Acceso directo del cuaderno de Synapse
Subir el cursor	Arriba
Bajar el cursor	Bajar
Deshacer	Ctrl+Z
Rehacer	Ctrl+Y
Comentar y quitar comentario	Ctrl+/
Eliminar palabra anterior	Ctrl+Retroceso
Eliminar palabra posterior	Ctrl+Suprimir
Ir al inicio de la celda	Ctrl+Inicio
Ir al final de la celda	Ctrl+Fin
Ir una palabra a la izquierda	Ctrl+Izquierda
Ir una palabra a la derecha	Ctrl+Derecha
Seleccionar todo	Ctrl+A
Aplicar sangría	Ctrl+]
Desaplicar sangría	Ctrl+[
Cambiar al modo de comando	Esc

Contenido relacionado

• cuadernos de ejemplo de Synapse
• Inicio rápido: Creación de un grupo de Apache Spark en Azure Synapse Analytics mediante herramientas web
• ¿Qué es Apache Spark en Azure Synapse Analytics?
• Uso de .NET para Apache Spark con Azure Synapse Analytics
• Documentación de .NET para Apache Spark
• Documentación de Azure Synapse Analytics