Procedimientos recomendados de ingeniería de software para cuadernos

En este artículo, se proporciona un tutorial práctico que muestra cómo aplicar procedimientos recomendados de ingeniería de software a los cuadernos de Azure Databricks, incluido el control de versiones, el uso compartido de código, las pruebas y, opcionalmente, la integración continua y la entrega o implementación continuas (CI/CD).

En este tutorial realizará lo siguiente:

• Agregue cuadernos a carpetas de Git de Azure Databricks para el control de versiones.
• Extraer partes del código de uno de los cuadernos en un módulo que se puede compartir.
• Probar el código compartido.
• Ejecutar los cuadernos desde un trabajo de Azure Databricks.
• Opcionalmente, aplicar CI/CD al código compartido.

Requisitos

Para completar este tutorial, debe proporcionar los siguientes recursos:

• Un repositorio remoto con un proveedor de Git compatible con Databricks. En el tutorial de este artículo, se usa GitHub. En este tutorial, se da por supuesto que tiene disponible un repositorio de GitHub llamado best-notebooks. (Puede asignarle un nombre diferente al repositorio. Si lo hace, reemplace best-notebooks con el nombre del repositorio en este tutorial). Cree un repositorio de GitHub si aún no tiene uno.

  Nota:

  Si crea un nuevo repositorio, asegúrese de inicializar el repositorio con al menos un archivo, por ejemplo, un archivo README.

• Un área de trabajo de Azure Databricks. Cree un área de trabajo si aún no tiene una.

• Un clúster de propósito general de Azure Databricks en el área de trabajo. Para ejecutar cuadernos durante la fase de diseño, conecte los cuadernos a un clúster de propósito general en ejecución. Más adelante, este tutorial usa un trabajo de Azure Databricks para automatizar la ejecución de los cuadernos en este clúster. (También puede ejecutar trabajos en clústeres de trabajos que solo existen durante la vigencia de los trabajos). Cree un clúster de propósito general si aún no tiene uno.

Paso 1: Configuración de carpetas de Git de Databricks

En este paso, conectará el repositorio de GitHub existente a las carpetas de Git de Azure Databricks en el área de trabajo de Azure Databricks existente.

Para permitir que el área de trabajo se conecte al repositorio de GitHub, primero debe proporcionar al área de trabajo las credenciales de GitHub, si aún no lo ha hecho.

Paso 1.1: Proporcionar las credenciales de GitHub

1. Haga clic en el nombre de usuario en la parte superior derecha del área de trabajo y, a continuación, haga clic en Configuración en la lista desplegable.
2. En la barra lateral Configuración, en Usuario, haga clic en Cuentas vinculadas.
3. En la pestaña Integración con Git, en Proveedor de Git, seleccione GitHub.
4. Haga clic en Token de acceso personal
5. En Git provider username or email (Nombre de usuario o correo electrónico del proveedor de Git), escriba su nombre de usuario de GitHub.
6. En Token, escriba el token de acceso personal de GitHub (clásico). Este token de acceso personal (clásico) debe tener los permisos de repositorio y flujo de trabajo.
7. Haga clic en Save(Guardar).

Paso 1.2: Conexión al repositorio de GitHub

1. En la barra lateral del área de trabajo, haga clic en Área de trabajo.
2. En el explorador Área de trabajo, expanda Área de trabajo >Usuarios.
3. Haga clic con el botón derecho en la carpeta de nombre de usuario y, a continuación, haga clic en crear > carpeta git.
4. En el cuadro de diálogo Crear carpeta Git:
   1. En Git repository URL (Dirección URL del repositorio de Git), escriba la dirección URL Clone with HTTPS (Clonar con HTTPS) de GitHub del repositorio de GitHub. En este artículo, se da por supuesto que la dirección URL termina con best-notebooks.git; por ejemplo, https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. En Git provider (Proveedor de Git), seleccione GitHub.
   3. Deje Nombre de carpeta de Git establezca en el nombre del repositorio, por ejemplo, best-notebooks.
   4. Haga clic en Crear carpeta Git.

Paso 2: Importación y ejecución del cuaderno

En este paso, importará un cuaderno externo existente en el repositorio. Puede crear sus propios cuadernos para este tutorial, pero los proporcionamos aquí para acelerar las cosas.

Paso 2.1: Creación de una rama de trabajo en el repositorio

En este paso secundario, creará una rama llamada eda en el repositorio. Esta rama le permite trabajar en los archivos y el código independientemente de la rama main del repositorio, lo cual es un procedimiento recomendado de ingeniería de software. (Puede asignar otro nombre a la rama).

Nota:

En algunos repositorios, la rama main puede denominarse master en su lugar. Si es así, reemplace main con master en este tutorial.

Sugerencia

Si no está familiarizado con el trabajo en ramas de Git, consulte Git Branching - Branches in a Nutshell (Ramas de Git: las ramas en pocas palabras) en el sitio web de Git.

1. La carpeta Git del paso 1.2 debe estar abierta. Si no es así, en la barra lateral Área de trabajo, expanda Área de trabajo> Usuarios, expanda la carpeta nombre de usuario y haga clic en la carpeta Git.

2. Junto al nombre de la carpeta en la ruta de navegación del área de trabajo, haga clic en el botón rama principal de Git.

3. En el cuadro de diálogo best-notebooks, haga clic en el botón Crear rama.

   Nota:

   Si el repositorio tiene un nombre que no sea best-notebooks, el título de este cuadro de diálogo será diferente aquí y a lo largo de este tutorial.

4. Escriba eda, y haga clic en Crear.

5. Cierre este cuadro de diálogo.

Paso 2.2: Importación del cuaderno en el repositorio

En este paso secundario, importará un cuaderno existente de otro repositorio en su repositorio. Este cuaderno hace lo siguiente:

• Copia un archivo .csv desde el repositorio de GitHub owid/covid-19-data en un clúster del área de trabajo. Este archivo .csv contiene datos públicos sobre hospitalizaciones por COVID-19 y métricas de cuidados intensivos de todo el mundo.
• Lea el contenido del archivo CSV en un Pandas DataFrame.
• Filtra los datos para que contengan métricas solo de los Estados Unidos.
• Muestra un trazado de los datos.
• Guarde el Dataframe de Pandas como una API de Pandas en Spark DataFrame.
• Realiza la limpieza de datos en el DataFrame de la API de Pandas en Spark.
• Escribe el DataFrame de la API de Pandas en Spark como una tabla Delta en el área de trabajo.
• Muestra el contenido de la tabla Delta.

Aunque puede crear su propio cuaderno en el repositorio aquí, la importación de un cuaderno existente ayuda a acelerar este tutorial. Para crear un cuaderno en esta rama o mover un cuaderno existente a esta rama en lugar de importar un cuaderno, consulte Uso básico de los archivos del área de trabajo.

1. En la carpeta Git de best-notebooks, haga clic en Crear > carpeta.
2. En el cuadro de diálogo Nueva carpeta, escriba notebooks, y haga clic en Crear.
3. En la carpeta cuadernos, haga clic en el kebab y a continuación, Importar.
4. En el cuadro de diálogo Importar:

   1. En Import from (Importar desde), seleccione URL.

   2. Escriba la dirección URL del contenido sin procesar del cuaderno covid_eda_raw en el repositorio databricks/notebook-best-practices de GitHub. Para obtener esta dirección URL: i. Ir a https://github.com/databricks/notebook-best-practices. ii. Haga clic en la carpeta notebooks. iii. Haga clic en el archivo covid_eda_raw.py. iv. Haga clic en Raw (Sin procesar). .v Copie la dirección URL completa de la barra de direcciones de su explorador web en el cuadro de diálogo Importar.

      Nota:

      El cuadro de diálogo Importar solo funciona con direcciones URL Git para repositorios públicos.

   3. Haga clic en Import.

Paso 2.3: Ejecución del cuaderno

1. Si el cuaderno aún no se muestra, abra la carpeta cuadernos, y a continuación, haga clic en el cuaderno covid_eda_raw dentro de la carpeta.
2. Seleccione el clúster al que asociar este cuaderno. Para obtener instrucciones sobre cómo crear un clúster, consulte Creación de un clúster.
3. Haga clic en Run All (Ejecutar todo).
4. Espere mientras se ejecuta el cuaderno.

Una vez que el cuaderno termine de ejecutarse, en el cuaderno debería ver un trazado de los datos, así como más de 600 filas de datos sin procesar en la tabla Delta. Si el clúster aún no se estaba ejecutando al empezar a ejecutar este cuaderno, el clúster podría tardar varios minutos en iniciarse antes de mostrar los resultados.

Paso 2.4: Insertar en el repositorio y combinar el cuaderno

En este paso secundario, guardará el trabajo realizado hasta ahora en el repositorio de GitHub. A continuación, combinará el cuaderno de la rama de trabajo en la rama main del repositorio.

1. Junto al nombre del cuaderno, haga clic en el botón de rama de Git eda.
2. En el cuadro de diálogo best-notebooks, en la pestaña Changes (Cambios), asegúrese de que esté seleccionado el archivo notebooks/covid_eda_raw.py.
3. En Mensaje de confirmación (obligatorio),escriba Added raw notebook.
4. En Description (optional) (Descripción [opcional]), escriba This is the first version of the notebook.
5. Haz clic en Commit & Push.
6. Haga clic en el vínculo Solicitud de incorporación de cambios en Crear una solicitud de incorporación de cambios en el proveedor de Git en el banner.
7. En GitHub, cree la solicitud de incorporación de cambios y, a continuación, combine la solicitud de incorporación de cambios en la rama main.
8. De vuelta en el área de trabajo de Azure Databricks, cierre el cuadro de diálogo best-notebooks si aún se muestra.

Paso 3: Traslado del código a un módulo compartido

En este paso, moverá parte del código del cuaderno a un conjunto de funciones compartidas fuera del cuaderno. Esto le permite usar estas funciones con otros cuadernos similares, lo que puede acelerar la futura codificación y ayudar a garantizar resultados de cuadernos más predecibles y coherentes. El uso compartido de este código también le permite probar más fácilmente estas funciones, algo que como procedimiento recomendado de ingeniería de software puede aumentar la calidad general del código a medida que avance.

Paso 3.1: Creación de otra rama de trabajo en el repositorio

1. Junto al nombre del cuaderno, haga clic en el botón de rama de Git eda.
2. En el cuadro de diálogo best-notebooks, haga clic en la flecha desplegable situada junto a la rama eda y seleccione main.
3. Haga clic en el botón Pull (Incorporar cambios). Si se le pide que continúe con la incorporación de cambios, haga clic en Confirm (Confirmar).
4. Haga clic en el botón Crear rama.
5. Escriba first_modules, y haga clic en Crear. (Puede asignar otro nombre a la rama).
6. Cierre este cuadro de diálogo.

Paso 3.2: Importación del cuaderno en el repositorio

Para acelerar este tutorial, en este paso secundario se importa otro cuaderno existente en el repositorio. Este cuaderno hace lo mismo que el cuaderno anterior, excepto que este cuaderno llamará a funciones de código compartido que se almacenan fuera del cuaderno. De nuevo, aquí podría crear su propio cuaderno en el repositorio y hacer el uso compartido de código real usted mismo.

1. En el explorador Área de trabajo, haga clic con el botón derecho en la carpeta cuadernos y luego haga clic en Importar.
2. En el cuadro de diálogo Importar:

   1. En Import from (Importar desde), seleccione URL.

   2. Escriba la dirección URL del contenido sin procesar del cuaderno covid_eda_modular en el repositorio databricks/notebook-best-practices de GitHub. Para obtener esta dirección URL: i. Ir a https://github.com/databricks/notebook-best-practices. ii. Haga clic en la carpeta notebooks. iii. Haga clic en el archivo covid_eda_modular.py. iv. Haga clic en Raw (Sin procesar). v. Copie la dirección URL completa desde la barra de direcciones del explorador web en el cuadro de diálogo Import Notebooks (Importar cuadernos).

      Nota:

      El cuadro de diálogo Importar cuadernos solo funciona con direcciones URL de Git para repositorios públicos.

   3. Haga clic en Import.

Paso 3.3: Adición de funciones de código compartido compatibles con el cuaderno

1. En el explorador Área de trabajo, haga clic con el botón derecho en la carpeta best-notebooks Git y luego haga clic en Crear> carpeta.

2. En el cuadro de diálogo Nueva carpeta, escriba covid_analysis, y haga clic en Crear.

3. En la carpeta covid_analysis, haga clic en Crear > archivo.

4. En el cuadro de diálogo New File Name (Nombre del nuevo archivo), escriba transforms.py y, a continuación, haga clic en Create File (Crear archivo).

5. En la ventana del editor de transforms.py, escriba el código siguiente:

   import pandas as pd
   
   # Filter by country code.
   def filter_country(pdf, country="USA"):
     pdf = pdf[pdf.iso_code == country]
     return pdf
   
   # Pivot by indicator, and fill missing values.
   def pivot_and_clean(pdf, fillna):
     pdf["value"] = pd.to_numeric(pdf["value"])
     pdf = pdf.fillna(fillna).pivot_table(
       values="value", columns="indicator", index="date"
     )
     return pdf
   
   # Create column names that are compatible with Delta tables.
   def clean_spark_cols(pdf):
     pdf.columns = pdf.columns.str.replace(" ", "_")
     return pdf
   
   # Convert index to column (works with pandas API on Spark, too).
   def index_to_col(df, colname):
     df[colname] = df.index
     return df
   

Sugerencia

Para ver otras técnicas de uso compartido de código, consulte Compartir código entre cuadernos de Databricks.

Paso 3.4: Adición de las dependencias del código compartido

El código anterior tiene varias dependencias de paquetes de Python para permitir que el código se ejecute correctamente. En este paso secundario, se declaran estas dependencias de paquetes. La declaración de dependencias mejora la reproducibilidad mediante el uso de versiones de las bibliotecas definidas de forma precisa.

1. En el explorador Área de trabajo, haga clic con el botón derecho en la carpeta best-notebooks Git y luego haga clic en Crear> carpeta.

   Nota:

   Quiere que el archivo que muestra las dependencias de paquetes vaya a la raíz de la carpeta Git, no a las carpetas cuadernos o covid_analysis.

2. En el cuadro de diálogo New File Name (Nombre del nuevo archivo), escriba requirements.txt y, a continuación, haga clic en Create File (Crear archivo).

3. En la ventana del editor requirements.txt, escribe el siguiente código:

   Nota:

   Si el archivo requirements.txt no está visible, es posible que tenga que actualizar el explorador web.

   -i https://pypi.org/simple
   attrs==21.4.0
   cycler==0.11.0
   fonttools==4.33.3
   iniconfig==1.1.1
   kiwisolver==1.4.2
   matplotlib==3.5.1
   numpy==1.22.3
   packaging==21.3
   pandas==1.4.2
   pillow==9.1.0
   pluggy==1.0.0
   py==1.11.0
   py4j==0.10.9.3
   pyarrow==7.0.0
   pyparsing==3.0.8
   pyspark==3.2.1
   pytest==7.1.2
   python-dateutil==2.8.2
   pytz==2022.1
   six==1.16.0
   tomli==2.0.1
   wget==3.2
   

   Nota:

   En el archivo anterior, se enumeran las versiones específicas de los paquetes. Para mejorar la compatibilidad, puede hacer una referencia cruzada de estas versiones con las instaladas en el clúster de propósito general. Consulte la sección "Entorno del sistema" para conocer la versión de Databricks Runtime del clúster en Versiones y compatibilidad de las notas de la versión de Databricks Runtime.

La estructura del repositorio debería tener ahora un aspecto similar al siguiente:

|-- covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
└── requirements.txt

Paso 3.5: Ejecución del cuaderno refactorizado

En este paso secundario, ejecutará el cuaderno covid_eda_modular, que llama al código compartido del archivo covid_analysis/transforms.py.

1. En el explorador Área de trabajo, haga clic en el cuaderno covid_eda_modular dentro de la carpeta notebooks.
2. Seleccione el clúster al que asociar este cuaderno.
3. Haga clic en Run All (Ejecutar todo).
4. Espere mientras se ejecuta el cuaderno.

Una vez que el cuaderno termine de ejecutarse, en el cuaderno debería ver resultados similares a los del cuaderno covid_eda_raw: un trazado de los datos, así como más de 600 filas de datos sin procesar en la tabla Delta. La principal diferencia con este cuaderno es que se usa un filtro diferente (un iso_code de DZA en lugar de USA). Si el clúster aún no se estaba ejecutando al empezar a ejecutar este cuaderno, el clúster podría tardar varios minutos en iniciarse antes de mostrar los resultados.

Paso 3.6: Insertar en el repositorio el cuaderno y su código relacionado

1. Junto al nombre del cuaderno, haga clic en el botón first_modules rama de Git.
2. En el cuadro de diálogo best-notebooks, en la pestaña Changes (Cambios), asegúrese de que se hayan seleccionado los siguientes elementos:
   • requirements.txt
   • covid_analysis/transforms.py
   • notebooks/covid_eda_modular.py
3. Para mensaje de confirmación (obligatorio), escriba Added refactored notebook.
4. En Description (optional) (Descripción [opcional]), escriba This is the second version of the notebook.
5. Haz clic en Commit & Push.
6. Haga clic en el vínculo Solicitud de incorporación de cambios en Crear una solicitud de incorporación de cambios en el proveedor de Git en el banner.
7. En GitHub, cree la solicitud de incorporación de cambios y, a continuación, combine la solicitud de incorporación de cambios en la rama main.
8. De vuelta en el área de trabajo de Azure Databricks, cierre el cuadro de diálogo best-notebooks si aún se muestra.

Paso 4: Prueba del código compartido

En este paso, probará el código compartido del último paso. Sin embargo, querrá probar este código sin ejecutar el propio cuaderno covid_eda_modular. Esto se debe a que si el código compartido no se puede ejecutar, es probable que el propio cuaderno tampoco se ejecute. Querrá primero detectar los errores en el código compartido antes de que el cuaderno principal produzca un error más adelante. Esta técnica de pruebas es un procedimiento recomendado de ingeniería de software.

Sugerencia

Para obtener enfoques adicionales a fin de probar cuadernos, así como pruebas para cuadernos de R y Scala, vea Pruebas unitarias para cuadernos.

Paso 4.1: Creación de otra rama de trabajo en el repositorio

1. Junto al nombre del cuaderno, haga clic en el botón first_modules rama de Git.
2. En el cuadro de diálogo best-notebooks, haga clic en la flecha desplegable situada junto a la rama first_modules y seleccione principal.
3. Haga clic en el botón Pull (Incorporar cambios). Si se le pide que continúe con la incorporación de cambios, haga clic en Confirm (Confirmar).
4. Haga clic en Crear rama.
5. Escriba first_tests, y haga clic en Crear. (Puede asignar otro nombre a la rama).
6. Cierre este cuadro de diálogo.

Paso 4.2: Adición de las pruebas

En este paso secundario, se usa el marco pytest para probar el código compartido. En estas pruebas, se afirma si se logran resultados de pruebas específicas. Si alguna prueba genera un resultado inesperado, esa prueba específica produce un error en la aserción y, por tanto, se produce un error en la propia prueba.

1. En el explorador Área de trabajo, haga clic con el botón derecho en la carpeta git y luego haga clic en Crear > carpeta.

2. En el cuadro de diálogo Nueva carpeta, escriba tests, y haga clic en Crear.

3. En la carpeta de pruebas, haga clic en Crear> archivo .

4. En el cuadro de diálogo New File Name (Nombre del nuevo archivo), escriba testdata.csv y, a continuación, haga clic en Create File (Crear archivo).

5. En la ventana del editor testdata.csv, escriba los siguientes datos de prueba:

   entity,iso_code,date,indicator,value
   United States,USA,2022-04-17,Daily ICU occupancy,
   United States,USA,2022-04-17,Daily ICU occupancy per million,4.1
   United States,USA,2022-04-17,Daily hospital occupancy,10000
   United States,USA,2022-04-17,Daily hospital occupancy per million,30.3
   United States,USA,2022-04-17,Weekly new hospital admissions,11000
   United States,USA,2022-04-17,Weekly new hospital admissions per million,32.8
   Algeria,DZA,2022-04-18,Daily ICU occupancy,1010
   Algeria,DZA,2022-04-18,Daily ICU occupancy per million,4.5
   Algeria,DZA,2022-04-18,Daily hospital occupancy,11000
   Algeria,DZA,2022-04-18,Daily hospital occupancy per million,30.9
   Algeria,DZA,2022-04-18,Weekly new hospital admissions,10000
   Algeria,DZA,2022-04-18,Weekly new hospital admissions per million,32.1
   

6. En la carpeta de pruebas, haga clic en Crear> archivo .

7. En el cuadro de diálogo New File Name (Nombre del nuevo archivo), escriba transforms_test.py y, a continuación, haga clic en Create File (Crear archivo).

8. En la ventana del editor transforms_test.py, escriba el siguiente código de prueba. Estas pruebas usan pytest accesorios estándar así como un DataFrame de pandas en memoria simulado:

   # Test each of the transform functions.
   import pytest
   from textwrap import fill
   import os
   import pandas as pd
   import numpy as np
   from covid_analysis.transforms import *
   from pyspark.sql import SparkSession
   
   @pytest.fixture
   def raw_input_df() -> pd.DataFrame:
     """
     Create a basic version of the input dataset for testing, including NaNs.
     """
     return pd.read_csv('tests/testdata.csv')
   
   @pytest.fixture
   def colnames_df() -> pd.DataFrame:
     df = pd.DataFrame(
       data=[[0,1,2,3,4,5]],
       columns=[
         "Daily ICU occupancy",
         "Daily ICU occupancy per million",
         "Daily hospital occupancy",
         "Daily hospital occupancy per million",
         "Weekly new hospital admissions",
         "Weekly new hospital admissions per million"
       ]
     )
     return df
   
   # Make sure the filter works as expected.
   def test_filter(raw_input_df):
     filtered = filter_country(raw_input_df)
     assert filtered.iso_code.drop_duplicates()[0] == "USA"
   
   # The test data has NaNs for Daily ICU occupancy; this should get filled to 0.
   def test_pivot(raw_input_df):
     pivoted = pivot_and_clean(raw_input_df, 0)
     assert pivoted["Daily ICU occupancy"][0] == 0
   
   # Test column cleaning.
   def test_clean_cols(colnames_df):
     cleaned = clean_spark_cols(colnames_df)
     cols_w_spaces = cleaned.filter(regex=(" "))
     assert cols_w_spaces.empty == True
   
   # Test column creation from index.
   def test_index_to_col(raw_input_df):
     raw_input_df["col_from_index"] = raw_input_df.index
     assert (raw_input_df.index == raw_input_df.col_from_index).all()
   

La estructura del repositorio debería tener ahora un aspecto similar al siguiente:

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py

Paso 4.3: Ejecución de las pruebas

Para acelerar este tutorial, en este paso secundario se usa un cuaderno importado para ejecutar las pruebas anteriores. Este cuaderno descarga e instala los paquetes de Python con dependencias de las pruebas en el área de trabajo, ejecuta las pruebas e informa de los resultados de las pruebas. Aunque puede ejecutar pytest desde el terminal web del clúster, ejecutar pytest desde un cuaderno puede ser más cómodo.

Nota:

Al ejecutar pytest, se ejecutan todos los archivos cuyos nombres siguen el formulario test_*.py o /*_test.py en el directorio actual y sus subdirectorios.

1. En el explorador Área de trabajo, haga clic con el botón derecho en la carpeta cuadernos y luego haga clic en Importar.
2. En el cuadro de diálogo Import Notebooks (Importar cuadernos):

   1. En Import from (Importar desde), seleccione URL.

   2. Escriba la dirección URL del contenido sin procesar del cuaderno run_unit_tests en el repositorio databricks/notebook-best-practices de GitHub. Para obtener esta dirección URL: i. Ir a https://github.com/databricks/notebook-best-practices. ii. Haga clic en la carpeta notebooks. iii. Haga clic en el archivo run_unit_tests.py. iv. Haga clic en Raw (Sin procesar). v. Copie la dirección URL completa desde la barra de direcciones del explorador web en el cuadro de diálogo Import Notebooks (Importar cuadernos).

      Nota:

      El cuadro de diálogo Importar cuadernos solo funciona con direcciones URL de Git para repositorios públicos.

   3. Haga clic en Import.

3. Seleccione el clúster al que asociar este cuaderno.
4. Haga clic en Run All (Ejecutar todo).
5. Espere mientras se ejecuta el cuaderno.

Una vez que el cuaderno termine de ejecutarse, en el cuaderno debería ver información sobre el número de pruebas superadas y con errores, junto con otros detalles relacionados. Si el clúster aún no se estaba ejecutando al empezar a ejecutar este cuaderno, el clúster podría tardar varios minutos en iniciarse antes de mostrar los resultados.

La estructura del repositorio debería tener ahora un aspecto similar al siguiente:

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  ├── covid_eda_raw (optional)
│  └── run_unit_tests
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py

Paso 4.4: Insertar en el repositorio el cuaderno y las pruebas relacionadas

1. Junto al nombre del cuaderno, haga clic en el botón de rama de Git first_tests.
2. En el cuadro de diálogo best-notebooks, en la pestaña Changes (Cambios), asegúrese de que se hayan seleccionado los siguientes elementos:
   • tests/transforms_test.py
   • notebooks/run_unit_tests.py
   • tests/testdata.csv
3. En Mensaje de confirmación (obligatorio), escriba Added tests.
4. En Description (optional) (Descripción [opcional]), escriba These are the unit tests for the shared code.
5. Haz clic en Commit & Push.
6. Haga clic en el vínculo Solicitud de incorporación de cambios en Crear una solicitud de incorporación de cambios en el proveedor de Git en el banner.
7. En GitHub, cree la solicitud de incorporación de cambios y, a continuación, combine la solicitud de incorporación de cambios en la rama main.
8. De vuelta en el área de trabajo de Azure Databricks, cierre el cuadro de diálogo best-notebooks si aún se muestra.

Paso 5: Creación de un trabajo para ejecutar los cuadernos

En los pasos anteriores, ha probado el código compartido manualmente y ha ejecutado los cuadernos manualmente. En este paso, usará un trabajo de Azure Databricks para probar el código compartido y ejecutar los cuadernos automáticamente, ya sea a petición o según una programación regular.

Paso 5.1: Creación de una tarea de trabajo para ejecutar el cuaderno de pruebas

1. En la barra lateral del área de trabajo, haga clic en Flujos de trabajo.
2. En la pestaña Jobs (Trabajos), haga clic en Create Job (Crear trabajo).
3. Edite el nombre del trabajo para que sea covid_report.
4. En Task name (Nombre de la tarea), escriba run_notebook_tests.
5. En Type (Tipo), seleccione Notebook (Cuaderno).
6. Para origen, seleccione Proveedor de Git.
7. Haga clic en Add a git reference (Agregar una referencia de Git).
8. En el cuadro de diálogo Git information (Información de Git):
   1. En Git repository URL (Dirección URL del repositorio de Git), escriba la dirección URL Clone with HTTPS (Clonar con HTTPS) de GitHub del repositorio de GitHub. En este artículo, se da por supuesto que la dirección URL termina con best-notebooks.git; por ejemplo, https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. En Git provider (Proveedor de Git), seleccione GitHub.
   3. En Git reference (branch / tag / commit) (Referencia de Git [rama/ etiqueta / confirmación]), escriba main.
   4. Junto a Git reference (branch / tag / commit) (Referencia de Git [rama/ etiqueta / confirmación]), seleccione branch (Rama).
   5. Haga clic en Confirmar.
9. En Path (Ruta de acceso), escriba notebooks/run_unit_tests. No agregue la extensión de archivo .py.
10. En Cluster (Clúster), seleccione el clúster del paso anterior.
11. Haga clic en Create task (Crear tarea).

Nota:

En este escenario, Databricks no recomienda usar el botón de programación del cuaderno, tal como se describe en Creación y administración de trabajos de cuaderno programados, para programar un trabajo a fin de ejecutar este cuaderno periódicamente. Esto se debe a que el botón de programación crea un trabajo mediante la copia de trabajo más reciente del cuaderno en el repositorio del área de trabajo. En su lugar, Databricks recomienda seguir las instrucciones anteriores para crear un trabajo que use la versión confirmada más reciente del cuaderno en el repositorio.

Paso 5.2: Creación de una tarea de trabajo para ejecutar el cuaderno principal

1. Haga clic en el icono + Agregar tarea.
2. Aparece un menú emergente. Seleccione Cuaderno.
3. En Task name (Nombre de la tarea), escriba run_main_notebook.
4. En Type (Tipo), seleccione Notebook (Cuaderno).
5. En Path (Ruta de acceso), escriba notebooks/covid_eda_modular. No agregue la extensión de archivo .py.
6. En Cluster (Clúster), seleccione el clúster del paso anterior.
7. Verify Depende del valor es run_notebook-tests.
8. Haga clic en Create task (Crear tarea).

Paso 5.3 Ejecución del trabajo

1. Haga clic en Ejecutar ahora.

2. En el elemento emergente, haga clic en View run (Ver ejecución).

   Nota:

   Si el elemento emergente desaparece demasiado rápido, haga lo siguiente:

   1. En la barra lateral del entorno Ciencias de datos e ingeniería o Databricks Mosaic AI, haga clic en Flujos de trabajo.
   2. En la pestaña Job runs (Ejecuciones del trabajo), haga clic en el valor de Start time (Hora de inicio) para obtener el último trabajo con covid_report en la columna Jobs (Trabajos).

3. Para ver los resultados del trabajo, haga clic en el icono run_notebook_tests, el icono run_main_notebook o ambos. Los resultados de cada icono son los mismos que si hubiera ejecutado los cuadernos usted mismo, uno por uno.

Nota:

Este trabajo se ha ejecutado a petición. Para configurar este trabajo para que se ejecute periódicamente, consulte Tipos de desencadenador para trabajos de Databricks.

(Opcional) Paso 6: Configuración del repositorio para probar el código y ejecutar el cuaderno automáticamente cada vez que cambie el código

En el paso anterior, usó un trabajo para probar automáticamente el código compartido y ejecutar los cuadernos en un momento dado o periódicamente. Sin embargo, puede preferir desencadenar pruebas automáticamente cuando los cambios se combinan en el repositorio de GitHub, mediante una herramienta de CI/CD, como Acciones de GitHub.

Paso 6.1: Configuración del acceso de GitHub al área de trabajo

En este subpaso, configurará un flujo de trabajo de Acciones de GitHub que ejecuta trabajos en el área de trabajo siempre que los cambios se combinen en el repositorio. Para ello, se proporciona a GitHub un token único de Azure Databricks para el acceso.

Por motivos de seguridad, Databricks desaconseja proporcionar el token de acceso personal del usuario del área de trabajo de Azure Databricks a GitHub. En su lugar, Databricks recomienda proporcionar a GitHub un token de Microsoft Entra ID que esté asociado a una entidad de servicio de Microsoft Entra ID. Para obtener instrucciones, consulte la sección Azure de la página Ejecución de una acción de GitHub de un cuaderno de Databricks en el marketplace de Acciones de GitHub.

Importante

Los cuadernos se ejecutan con todos los permisos del área de trabajo de la identidad asociada al token, por lo que Databricks recomienda usar una entidad de servicio. Si realmente desea proporcionar el token de acceso personal del usuario del área de trabajo de Azure Databricks a GitHub solo con fines de exploración personal y entiende que, por motivos de seguridad, Databricks desaconseja esta práctica, consulte las instrucciones para crear el token de acceso personal del usuario del área de trabajo.

Paso 6.2: Adición del flujo de trabajo de Acciones de GitHub

En este paso secundario, agregará un flujo de trabajo de Acciones de GitHub para ejecutar el cuaderno run_unit_tests siempre que haya una solicitud de incorporación de cambios en el repositorio.

Este paso secundario almacena el flujo de trabajo de Acciones de GitHub en un archivo que se almacena dentro de varios niveles de carpetas en el repositorio de GitHub. Acciones de GitHub requiere que exista una jerarquía específica de carpetas anidadas en el repositorio para que funcione correctamente. Para completar este paso, debe usar el sitio web para el repositorio de GitHub, ya que la interfaz de usuario de la carpeta Git de Azure Databricks no admite la creación de jerarquías de carpetas anidadas.

1. En el sitio web del repositorio de GitHub, haga clic en la pestaña Code (Código).

2. Haga clic en la flecha situada junto a principal para implementar la lista desplegable Cambiar ramas o etiquetas.

3. En el cuadro Find or create a branch (Buscar o crear una rama), escriba adding_github_actions.

4. Haga clic en Create branch: adding_github_actions from ‘main’ (Crear rama: adding_github_actions desde "main").

5. Haga clic en Add file > Create new file (Agregar archivo > Crear nuevo archivo).

6. En Name your file (Nombre del archivo), escriba .github/workflows/databricks_pull_request_tests.yml.

7. En la ventana del editor, escriba el código siguiente. Este código usa el enlace de pull_request desde Ejecutar acción de GitHub del cuaderno de Databricks Notebook para ejecutar el cuaderno de run_unit_tests.

   En el código siguiente, reemplace:

   • <your-workspace-instance-URL> por el nombre de la instancia de Azure Databricks.
   • <your-access-token> por el token que generó anteriormente.
   • <your-cluster-id> por el identificador del clúster de destino.

   name: Run pre-merge Databricks tests
   
   on:
     pull_request:
   
   env:
     # Replace this value with your workspace instance name.
     DATABRICKS_HOST: https://<your-workspace-instance-name>
   
   jobs:
     unit-test-notebook:
       runs-on: ubuntu-latest
       timeout-minutes: 15
   
       steps:
         - name: Checkout repo
           uses: actions/checkout@v2
         - name: Run test notebook
           uses: databricks/run-notebook@main
           with:
             databricks-token: <your-access-token>
   
             local-notebook-path: notebooks/run_unit_tests.py
   
             existing-cluster-id: <your-cluster-id>
   
             git-commit: "${{ github.event.pull_request.head.sha }}"
   
             # Grant all users view permission on the notebook's results, so that they can
             # see the result of the notebook, if they have related access permissions.
             access-control-list-json: >
               [
                 {
                   "group_name": "users",
                   "permission_level": "CAN_VIEW"
                 }
               ]
             run-name: "EDA transforms helper module unit tests"
   

8. Haga clic en Commit changes (Confirmar cambios).

9. En el cuadro de diálogo Confirmar cambios, escriba Create databricks_pull_request_tests.yml en Mensaje de confirmación

10. Seleccione Confirmar directamente en la rama de adding_github_actions y haga clic en Confirmar cambios.

11. En la pestaña Código, haga clic en Comparación solicitud de incorporación de cambios y, a continuación, cree la solicitud de incorporación de cambios.

12. En la página de la solicitud de incorporación de cambios, espere a que el icono situado junto a Run pre-merge Databricks tests / unit-test-notebook (pull_request) (Ejecutar pruebas de Databricks previas a la combinación / unit-test-notebook [pull_request]) muestre una marca de comprobación verde. (El icono puede tardar unos minutos en aparecer). Si hay una X roja en lugar de una marca de comprobación verde, haga clic en Details (Detalles) para averiguar por qué. Si ya no se muestran el icono o la opción Details (Detalles), haga clic en Show all checks (Mostrar todas las comprobaciones).

13. Si aparece la marca de comprobación verde, combine la solicitud de incorporación de cambios en la rama main.

(Opcional) Paso 7: Actualización del código compartido en GitHub para desencadenar pruebas

En este paso, realizará un cambio en el código compartido y, a continuación, insertará el cambio en el repositorio de GitHub, que desencadenará inmediatamente las pruebas automáticamente, en función de la acción de GitHub del paso anterior.

Paso 7.1: Creación de otra rama de trabajo en el repositorio

1. En el explorador Área de trabajo, abra la carpeta git best-notebooks.
2. Junto al nombre de la carpeta, haga clic en la rama de git botón first_tests.
3. En el cuadro de diálogo best-notebooks, haga clic en la flecha desplegable situada junto a la rama first_tests y seleccione principal.
4. Haga clic en el botón Pull (Incorporar cambios). Si se le pide que continúe con la incorporación de cambios, haga clic en Confirm (Confirmar).
5. Haga clic en el botón + (Crear rama).
6. Escriba trigger_tests, y haga clic en Crear. (Puede asignar otro nombre a la rama).
7. Cierre este cuadro de diálogo.

Paso 7.2: Cambio del código compartido

1. En el explorador Área de trabajo, en la carpeta git best-notebooks, haga clic en el archivo covid_analysis/transforms.py.

2. Cambie la tercera línea de este archivo:

   # Filter by country code.
   

   Por esta otra:

   # Filter by country code. If not specified, use "USA."
   

Paso 7.3: Insertar en el repositorio el cambio para desencadenar las pruebas

1. Junto al nombre del archivo, haga clic en el botón de la rama de git trigger_tests.
2. En el cuadro de diálogo best-notebooks, en la pestaña Changes (Cambios), asegúrese de que esté seleccionado el archivo covid_analysis/transforms.py.
3. Para mensaje de confirmación (obligatorio), escriba Updated comment.
4. En Description (optional) (Descripción [opcional]), escriba This updates the comment for filter_country.
5. Haz clic en Commit & Push.
6. Haga clic en el vínculo solicitud de incorporación de cambios en Crear una solicitud de incorporación de cambios en el proveedor de Git en el banner y luego cree la solicitud de incorporación de cambios en GitHub.
7. En la página de la solicitud de incorporación de cambios, espere a que el icono situado junto a Run pre-merge Databricks tests / unit-test-notebook (pull_request) (Ejecutar pruebas de Databricks previas a la combinación / unit-test-notebook [pull_request]) muestre una marca de comprobación verde. (El icono puede tardar unos minutos en aparecer). Si hay una X roja en lugar de una marca de comprobación verde, haga clic en Details (Detalles) para averiguar por qué. Si ya no se muestran el icono o la opción Details (Detalles), haga clic en Show all checks (Mostrar todas las comprobaciones).
8. Si aparece la marca de comprobación verde, combine la solicitud de incorporación de cambios en la rama main.