Share via

Uso de dbx con Visual Studio Code

  • Artículo

Importante

Esta documentación se ha retirado y es posible que no se actualice.

Databricks recomienda usar las agrupaciones de recursos de Databricks en lugar de dbx de Databricks Labs. Consulte Qué son las agrupaciones de recursos de Databricks y Migración de dbx a agrupaciones.

Para usar Azure Databricks con Visual Studio Code, consulte el artículo Extensión de Databricks para Visual Studio Code.

En este artículo, se describe un ejemplo de código basado en Python con el que puede trabajar en cualquier IDE compatible con Python. En concreto, en este artículo se describe cómo trabajar con este ejemplo de código en Visual Studio Code, que proporciona las siguientes características de productividad para desarrolladores:

En este artículo se usa dbx de Databricks Labs junto con Visual Studio Code para enviar el ejemplo de código a un área de trabajo remota de Azure Databricks. dbx lleva a Azure Databricks a Introducción a los flujos de trabajo de Azure Databricks para ejecutar el código enviado en un clúster de trabajos de Azure Databricks en esa área de trabajo.

Puede usar proveedores de Git de terceros populares para el control de versiones y la integración continua y entrega continua o la implementación continua (CI/CD) del código. Para el control de versiones, estos proveedores de Git incluyen lo siguiente:

Para CI/CD, dbx admite las siguientes plataformas de CI/CD:

En este artículo, para demostrar cómo puede funcionar el control de versiones y CI/CD, se describe cómo usar Visual Studio Code, dbx y este ejemplo de código, junto con GitHub y Acciones de GitHub.

Requisitos de ejemplo de código

Para usar este ejemplo de código, debe tener lo siguiente:

Además, en la máquina de desarrollo local, debe tener lo siguiente:

  • Python versión 3.8 o superior.

    Debe usar una versión de Python que coincida con la instalada en los clústeres de destino. Para obtener la versión de Python instalada en un clúster existente, puede usar el terminal web del clúster para ejecutar el comando python --version. Consulte también la sección "Entorno del sistema" de Versiones y compatibilidad de las notas de la versión de Databricks Runtime para obtener la versión de Databricks Runtime de los clústeres de destino. En cualquier caso, la versión de Python debe ser 3.8 o superior.

    Para obtener la versión de Python a la que se hace referencia actualmente en la máquina local, ejecute python --version desde el terminal local. (En función de cómo haya configurado Python en la máquina local, es posible que tenga que ejecutar python3 en lugar de python en este artículo). Consulte también Selección de un intérprete de Python.

  • pip. pip se instala automáticamente con las versiones más recientes de Python. Para comprobar si pip ya está instalado, ejecute pip --version desde el terminal local. (En función de cómo haya configurado Python o pip en la máquina local, es posible que tenga que ejecutar pip3 en lugar de pip en este artículo).

  • dbx versión 0.8.0 o superior. Puede instalar el paquete dbx desde el índice de paquetes de Python (PyPI) ejecutando pip install dbx.

    Nota:

    No es necesario instalar dbx ahora. Puede instalarlo más adelante en la sección setup del ejemplo de código.

  • Un método para crear entornos virtuales de Python para asegurarse de que se usan las versiones correctas de Python y las dependencias de paquetes en los proyectos de dbx. En este artículo, se trata pipenv.

  • La CLI de Databricks, versión 0.18 o anterior, configurada con autenticación.

    Nota:

    No es necesario instalar la CLI de Databricks heredada (versión 0.17 de la CLI de Databricks) ahora. Puede instalarla más adelante en la sección setup del ejemplo de código. Si quiere instalarla más adelante, debe recordar configurar la autenticación en ese momento en su lugar.

  • Visual Studio Code.

  • La extensión de Python para Visual Studio Code.

  • La extensión de solicitud de incorporación y problemas de GitHub para Visual Studio Code.

  • Git.

Acerca del ejemplo de código

El ejemplo de código de Python de este artículo, disponible en el repositorio databricks/ide-best-practices de GitHub, hace lo siguiente:

  1. Obtiene datos del repositorio owid/covid-19-data en GitHub.
  2. Filtra los datos de un código de país ISO específico.
  3. Crea una tabla dinámica a partir de los datos.
  4. Realiza la limpieza de datos.
  5. Modulariza la lógica de código en funciones reutilizables.
  6. Realiza pruebas unitarias de las funciones.
  7. Proporciona configuraciones y opciones de proyecto dbx para permitir que el código escriba los datos en una tabla Delta en un área de trabajo remota de Azure Databricks.

Ejecución del ejemplo de código

Una vez que haya establecido los requisitos para este ejemplo de código, complete los pasos siguientes para empezar a usar el ejemplo de código.

Nota:

En estos pasos no se incluye la configuración de este ejemplo de código para CI/CD. No es necesario configurar CI/CD para ejecutar este ejemplo de código. Si quiere configurar CI/CD más adelante, consulte Ejecución con Acciones de GitHub.

Paso 1: Creación de un entorno virtual de Python

  1. Desde el terminal, cree una carpeta en blanco para que contenga un entorno virtual para este ejemplo de código. Estas instrucciones usan una carpeta primaria denominada ide-demo. Puede asignar cualquier nombre que quiera a esta carpeta. Si se usa un nombre diferente, reemplace el nombre en este artículo. Después de crear la carpeta, cambie a dicha carpeta y, a continuación, inicie Visual Studio Code desde esa carpeta. Asegúrese de incluir el punto (.) después del comando code.

    Para Linux y macOS:

    mkdir ide-demo
cd ide-demo
code .

    Sugerencia

    Si se recibe el error command not found: code, consulte Inicio desde la línea de comandos en el sitio web de Microsoft.

    Para Windows:

    md ide-demo
cd ide-demo
code .

  2. En Visual Studio Code, en la barra de menús, haga clic en Ver > Terminal.

  3. Desde la raíz de la carpeta ide-demo, ejecute el comando pipenv con la siguiente opción, donde <version> es la versión de destino de Python que ya ha instalado localmente (e, idealmente, una versión que coincida con la versión de Python de los clústeres de destino), por ejemplo, 3.8.14.

    pipenv --python <version>

    Anote el valor de Virtualenv location en la salida del comando pipenv, ya que lo necesitará en el paso siguiente.

  4. Seleccione el intérprete de Python de destino y, a continuación, active el entorno virtual de Python:

    1. En la barra de menús, haga clic en View > Command Palette, escriba Python: Select y, a continuación, haga clic en Python: Select Interpreter.

    2. Seleccione el intérprete de Python de la ruta de acceso al entorno virtual de Python que acaba de crear. (Esta ruta de acceso aparece como el valor de Virtualenv location en la salida del comando pipenv).

    3. En la barra de menús, haga clic en View > Command Palette, escriba Terminal: Create y, a continuación, haga clic en Terminal: Create New Terminal.

    4. Asegúrese de que el símbolo del sistema indica que está en el shell pipenv. Para confirmarlo, debería ver algo parecido a (<your-username>) antes del símbolo del sistema. Si no lo ve, ejecute el siguiente comando:

      pipenv shell

      Para salir del shell pipenv, ejecute el comando exit, y los paréntesis desaparecerán.

    Para más información, consulte Uso de entornos de Python en VS Code en la documentación de Visual Studio Code.

Paso 2: Clonación del ejemplo de código de GitHub

  1. En Visual Studio Code, abra la carpeta ide-demo (Archivo > Abrir carpeta), si aún no está abierta.
  2. Haga clic en Ver > Paleta de comandos, escriba Git: Cloney, a continuación, haga clic en Git: Clonar.
  3. Para Proporcione la dirección URL del repositorio o seleccione un origen de repositorio, escriba https://github.com/databricks/ide-best-practices.
  4. Vaya a la carpeta ide-demo y haga clic en Seleccionar ubicación del repositorio.

Paso 3: Instalación de las dependencias del ejemplo de código

  1. Instale una versión de dbx y la 0.18 o anterior de la CLI de Databricks que sea compatible con la versión de Python. Para ello, en Visual Studio Code en el terminal, desde la carpeta ide-demo con un shell pipenv activado (pipenv shell), ejecute el siguiente comando:

    pip install dbx

  2. Confirme que dbx está instalado. Para ello, ejecute el siguiente comando:

    dbx --version

    Si se devuelve el número de versión, dbx está instalado.

    Si el número de versión es inferior a 0.8.0, actualice dbx con la ejecución del siguiente comando y vuelva a comprobar el número de versión:

    pip install dbx --upgrade
dbx --version

# Or ...
python -m pip install dbx --upgrade
dbx --version

  3. Al instalar dbx, la CLI de Databricks heredada (CLI de Databricks versión 0.17) también se instala automáticamente. Para confirmar que la CLI de Databricks heredada (CLI de Databricks versión 0.17) esté instalada, ejecute el siguiente comando:

    databricks --version

    Si se devolviera la versión 0.17 de la CLI de Databricks, se instalará la CLI de Databricks heredada.

  4. Si no configuró la CLI de Databricks heredada (CLI de Databricks versión 0.17) con autenticación, será necesario hacerlo ahora. Para confirmar que la autenticación está configurada, ejecute el siguiente comando básico para obtener información de resumen sobre el área de trabajo de Azure Databricks. Asegúrese de incluir la barra diagonal (/) después del subcomando ls:

    databricks workspace ls /

    Si se devuelve una lista de nombres de carpeta de nivel raíz para el área de trabajo, la autenticación está configurada.

  5. Instale los paquetes de Python de los que depende este ejemplo de código. Para ello, ejecute el siguiente comando desde la carpeta ide-demo/ide-best-practices:

    pip install -r unit-requirements.txt

  6. Confirme que los paquetes dependientes del ejemplo de código estén instalados. Para ello, ejecute el siguiente comando:

    pip list

    Si los paquetes que aparecen en los archivos requirements.txt y unit-requirements.txt están en alguna parte de esta lista, se instalan los paquetes dependientes.

    Nota:

    Los archivos enumerados en requirements.txt son para versiones de paquete específicas. Para mejorar la compatibilidad, puede hacer referencia cruzada a estas versiones con el tipo de nodo de clúster que quiere que use el área de trabajo de Azure Databricks para ejecutar implementaciones más adelante. 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.

Paso 4: Personalización del ejemplo de código para el área de trabajo de Azure Databricks

  1. Personalice la configuración del proyecto dbx del repositorio. Para ello, en el archivo .dbx/project.json, cambie el valor del objeto profile de DEFAULT por el nombre del perfil que coincida con el que configuró para la autenticación con la CLI de Databricks heredada (CLI de Databricks versión 0.17). Si no configuró ningún perfil no predeterminado, deje DEFAULT tal como está. Por ejemplo:

    {
  "environments": {
    "default": {
      "profile": "DEFAULT",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Shared/dbx/covid_analysis",
        "artifact_location": "dbfs:/Shared/dbx/projects/covid_analysis"
      }
    }
  },
  "inplace_jinja_support": false
}

  2. Personalice la configuración de implementación del proyecto dbx. Para ello, en el archivo conf/deployment.yml, cambie el valor de los objetos spark_version y node_type_id de 10.4.x-scala2.12 y m6gd.large por la cadena de versión en tiempo de ejecución y el tipo de nodo de clúster de Azure Databricks que desea que el área de trabajo de Azure Databricks use para ejecutar implementaciones.

    Por ejemplo, para especificar Databricks Runtime 10.4 LTS y un tipo de nodo Standard_DS3_v2:

    environments:
  default:
    workflows:
      - name: "covid_analysis_etl_integ"
        new_cluster:
          spark_version: "10.4.x-scala2.12"
          num_workers: 1
        node_type_id: "Standard_DS3_v2"
        spark_python_task:
          python_file: "file://jobs/covid_trends_job.py"
      - name: "covid_analysis_etl_prod"
        new_cluster:
          spark_version: "10.4.x-scala2.12"
          num_workers: 1
          node_type_id: "Standard_DS3_v2"
          spark_python_task:
            python_file: "file://jobs/covid_trends_job.py"
          parameters: ["--prod"]
      - name: "covid_analysis_etl_raw"
        new_cluster:
          spark_version: "10.4.x-scala2.12"
          num_workers: 1
          node_type_id: "Standard_DS3_v2"
          spark_python_task:
            python_file: "file://jobs/covid_trends_job_raw.py"

Sugerencia

En este ejemplo, cada una de estas tres definiciones de trabajo tiene el mismo valor de spark_version y node_type_id. Puede usar distintos valores para diferentes definiciones de trabajo. También puede crear valores compartidos y reutilizarlos en las definiciones de trabajo para reducir los errores de escritura y el mantenimiento de código. Consulte el ejemplo de YAML en la documentación de dbx.

Exploración del ejemplo de código

Después de configurar el ejemplo de código, use la siguiente información para obtener información sobre cómo funcionan los distintos archivos de la carpeta ide-demo/ide-best-practices.

Modularización de código

Código sin modularizar

El archivo jobs/covid_trends_job_raw.py es una versión sin modularizar de la lógica de código. Puede ejecutar este archivo por sí mismo.

Código modularizado

El archivo jobs/covid_trends_job.py es una versión modularizada de la lógica de código. Este archivo se basa en el código compartido del archivo covid_analysis/transforms.py. El archivo covid_analysis/__init__.py trata la carpeta covide_analysis como un paquete contenedor.

Prueba

Pruebas unitarias

El archivo tests/testdata.csv contiene una pequeña parte de los datos del archivo covid-hospitalizations.csv con fines de prueba. El archivo tests/transforms_test.py contiene las pruebas unitarias del archivo covid_analysis/transforms.py.

Ejecutor de prueba unitaria

El archivo pytest.ini contiene opciones de configuración para ejecutar pruebas con pytest. Consulte pytest.ini y Opciones de configuración en la documentación de pytest.

El archivo .coveragerc contiene opciones de configuración para las medidas de cobertura de código en Python con coverage.py. Vea Referencia de configuración en la documentación de coverage.py.

El archivo requirements.txt, que es un subconjunto del archivo unit-requirements.txt que ejecutó anteriormente con pip, contiene una lista de paquetes de los que también dependen las pruebas unitarias.

Packaging

El archivo setup.py proporciona comandos que se ejecutarán en la consola (scripts de consola), como el comando pip, para empaquetar proyectos de Python con setuptools. Consulte Puntos de entrada en la documentación setuptools.

Otros archivos

Hay otros archivos en este ejemplo de código que no se han descrito anteriormente:

  • La carpeta .github/workflows contiene tres archivos, databricks_pull_request_tests.yml, onpush.yml y onrelease.yaml, que representan el Acciones de GitHub, que se explican más adelante en la sección Acciones de GitHub.
  • El archivo .gitignore contiene una lista de carpetas y archivos locales que Git omite para el repositorio.

Ejecución del ejemplo de código

Puede usar dbx en la máquina local para indicar a Azure Databricks que ejecute el ejemplo de código en el área de trabajo remota a petición, como se describe en la siguiente subsección. O bien, puede usar Acciones de GitHub para que GitHub ejecute el ejemplo de código cada vez que inserte cambios de código en el repositorio de GitHub.

Ejecución con dbx

  1. Instale el contenido de la carpeta covid_analysis como un paquete en setuptoolsmodo de desarrollo de Python ejecutando el siguiente comando desde la raíz del proyecto dbx (por ejemplo, la carpeta ide-demo/ide-best-practices). Asegúrese de incluir el punto (.) al final de este comando:

    pip install -e .

    Este comando crea una carpeta covid_analysis.egg-info, que contiene información sobre la versión compilada de los archivos covid_analysis/__init__.py y covid_analysis/transforms.py.

  2. Para realizar las pruebas, ejecute el siguiente comando:

    pytest tests/

    Los resultados de las pruebas se muestran en el terminal. Las cuatro pruebas deben mostrarse como superadas.

    Sugerencia

    Para ver otra manera de enfocar las pruebas, incluidas las pruebas para cuadernos de R y Scala, consulte Pruebas unitarias para cuadernos.

  3. Opcionalmente, ejecute el siguiente comando para obtener las métricas de cobertura de prueba para las pruebas:

    coverage run -m pytest tests/

    Nota:

    Si un mensaje indica que no se encuentra coverage, ejecute pip install coverage e inténtelo de nuevo.

    Para ver los resultados de la cobertura de prueba, ejecute el siguiente comando:

    coverage report -m

  4. Si se superan las cuatro pruebas, envíe el contenido del proyecto dbx al área de trabajo de Azure Databricks mediante la ejecución del siguiente comando:

    dbx deploy --environment=default

    La información sobre el proyecto y sus ejecuciones se envían a la ubicación especificada en el objeto workspace_directory del archivo .dbx/project.json.

    El contenido del proyecto se envía a la ubicación especificada en el objeto artifact_location del archivo .dbx/project.json.

  5. Ejecute la versión de preproducción del código en el área de trabajo, ejecutando el siguiente comando:

    dbx launch covid_analysis_etl_integ

    En el terminal, se muestra un vínculo a los resultados de la ejecución. Debe tener el siguiente aspecto:

    https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345

    Siga este vínculo en el explorador web para ver los resultados de la ejecución en el área de trabajo.

  6. Ejecute la versión de producción del código en el área de trabajo, ejecutando el siguiente comando:

    dbx launch covid_analysis_etl_prod

    En el terminal, se muestra un vínculo a los resultados de la ejecución. Debe tener el siguiente aspecto:

    https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456

    Siga este vínculo en el explorador web para ver los resultados de la ejecución en el área de trabajo.

Ejecución con Acciones de GitHub

En la carpeta .github/workflows del proyecto, los archivos onpush.yml y onrelease.yml de Acciones de GitHub hacen lo siguiente:

  • En cada inserción en una etiqueta que comienza por v, usa dbx para implementar el trabajo covid_analysis_etl_prod.
  • En cada inserción que no es en una etiqueta que comienza por v:
    1. Usa pytest para ejecutar las pruebas unitarias.
    2. Usa dbx para implementar en el área de trabajo remota, el archivo especificado en el trabajo covid_analysis_etl_integ.
    3. Usa dbx para iniciar el archivo ya implementado especificado en el trabajo covid_analysis_etl_integ en el área de trabajo remota, trazando esta ejecución hasta que finalice.

Nota:

Se proporciona un archivo Acciones de GitHub adicional, databricks_pull_request_tests.yml, como plantilla con la que experimentar, sin afectar a los archivos onpush.yml y onrelease.yml de Acciones de GitHub. Puede ejecutar este ejemplo de código sin el archivo databricks_pull_request_tests.yml de Acciones de GitHub. Su utilización no se explica en este artículo.

En las subsecciones siguientes se describe cómo configurar y ejecutar los archivos onpush.yml y onrelease.yml de Acciones de GitHub.

Configuración para usar Acciones de GitHub

Configure el área de trabajo de Azure Databricks siguiendo las instrucciones de Entidades de servicio para CI/CD. Esto incluye las acciones siguientes:

  1. Crear una entidad de servicio.
  2. Cree un token de Microsoft Entra ID para una entidad de servicio.

Como procedimiento recomendado de seguridad, Databricks recomienda usar un token de Microsoft Entra ID para una entidad de servicio, en lugar del token de acceso personal de Databricks para el usuario del área de trabajo, para permitir que GitHub se autentique con el área de trabajo de Azure Databricks.

Después de crear la entidad de servicio y su token de Microsoft Entra ID, detenga y anote el valor del token de Microsoft Entra ID, que usará en la sección siguiente.

Ejecución de Acciones de GitHub

Paso 1: Publicación del repositorio clonado
  1. En Visual Studio Code, en la barra lateral, haga clic en el icono de GitHub. Si el icono no está visible, habilite primero la extensión Solicitudes de incorporación de cambios de GitHub y problemas a través de la vista Extensiones (Ver > Extensiones).
  2. Si el botón Iniciar sesión está visible, haga clic en él y siga las instrucciones de la pantalla para iniciar sesión en la cuenta de GitHub.
  3. En la barra de menús, haga clic en Ver > Paleta de comandos, escriba Publish to GitHub y, a continuación, haga clic en Publicar en GitHub.
  4. Seleccione una opción para publicar el repositorio clonado en la cuenta de GitHub.
Paso 2: Adición de secretos cifrados al repositorio

En el sitio web de GitHub del repositorio publicado, siga las instrucciones de Creación de secretos cifrados para un repositorio, para los siguientes secretos cifrados:

  • Cree un secreto cifrado denominado DATABRICKS_HOST, establecido en el valor de la dirección URL por área de trabajo, por ejemplo, https://adb-1234567890123456.7.azuredatabricks.net.
  • Cree un secreto cifrado denominado DATABRICKS_TOKEN, establecido en el valor del token de Microsoft Entra ID Entra para la entidad de servicio.
Paso 3: Creación y publicación de una rama en el repositorio
  1. En Visual Studio Code, en la vista Control de código fuente (Ver > Control de código fuente), haga clic en el icono ... (Vistas y más acciones).
  2. Haga clic en Rama > Crear rama desde.
  3. Escriba un nombre para la rama, por ejemplo my-branch.
  4. Seleccione la rama desde la que se va a crear la rama, por ejemplo main.
  5. Realice un cambio menor en uno de los archivos del repositorio local y, a continuación, guarde el archivo. Por ejemplo, realice un cambio menor en un comentario de código en el archivo tests/transforms_test.py.
  6. En la vista Control de código fuente, vuelva a hacer clic en el icono ... (Vistas y más acciones).
  7. Haga clic en Cambios > Almacenar todos los cambios.
  8. Vuelva a hacer clic en el icono ... (Vistas y más acciones).
  9. Haga clic en Confirmar > Confirmar por etapas.
  10. Escriba un mensaje para la confirmación.
  11. Vuelva a hacer clic en el icono ... (Vistas y más acciones).
  12. Haga clic en Rama > Publicar rama.
Paso 4: Creación de una solicitud de incorporación de cambios y combinación
  1. Vaya al sitio web de GitHub para el repositorio publicado, https://github/<your-GitHub-username>/ide-best-practices.
  2. En la pestaña Solicitudes de cambios, junto a my-branch tiene inserciones recientes, haga clic en Comparar y solicitar cambios.
  3. Haga clic en Crear solicitud de incorporación de cambios.
  4. En la página de solicitud de incorporación de cambios, espere a que en el icono junto a Canalización de CI/ci-pipeline (inserción) se muestre una marca de verificació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 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).
  5. Si aparece la marca de verificación verde, combine la solicitud de incorporación de cambios en la rama main haciendo clic en Combinar solicitud de incorporación de cambios.