Использование dbx с Visual Studio Code

Статья
10/09/2024

Внимание

Поддержка этой документации прекращена, она может больше не обновляться.

Databricks рекомендует использовать пакеты ресурсов Databricks вместо dbx Databricks Labs. См. раздел "Что такое пакеты ресурсов Databricks" и "Миграция из dbx в пакеты".

Сведения об использовании Azure Databricks с Visual Studio Code см. в статье о расширении Databricks для Visual Studio Code.

В этой статье описывается пример кода на основе Python, с которым можно работать в любой интегрированной среде разработки, совместимой с Python. В частности, в данной статье описывается, как работать с этим примером кода в Visual Studio Code, что предоставляет следующие функции повышения эффективности разработчика.

Заполнение кода
Выделение
Тестирование
Отладка объектов кода, которые не требуют подключения к удаленным ресурсам Azure Databricks в режиме реального времени.

В данной статье используется dbx от Databricks Labs вместе с Visual Studio Code для отправки примера кода в удаленную рабочую область Azure Databricks. dbx указывает Azure Databricks обзор оркестрации в Databricks запустить отправленный код в кластере заданий Azure Databricks заданий в этой рабочей области.

Вы можете использовать для управления версиями и непрерывной интеграции и непрерывной поставки или непрерывного развертывания (CI/CD) кода популярные сторонние поставщики Git. Для управления версиями используются в том числе следующие поставщики Git.

GitHub
Bitbucket;
GitLab
Azure DevOps (недоступен в регионах Azure для Китая).
AWS CodeCommit
GitHub AE

dbx поддерживает следующие платформы CI/CD.

Чтобы продемонстрировать работу управления версиями и CI/CD, в этой статье описывается, как использовать Visual Studio Code, dbxи этот пример кода, а также GitHub и GitHub Actions.

Требования к примеру кода

Чтобы использовать этот пример кода, необходимо следующее.

Рабочая область Azure Databricks в учетной записи Azure Databricks.
Учетная запись GitHub. Создайте учетную запись GitHub, если у вас еще нет ее.

Кроме того, на вашем локальном компьютере для разработки должно быть установлено следующее.

Python версии 3.8 или более поздней.

Следует использовать версию Python, соответствующую версии, установленной в целевых кластерах. Чтобы получить версию Python, установленную в существующем кластере, можно использовать веб-терминал кластера для выполнения команды python --version. См. также раздел "Системная среда" в версиях заметок о выпуске Databricks Runtime и совместимости версии среды выполнения Databricks для целевых кластеров. В любом случае требуется Python версии 3.8 или более поздней.

Чтобы получить версию Python, на которую сейчас ссылается локальный компьютер, запустите python --version из локального терминала. (В зависимости от варианта настройки Python на локальном компьютере в процессе изучения данной статьи может потребоваться запустить python3 вместо python.) См. также раздел Выбор интерпретатора Python.
pip. pip автоматически устанавливается с более новыми версиями Python. Чтобы проверить наличие установки pip, запустите pip --version из локального терминала. (В зависимости от варианта настройки Python или pip на локальном компьютере в процессе изучения данной статьи может потребоваться запустить pip3 вместо pip.)
dbx версии 0.8.0 или более поздней. Вы можете установить пакет dbx с помощью PyPI, выполнив команду pip install dbx.

Примечание.

Устанавливать dbx сейчас не нужно. Его можно установить позже в разделе установки примера кода.
Метод создания виртуальных сред Python должен гарантировать, что в проектах dbx всегда используются правильные версии Python и все нужные зависимости пакетов. В этой статье рассматривается pipenv.
Интерфейс командной строки Databricks версии 0.18 или ниже настроен с проверкой подлинности.

Примечание.

Теперь вам не нужно устанавливать устаревший интерфейс командной строки Databricks (Databricks CLI версии 0.17). Его можно установить позже в разделе установки примера кода. Если вы хотите установить его позже, не забудьте сейчас вместо этого настроить проверку подлинности.
Visual Studio Code.
Расширение Python для Visual Studio Code.
Расширение запросов на вытягивание и сообщений о проблемах на GitHub для Visual Studio Code.
Git.

Сведения о примере кода

Пример кода Python для этой статьи, доступный в репозитории databricks/ide-best-practices на GitHub, выполняет следующие действия.

Получает данные из репозитория owid/covid-19-data на GitHub.
Фильтрует данные по определенному коду страны ISO.
Создает сводную таблицу на основе данных.
Выполняет очистку данных.
Составляет логику кода из модулей в многократно используемые функции.
Выполняет модульное тестирование функций.
Предоставляет конфигурации и параметры проекта dbx, что позволяет коду записывать данные в разностную таблицу в удаленной рабочей области Azure Databricks.

Запуск примера кода

Выполнив требования для этого примера кода, выполните следующие действия, чтобы начать работу с примером кода.

Примечание.

Эти действия не включают настройку данного примера кода для CI/CD. Для запуска этого примера кода не требуется настраивать CI/CD. Если вы хотите настроить CI/CD позже, см. статью Запуск с помощью GitHub Actions.

Шаг 1. Создание виртуального окружения Python

В терминале создайте пустую папку, содержащую виртуальную среду для этого примера кода. Эти инструкции используют папку с именем ide-demo. Вы можете присвоить этой папке любое имя. Выбрав другое имя, просто укажите его вместо используемого по умолчанию во всей статье. Откройте созданную папку и запустите Visual Studio Code из нее. Не забудьте добавить точку (.) после команды code.

Для Linux и macOS:
```
mkdir ide-demo
cd ide-demo
code .
```
Совет

При появлении ошибки command not found: code см. раздел Запуск из командной строки на веб-сайте Майкрософт.

Для Windows:
```
md ide-demo
cd ide-demo
code .
```
В Visual Studio Code в строке меню щелкните Вид > Терминал.
В корне папки ide-demo выполните команду pipenv со следующим параметром, где <version> — это целевая версия Python, которую вы уже установили локально (в идеале это версия, соответствующая версии Python вашего целевого кластера), например 3.8.14.
```
pipenv --python <version>
```
Запишите значение Virtualenv location в выходных данных команды pipenv, так как оно понадобится на следующем шаге.
Выберите целевой интерпретатор Python и активируйте виртуальную среду Python:
1. В строке меню щелкните Вид > Палитра команд, введите Python: Select и выберите Python: выбрать интерпретатор.
2. Выберите интерпретатор Python в пути к созданной виртуальной среде Python. (Этот путь указан в качестве значения Virtualenv location в выходных данных команды pipenv.)
3. В строке меню щелкните Вид > палитры команд, введите Terminal: Create и выберите Терминал: создать новый терминал.
4. Убедитесь, что в командной строке указано, что вы находитесь в оболочке pipenv. Для подтверждения перед переходом в командную строку должно отобразиться что-то подобное (<your-username>). Если ничего не отображается, выполните следующую команду:
```
pipenv shell
```
  Чтобы выйти из оболочки pipenv, выполните команду exit, и круглые скобки исчезнут.
Дополнительные сведения см. в разделе, посвященном использованию сред Python в VS Code, в документации по Visual Studio Code.

Шаг 2. Клонирование примера кода из GitHub

В Visual Studio Code откройте папку ide-demo (Файл > Открыть папку), если она еще не открыта.
Щелкните Вид > Палитра команд, введите Git: Clone и нажмите кнопку Git: клонировать.
В поле Укажите URL-адрес репозитория или выберите источник репозитория введите https://github.com/databricks/ide-best-practices.
Перейдите в папку ide-demo и щелкните Выбрать расположение репозитория.

Шаг 3. Установка зависимостей примера кода

Установите версию интерфейса командной dbx строки Databricks версии 0.18 или ниже, совместимую с вашей версией Python. Для этого в терминале Visual Studio Code из папки ide-demo с активированной оболочкой pipenv(pipenv shell) выполните следующую команду:
```
pip install dbx
```
Проверьте наличие установки dbx. Для этого выполните следующую команду:
```
dbx --version
```
Если возвращается номер версии, dbx установлено.

Если номер версии ниже 0.8.0, выполните dbx следующую команду, а затем снова проверьте номер версии:
```
pip install dbx --upgrade
dbx --version

# Or ...
python -m pip install dbx --upgrade
dbx --version
```
При установке dbxустаревший интерфейс командной строки Databricks (Databricks CLI версии 0.17) также устанавливается автоматически. Чтобы убедиться, что установлен устаревший интерфейс командной строки Databricks (Databricks CLI версии 0.17), выполните следующую команду:
```
databricks --version
```
Если возвращается интерфейс командной строки Databricks версии 0.17, устанавливается устаревший интерфейс командной строки Databricks.
Если вы не настроили устаревший интерфейс командной строки Databricks (Databricks CLI версии 0.17) с проверкой подлинности, это необходимо сделать сейчас. Убедитесь, что проверка подлинности настроена, выполнив следующую базовую команду для получения сводной информации о рабочей области Azure Databricks. Не забудьте поставить косую черту (/) после подкоманды ls:
```
databricks workspace ls /
```
Если возвращается список имен папок корневого уровня для рабочей области, проверка подлинности настроена.
Установите пакеты Python, от которые зависит этот пример кода. Для этого запустите выполнение следующей команды из папки ide-demo/ide-best-practices.
```
pip install -r unit-requirements.txt
```
Убедитесь, что зависимые пакеты примера кода установлены. Для этого выполните следующую команду:
```
pip list
```
Если пакеты из списка в requirements.txt и файлы unit-requirements.txt находятся в этом списке, зависимые пакеты установлены.

Примечание.

Файлы из списка в requirements.txt предназначены для определенных версий пакетов. Для повышения совместимости можно оставлять перекрестные ссылки на эти версии с типом узла кластера, который требуется использовать в рабочей области Azure Databricks для последующего запуска развертываний. Ознакомьтесь с разделом "Системная среда" для версии среды выполнения Databricks кластера в заметках о выпуске Databricks Runtime и совместимости.

Шаг 4. Настройка примера кода для рабочей области Azure Databricks

Настройте параметры проекта dbx репозитория. Для этого в .dbx/project.json файле измените значение profile объекта на DEFAULT имя профиля, соответствующего указанному для проверки подлинности с помощью устаревшей интерфейса командной строки Databricks (Databricks CLI версии 0.17). Если вы не настроили профиль, отличный от используемого по умолчанию, оставьте DEFAULT как есть. Например:
```
{
  "environments": {
    "default": {
      "profile": "DEFAULT",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/covid_analysis",
        "artifact_location": "dbfs:/Shared/dbx/projects/covid_analysis"
      }
    }
  },
  "inplace_jinja_support": false
}
```

Настройте параметры развертывания проекта dbx. Для этого в файле conf/deployment.yml измените значение spark_version и объектов node_type_id с 10.4.x-scala2.12 и m6gd.large на строку версии среды выполнения Azure Databricks и тип узла кластера, которые требуется использовать для запуска развертываний в рабочей области Azure Databricks.

Например, чтобы указать Databricks Runtime 10.4 LTS и тип узла 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"

Совет

В данном примере каждое из этих трех определений задания имеет одно и то же значение spark_version и node_type_id. Вы можете использовать разные значения для разных определений задания. Чтобы уменьшить количество ошибок ввода и объем обслуживания кода, можно также создавать общие значения и многократно использовать их в определениях заданий. См. пример YAML в документации по dbx.

Изучение примера кода

После настройки примера кода воспользуйтесь следующими сведениями, чтобы узнать, как работают различные файлы в папке ide-demo/ide-best-practices.

Модулирование кода

Немодульный код

Файл jobs/covid_trends_job_raw.py представляет собой немодульную версию логики кода. Этот файл можно запустить самостоятельно.

Модульный код

Файл jobs/covid_trends_job.py представляет собой модульную версию логики кода. Этот файл использует общий код в файле covid_analysis/transforms.py. Файл covid_analysis/__init__.py рассматривает папку covide_analysis как содержащий пакет.

Тестирование

Модульные тесты

Файл tests/testdata.csv содержит небольшую часть данных в файле covid-hospitalizations.csv для тестирования. Файл tests/transforms_test.py содержит модульные тесты для файла covid_analysis/transforms.py.

Средство выполнения модульных тестов

Файл pytest.ini содержит параметры конфигурации для выполнения тестов с помощью pytest. См. статьи pytest.ini и Параметры конфигурации в документации по pytest.

Файл .coveragerc содержит параметры конфигурации для измерений объема протестированного кода Python с помощью coverage.py. См. справочник по конфигурации в документации по coverage.py.

Файл requirements.txt, который представляет собой подмножество файла unit-requirements.txt, запущенного ранее с помощью pip, содержит список пакетов, от которых также зависят модульные тесты.

Упаковка

Файл setup.py предоставляет команды для выполнения в консоли (консольные скрипты), такие как команда pip, для упаковки проектов Python с помощью средств установки. См. статью Точки входа в документации по setuptools.

Другие файлы

В этом примере кода имеются и другие файлы, которые не были описаны ранее.

Папка .github/workflows содержит три файла, databricks_pull_request_tests.yml, onpush.yml и onrelease.yaml, которые представляют GitHub Actions (рассматривается далее в разделе GitHub Actions).
Файл .gitignore содержит список локальных папок и файлов, которые Git игнорирует для репозитория.

Запуск примера кода

С помощью dbx на локальном компьютере можно предписать Azure Databricks запустить пример кода в удаленной рабочей области по запросу, как описано в следующем подразделе. Кроме того, можно использовать GitHub Actions, чтобы GitHub запускал пример кода при каждой отправке изменений кода в репозиторий GitHub.

Запуск с помощью dbx

Установите содержимое covid_analysis папки в виде пакета в режиме разработки Python setuptools, выполнив следующую команду из корневого dbx каталога проекта (например, папкуide-demo/ide-best-practices). Не забудьте добавить точку (.) в конце команды.
```
pip install -e .
```
Эта команда создает папкуcovid_analysis.egg-info, содержащую сведения о скомпилированной версии файлов covid_analysis/__init__.py и covid_analysis/transforms.py.
Запустите тесты, выполнив следующую команду:
```
pytest tests/
```
Результаты тестов отображаются в терминале. Все четыре теста должны отображаться как пройденные.

Совет

Дополнительные подходы к тестированию, включая тестирование записных книжек R и Scala, см. в разделе Модульное тестирование записных книжек.
При необходимости получите метрики объема протестированного кода для тестов, выполнив следующую команду:
```
coverage run -m pytest tests/
```
Примечание.

Если отображается сообщение о том, что не удается найти coverage, запустите pip install coverage и повторите попытку.

Чтобы просмотреть результаты, касающиеся объема протестированного кода, выполните следующую команду:
```
coverage report -m
```
Если все четыре теста пройдены, отправьте содержимое проекта dbx в рабочую область Azure Databricks, выполнив следующую команду:
```
dbx deploy --environment=default
```
Сведения о проекте и его запусках отправляются в расположение, указанное в объекте workspace_directory в файле .dbx/project.json.

Содержимое проекта отправляется в расположение, указанное в объекте artifact_location в файле .dbx/project.json.
Запустите предварительную версию кода в рабочей области, выполнив следующую команду:
```
dbx launch covid_analysis_etl_integ
```
Ссылка на результаты выполнения отображается в терминале. Должно отобразиться примерно следующее:
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345
```
Чтобы просмотреть результаты выполнения в рабочей области, перейдите по этой ссылке в веб-браузере.
Запустите рабочую версию кода в рабочей области, выполнив следующую команду:
```
dbx launch covid_analysis_etl_prod
```
Ссылка на результаты выполнения отображается в терминале. Должно отобразиться примерно следующее:
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456
```
Чтобы просмотреть результаты выполнения в рабочей области, перейдите по этой ссылке в веб-браузере.

Запуск с помощью GitHub Actions

В папке .github/workflows проекта файлы onpush.yml и onrelease.yml GitHub Actions выполняют следующие действия.

При каждой отправке в тег, начинающийся с v, используется dbx для развертывания задания covid_analysis_etl_prod.
В каждой отправке, которая не является тегом, начинающимся с v:
1. используется pytest для выполнения модульных тестов;
2. используется dbx для развертывания файла, указанного в задании covid_analysis_etl_integ, в удаленной рабочей области;
3. используется dbx для запуска уже развернутого файла, указанного в задании covid_analysis_etl_integ, в удаленной рабочей области, при этом до завершения выполнения осуществляется его трассировка.

Примечание.

Дополнительный файл GitHub Actions databricks_pull_request_tests.yml предоставляется в качестве шаблона для экспериментирования без влияния на файлы onpush.yml и onrelease.yml GitHub Actions. Этот пример кода можно запустить без файла databricks_pull_request_tests.yml GitHub Actions. Его использование в этой статье не описывается.

В следующих подразделах описано, как настроить и запустить файлы onpush.yml и onrelease.yml GitHub Actions.

Настройка для использования GitHub Actions

Настройте рабочую область Azure Databricks, выполнив инструкции в статье Субъекты-службы для CI/CD. Для этого необходимо выполнить следующие действия.

Создание субъекта-службы.
Создайте маркер идентификатора Microsoft Entra для субъекта-службы.

В качестве рекомендации по обеспечению безопасности Databricks рекомендуется использовать маркер идентификатора Microsoft Entra для субъекта-службы вместо маркера личного доступа Databricks для пользователя рабочей области, чтобы включить проверку подлинности GitHub в рабочей области Azure Databricks.

После создания субъекта-службы и его маркера идентификатора Microsoft Entra, остановите и запишите значение маркера идентификатора Microsoft Entra, которое вы будете использовать в следующем разделе.

Запуск GitHub Actions

Шаг 1. Публикация клонированного репозитория

В Visual Studio Code на боковой панели щелкните значок GitHub. Если значок не отображается, сначала включите расширение запросов на вытягивание и сообщений о проблемах GitHub в представлении Расширения (Представление > Расширения).
Если кнопка Войти отображается, нажмите ее и следуйте инструкциям на экране, чтобы войти в учетную запись GitHub.
В строке меню щелкните Вид > Палитра команд, введите Publish to GitHub и выберите Опубликовать в GitHub.
Выберите вариант публикации клонированного репозитория в учетной записи GitHub.

Шаг 2. Добавление зашифрованных секретов в репозиторий

На веб-сайте GitHub для опубликованного репозитория следуйте инструкциям в разделе Создание зашифрованных секретов для репозитория для следующих зашифрованных секретов:

Создайте зашифрованный секрет с именем DATABRICKS_HOST и значением URL-адреса для каждой рабочей области, например, https://adb-1234567890123456.7.azuredatabricks.net.
Создайте зашифрованный секрет с именем DATABRICKS_TOKEN, задайте значение маркера идентификатора Microsoft Entra для субъекта-службы.

Шаг 3. Создание и публикация ветви в репозитории

В Visual Studio Code в представлении Система управления версиями (Представление > Система управления версиями) щелкните значок ... (Представления и другие действия).
Щелкните Ветвь > Создать ветвь на основе.
Укажите имя для ветви, например my-branch.
Выберите ветвь, на основе которой будет создана новая ветвь, например, main.
Внесите незначительное изменение в один из файлов в локальном репозитории, а затем сохраните файл. Например, внесите незначительное изменение в комментарий кода в файле tests/transforms_test.py.
В представлении Система управления версиями снова щелкните значок ... (Представления и другие действия).
Щелкните Изменения > Подготовить все изменения.
Еще раз щелкните значок ... (Представления и другие действия).
Щелкните Зафиксировать > Фиксация подготовлена.
Введите сообщение для фиксации.
Еще раз щелкните значок ... (Представления и другие действия).
Щелкните Ветвь > Опубликовать ветвь.

Шаг 4. Создание запроса на вытягивание и слияние

Перейдите на веб-сайт GitHub для опубликованного репозитория https://github/<your-GitHub-username>/ide-best-practices.
На вкладке "Запросы на вытягивание" рядом с моей ветвью были последние отправки, нажмите кнопку "Сравнить" и "Запрос на вытягивание".
Нажмите кнопку "Создать запрос на вытягивание".
На странице запроса на вытягивание дождитесь, когда на месте значка рядом с Конвейер CI / ci-pipeline (отправка) появится зеленая галочка. (На появление значка может потребоваться несколько секунд или минут.) Если вместо зеленой галочки отображается красный значок X, щелкните Сведения, чтобы определить причину. Если значок или Сведения больше не отображаются, щелкните Показать все проверки.
Если отобразится зеленая галочка, добавьте запрос на вытягивание в ветвь main, щелкнув Объединить запрос на вытягивание.

Поделиться через

Использование dbx с Visual Studio Code

Требования к примеру кода

Сведения о примере кода

Запуск примера кода

Шаг 1. Создание виртуального окружения Python

Шаг 2. Клонирование примера кода из GitHub

Шаг 3. Установка зависимостей примера кода

Шаг 4. Настройка примера кода для рабочей области Azure Databricks

Изучение примера кода

Модулирование кода

Немодульный код

Модульный код

Тестирование

Модульные тесты

Средство выполнения модульных тестов

Упаковка

Другие файлы

Запуск примера кода

Запуск с помощью dbx

Запуск с помощью GitHub Actions

Настройка для использования GitHub Actions

Запуск GitHub Actions

Шаг 1. Публикация клонированного репозитория

Шаг 2. Добавление зашифрованных секретов в репозиторий

Шаг 3. Создание и публикация ветви в репозитории

Шаг 4. Создание запроса на вытягивание и слияние

Обратная связь

Дополнительные ресурсы