Лучшие методики программной инженерии для записных книжек

В этой статье приведены практические пошаговые инструкции по применению лучших методик программной инженерии к записным книжкам Azure Databricks, включая управление версиями, обмен кодом, тестирование, а также, при необходимости, непрерывную интеграцию и деплоймент или развертывание (CI/CD).

В этом пошаговом руководстве описаны следующие операции.

• Добавьте записные книжки в папки Azure Databricks Git для управления версиями.
• Извлечение фрагментов кода из одной из записных книжек в общий модуль.
• Тестирование общего кода.
• Запустите записные книжки в задании Azure Databricks.
• Опционально примените CI/CD к общему коду.

Требования

Для работы с этим пошаговым руководством необходимо предоставить следующие ресурсы:

• Удаленный репозиторий с поставщиком Git, поддерживаемым Databricks. В этом пошаговом руководстве используется GitHub. В этом пошаговом руководстве предполагается, что у вас есть репозиторий GitHub с именем best-notebooks. (Вы можете присвоить репозиторию другое имя. Если вы это сделаете, замените best-notebooks на имя вашего репо в этом пошаговом руководстве.) Создайте репозиторий GitHub, если он у вас еще нет.

  Примечание.

  Если вы создаете новый репозиторий, не забудьте инициализировать репозиторий, добавив в него по крайней мере один файл, например, файл README.

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

• Универсальный кластер Azure Databricks в рабочей области. Чтобы запускать ноутбуки на этапе проектирования, вам нужно подключить их к работающему универсальному кластеру. Далее в этом пошаговом руководстве используется задание Azure Databricks для автоматизации выполнения записных книжек в этом кластере. (Можно также запускать задания в кластерах заданий , которые существуют только для времени существования заданий.) Создайте кластер всех целей , если у вас еще нет этого кластера.

Шаг 1. Настройка папок Databricks Git

На этом шаге вы подключите существующий репозиторий GitHub к папкам Azure Databricks Git в существующей рабочей области Azure Databricks.

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

Шаг 1.1. Предоставление учетных данных GitHub

1. Нажмите на ваше имя пользователя в правом верхнем углу рабочей области, затем выберите Параметры из выпадающего списка.
2. На боковой панели "Параметры " в разделе "Пользователь" щелкните "Связанные учетные записи".
3. В разделе Git интеграции, для поставщикаGit выберите GitHub.
4. Щелкните персональный токен доступа.
5. Для параметра Git provider username or email (Имя пользователя или адрес электронной почты поставщика Git) введите свое имя пользователя GitHub.
6. Для токена введите личный токен доступа GitHub (классический). Этот личный токен доступа (классический) должен иметь права репозитория и рабочего процесса.
7. Нажмите кнопку Сохранить.

Шаг 1.2. Подключение к репозиторию GitHub

1. На боковой панели рабочей области щелкните "Рабочая область".
2. В браузере Workspace разверните Workspace > Пользователи.
3. Щелкните правой кнопкой мыши папку имени пользователя и выберите команду "Создать > папку Git".
4. В диалоговом окне «Создать папку Git»
   1. Для параметра Git repository URL (URL-адрес репозитория Git) введите URL-адрес клонирования с использованием HTTPS для своего репозитория GitHub. В этой статье предполагается, что URL-адрес заканчивается на best-notebooks.git, например https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. Для поставщика Gitвыберите GitHub.
   3. Оставьте имя папки Git установленным на имя вашего репозитория, например best-notebooks.
   4. Щелкните "Создать папку Git".

Шаг 2. Импорт и выполнение ноутбука

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

Шаг 2.1. Создание рабочей ветви в репозитории

На этом шаге вы создадите ветвь с именем eda в репозитории. Эта ветвь позволяет работать с файлами и кодом независимо от ветви репозитория main , что является рекомендациями по проектированию программного обеспечения. (Вы можете присвоить ветви другое имя.)

1. Папка Git из шага 1.2 должна быть открыта. Если нет, разверните на боковой панели Рабочей области узел >, затем разверните папку с вашим именем пользователя и выберите папку Git.

2. Рядом с именем папки под навигационной цепочкой рабочей области нажмите кнопку основной ветви Git.

3. В диалоговом окне best-notebooks нажмите кнопку Создать ветвь.

   Примечание.

   Если у вашего репозитория имя, отличное от best-notebooks, то заголовок этого диалогового окна будет другим здесь и во всем этом пошаговом руководстве.

4. Введите edaи нажмите кнопку "Создать".

5. Закройте диалоговое окно.

Шаг 2.2. Импорт записной книжки в репозиторий

На этом шаге вы импортируете существующую записную книжку из другого репозитория в свой репозиторий. Эта записная книжка делает следующее:

• Копирует CSV-файл из репозитория GitHub owid/covid-19-data в кластер в рабочей области. Этот CSV-файл содержит общедоступные данные о госпитализациях и метриках интенсивной терапии, связанных с COVID-19, со всего мира.
• Считывает содержимое CSV-файла в pandasDataFrame.
• Фильтрует данные для включения метрик только из США.
• Отображает график данных.
• Сохраняет pandas DataFrame как Pandas API на SparkDataFrame.
• Выполняет очистку данных в DataFrame на Spark, используя API Pandas.
• Записывает API Pandas на DataFrame Spark в виде таблицы Delta в вашей рабочей области.
• Отображает содержимое таблицы Delta.

Хотя вы можете здесь создать собственную записную книжку в репозитории, импорт существующей записной книжки вместо этого помогает ускорить это пошаговое объяснение. Чтобы создать записную книжку в этой ветви или переместить существующую записную книжку в эту ветвь вместо импорта записной книжки, см . основные сведения об использовании файлов рабочей области.

1. В папке Git с лучшими записными книжками нажмите кнопку "Создать > папку".

2. В диалоговом окне "Создать папку" введите notebooksи нажмите кнопку "Создать".

3. В папке записных книжек щелкните кебаб, а затем импортируйте.

4. В диалоговом окне Импорт:

   1. Для импорта извыберите URL.

   2. Введите URL-адрес для необработанного содержимого записной книжки covid_eda_raw в репозитории databricks/notebook-best-practices на сайте GitHub. Чтобы получить этот URL-адрес: i. Перейдите к https://github.com/databricks/notebook-best-practices. ii. Щелкните папку notebooks. iii Щелкните файл covid_eda_raw.py. iv. Щелкните Raw. в. Скопируйте полный URL-адрес из адресной строки веб-браузера в диалоговое окно импорта .

      Примечание.

      Диалоговое окно импорта работает с URL-адресами Git только для общедоступных репозиториев.

   3. Нажмите кнопку Импорт.

Шаг 2.3. Запуск записной книжки

1. Если записная книжка еще не отображается, откройте папку записных книжек и щелкните записную книжку covid_eda_raw внутри папки.
2. Выберите кластер, чтобы присоединить к нему эту записную книжку. Инструкции по созданию кластера см. в разделе "Создание кластера".
3. Щелкните Run All (Выполнить все).
4. Ожидайте, пока завершится работа записной книжки.

После завершения работы записной книжки вы увидите данные в виде графика, а также более 600 строк необработанных данных в таблице Delta. Если кластер еще не работал на момент запуска этой записной книжки, на его запуск и отображение результатов может потребоваться несколько минут.

Шаг 2.4. Синхронизация и объединение записной книжки

На этом шаге вы сохраните свою работу в репозитории GitHub. Затем вы объединяете ноутбук из рабочей ветки в ветку репозитория main.

1. Рядом с именем записной книжки нажмите кнопку Git ветка eda.
2. В диалоговом окне best-notebooks на вкладке Changes (Изменения) убедитесь, что выбран файл notebooks/covid_eda_raw.py.
3. Для сообщения о фиксации (обязательно)введите Added raw notebook.
4. Для параметра Description (optional) (Описание (необязательно)) введите This is the first version of the notebook..
5. Нажмите Зафиксировать и Отправить.
6. Щелкните ссылку на pull request в Создать pull request на вашем git-провайдере в баннере.
7. В GitHub создайте pull request, а затем объедините pull request в ветку main.
8. Вернитесь в рабочую область Azure Databricks и закройте диалоговое окно best-notebooks, если оно еще отображается.

Шаг 3. Перемещение кода в общий модуль

На этом шаге вы переместите некоторый код из вашей записной книжки в набор общих функций за её пределами. Это позволит использовать эти функции с другими аналогичными записными книжками, что ускорит написание кода в будущем и обеспечит дополнительную предсказуемость и согласованность результатов записных книжек. Совместное использование этого кода также упрощает тестирование этих функций, что является лучшей методикой программной инженерии и повышает общее качество кода.

Шаг 3.1. Создание другой рабочей ветви в репозитории

1. Рядом с именем записной книжки нажмите кнопку ветка Git «eda».
2. В диалоговом окне лучшие ноутбуки щелкните стрелку раскрывающегося списка рядом с ветвью eda и выберите main.
3. Нажмите кнопку Pull. Если появится запрос на извлечение, нажмите Confirm (Подтвердить).
4. Нажмите кнопку "Создать ветвь ".
5. Введите first_modulesи нажмите кнопку "Создать". (Вы можете присвоить ветви другое имя.)
6. Закройте диалоговое окно.

Шаг 3.2. Импорт записной книжки в репозиторий

Чтобы ускорить работу с этим пошаговым руководством, на этом шаге вы импортируете в репозиторий другую существующую записную книжку. Эта записная книжка выполняет те же действия, что и предыдущая записная книжка, за исключением того, что она вызывает функции общего кода, хранящиеся за пределами записной книжки. Опять же, вы можете создать собственную записную книжку в репозитории здесь и самостоятельно предоставить общий доступ к коду.

1. В браузере рабочей области щелкните правой кнопкой мыши папку notebooks и нажмите Импорт.

2. В диалоговом окне Импорта :

   1. Для импорта извыберите URL.

   2. Введите URL-адрес для необработанного содержимого записной книжки covid_eda_modular в репозитории databricks/notebook-best-practices на сайте GitHub. Чтобы получить этот URL-адрес: i. Перейдите к https://github.com/databricks/notebook-best-practices. ii. Щелкните папку notebooks. iii Щелкните файл covid_eda_modular.py. iv. Щелкните Raw. в. Скопируйте полный URL-адрес из адресной строки веб-браузера в диалоговое окно импорта записных книжек .

      Примечание.

      Диалоговое окно Импорт записных книжек работает с URL-адресами Git только для общедоступных репозиториев.

   3. Нажмите кнопку Импорт.

Шаг 3.3. Добавление вспомогательных функций общего кода записной книжки

1. В браузере рабочей области щелкните правой кнопкой мыши папку Git best-notebooks и выберите Создать > папку.

2. В диалоговом окне "Создать папку" введите covid_analysisи нажмите кнопку "Создать".

3. В папке covid_analysis нажмите кнопку "Создать > файл".

4. В диалоговом окне New File Name (Имя нового файла) введите transforms.py и щелкните Create File (Создать > Файл).

5. В окне редактора transforms.py введите следующий код:

   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
   

Шаг 3.4. Добавление зависимостей общего кода

Предыдущий код имеет несколько зависимостей пакета Python для правильного выполнения кода. На этом этапе вы указываете зависимости этих пакетов. Объявление зависимостей улучшает воспроизводимость благодаря точно определенным версиям библиотек.

1. В браузере рабочей области щелкните правой кнопкой мыши на папке Git "best-notebooks", затем нажмите «Создать > файл».

   Примечание.

   Вы хотите, чтобы файл, где перечислены зависимости пакетов, был помещен в корневой каталог репозитория Git, а не в папку notebooks или covid_analysis.

2. В диалоговом окне New File Name (Имя нового файла) введите requirements.txt и щелкните Create File (Создать > Файл).

3. В окне редактора requirements.txt введите следующий код:

   Примечание.

   Если файл requirements.txt не отображается, может потребоваться обновить веб-браузер.

   -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
   

   Примечание.

   В предыдущем файле приведены определенные версии пакетов. Для повышения совместимости вы можете сравнить эти версии с теми, которые установлены в универсальном кластере. См. раздел "Системная среда" для версии Databricks Runtime вашего кластера в заметках о выпусках Databricks Runtime и совместимости.

Структура репозитория должна выглядеть так, как показано здесь:

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

Шаг 3.5: Запустите рефакторизованный ноутбук

На этом подэтапе вы запускаете ноутбук covid_eda_modular, который вызывает общий код в covid_analysis/transforms.py.

1. В браузере рабочей области щелкните ноутбук covid_eda_modular в папке ноутбуков.
2. Выберите кластер, чтобы присоединить к нему эту записную книжку.
3. Щелкните Run All (Выполнить все).
4. Ожидайте, пока завершится работа записной книжки.

После завершения работы записной книжки вы должны увидеть результаты, аналогичные тем, что в записной книжке covid_eda_raw: график данных, а также более 600 строк необработанных данных в таблице Delta. Основное отличие этой записной книжки заключается в том, что в ней используется другой фильтр (iso_codeDZA вместо USA). Если кластер еще не работал на момент запуска этой записной книжки, на его запуск и отображение результатов может потребоваться несколько минут.

Шаг 3.6. Синхронизация записной книжки и связанного кода

1. Рядом с именем записной книжки нажмите на кнопку ветки Git first_modules.
2. В диалоговом окне "Лучшие записные книжки" на вкладке "Изменения" убедитесь в выборе следующего:
   • requirements.txt
   • covid_analysis/transforms.py
   • ноутбуки/covid_eda_modular.py
3. Для сообщения о фиксации (обязательно)введите Added refactored notebook.
4. Для параметра Description (optional) (Описание (необязательно)) введите This is the second version of the notebook..
5. Нажмите Зафиксировать и Отправить.
6. Щелкните ссылку на pull request в Создать pull request на вашем git-провайдере в баннере.
7. В GitHub создайте pull request, а затем объедините pull request в ветку main.
8. Вернитесь в рабочую область Azure Databricks и закройте диалоговое окно best-notebooks, если оно еще отображается.

Шаг 4. Тестирование общего кода

На этом шаге вы протестируете общий код с последнего шага. Но вам нужно протестировать этот код без выполнения самой записной книжки covid_eda_modular. Это связано с тем, что если общий код не запустится, записная книжка с большой вероятностью также не будет выполнена. Вы хотите сначала выявить сбои в общем коде, прежде чем в конечном итоге выйти из строя основная записная книжка. Этот метод тестирования — это лучшая методика программной инженерии.

Шаг 4.1. Создание другой рабочей ветви в репозитории

1. Рядом с именем записной книжки нажмите кнопку ветви Git first_modules.
2. В диалоговом окне best-notebooks щелкните стрелку раскрывающегося списка рядом с ветвью first_modules и выберите main.
3. Нажмите кнопку Pull. Если появится запрос на извлечение, нажмите Confirm (Подтвердить).
4. Щелкните Создать ветвь.
5. Введите first_testsи нажмите кнопку "Создать". (Вы можете присвоить ветви другое имя.)
6. Закройте диалоговое окно.

Шаг 4.2. Добавление тестов

На этом шаге вы воспользуетесь платформой pytest, чтобы протестировать общий код. С помощью этих тестов вы проверяете, получены ли определенные результаты. Если какой-либо тест выдает непредвиденный результат, этот конкретный тест не проходит проверку, и поэтому сам тест проваливается.

1. В обозревателе рабочей области щелкните правой кнопкой мыши на папке Git, затем выберите >.

2. В диалоговом окне "Создать папку" введите testsи нажмите кнопку "Создать".

3. В папке тестов нажмите кнопку "Создать > файл".

4. В диалоговом окне New File Name (Имя нового файла) введите testdata.csv и щелкните Create File (Создать > Файл).

5. В окне редактора testdata.csv введите следующие тестовые данные:

   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. В папке тестов нажмите кнопку "Создать > файл".

7. В диалоговом окне New File Name (Имя нового файла) введите transforms_test.py и щелкните Create File (Создать > Файл).

8. В окне редактора transforms_test.py введите следующий тестовый код. Эти тесты используют стандартные pytestфикстуры, а также макет в памяти при помощи pandas DataFrame.

   # 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()
   

Структура репозитория должна выглядеть так, как показано здесь:

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

Шаг 4.3. Выполнение тестов

Чтобы ускорить работу с этим пошаговым руководством, в этом шаге вы воспользуетесь импортированной записной книжкой для выполнения предыдущих тестов. Эта записная книжка загружает и устанавливает зависимые от тестов пакеты Python в рабочую область, выполняет тесты и сообщает результаты тестов. Хотя вы можете запустить pytest из веб-терминала вашего кластера, выполнение pytest из записной книжки может быть более удобным.

1. В браузере рабочей области щелкните правой кнопкой мыши папку notebooks и нажмите Импорт.

2. В диалоговом окне импорта записных книжек :

   1. Для импорта извыберите URL.

   2. Введите URL-адрес для необработанного содержимого записной книжки run_unit_tests в репозитории databricks/notebook-best-practices на сайте GitHub. Чтобы получить этот URL-адрес: i. Перейдите к https://github.com/databricks/notebook-best-practices. ii. Щелкните папку notebooks. iii Щелкните файл run_unit_tests.py. iv. Щелкните Raw. в. Скопируйте полный URL-адрес из адресной строки веб-браузера в диалоговое окно импорта записных книжек .

      Примечание.

      Диалоговое окно Импорт записных книжек работает с URL-адресами Git только для общедоступных репозиториев.

   3. Нажмите кнопку Импорт.

3. Выберите кластер, чтобы присоединить к нему эту записную книжку.

4. Щелкните Run All (Выполнить все).

5. Ожидайте, пока завершится работа записной книжки.

После завершения работы записной книжки в ней отобразятся сведения о количестве пройденных и неудачных тестов, а также другие связанные подробности. Если кластер еще не работал на момент запуска этой записной книжки, на его запуск и отображение результатов может потребоваться несколько минут.

Структура репозитория должна выглядеть так, как показано здесь:

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

Шаг 4.4. Проверка записной книжки и связанных тестов

1. Рядом с именем записной книжки нажмите кнопку ветки Git first_tests.
2. В диалоговом окне "Лучшие записные книжки" на вкладке "Изменения" убедитесь в выборе следующего:
   • test/transforms_test.py
   • notebooks/run_unit_tests.py
   • test/testdata.csv
3. Для сообщения о фиксации (обязательно)введите Added tests.
4. Для параметра Описание (необязательно) введите These are the unit tests for the shared code..
5. Нажмите Зафиксировать и Отправить.
6. Щелкните ссылку на pull request в Создать pull request на вашем git-провайдере в баннере.
7. В GitHub создайте pull request, а затем объедините pull request в ветку main.
8. Вернитесь в рабочую область Azure Databricks и закройте диалоговое окно best-notebooks, если оно еще отображается.

Шаг 5. Создание задания для выполнения записных книжек

На предыдущих этапах вы вручную протестировали общий код и запустили свои ноутбуки вручную. На этом шаге вы воспользуетесь заданием Azure Databricks для тестирования общего кода и автоматического выполнения записных книжек по запросу или по расписанию.

Шаг 5.1. Создание задачи для запуска тестового блокнота

1. На боковой панели рабочей области щелкните "Рабочие процессы".
2. На вкладке Jobs (Задания) щелкните Create Job (Создать задание).
3. Измените имя задания на covid_report.
4. Для параметра Task name (Имя задачи) введите run_notebook_tests.
5. Для типавыберите Записная книжка.
6. Для источникавыберите поставщик Git.
7. Щелкните Добавить ссылку на git.
8. В диалоговом окне сведений Git:
   1. Для параметра Git repository URL (URL-адрес репозитория Git) введите URL-адрес клонирования с использованием HTTPS для своего репозитория GitHub. В этой статье предполагается, что URL-адрес заканчивается на best-notebooks.git, например https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. Для поставщика Gitвыберите GitHub.
   3. Для параметра Git reference (branch / tag / commit) (Ссылка Git (ветвь/тег/фиксация)) введите main.
   4. Рядом со ссылкой на Git (branch/tag/commit)выберите ветку.
   5. Нажмите кнопку Подтвердить.
9. Для параметра Path (Путь) введите notebooks/run_unit_tests. Не добавляйте расширение файла .py.
10. Для кластеравыберите кластер на предыдущем шаге.
11. Нажмите Создать задачу.

Шаг 5.2. Создание задачи для выполнения основной записной книжки

1. Щелкните значок +Добавить задачу.
2. Откроется контекстное меню. Выберите Записная книжка.
3. Для параметра Task name (Имя задачи) введите run_main_notebook.
4. Для типавыберите Записная книжка.
5. Для параметра Path (Путь) введите notebooks/covid_eda_modular. Не добавляйте расширение файла .py.
6. Для кластеравыберите кластер на предыдущем шаге.
7. Убедитесь, что значение Depends on равно run_notebook-tests.
8. Нажмите Создать задачу.

Шаг 5.3. Выполнение задания

1. Щелкните Запустить сейчас.

2. Во всплывающем окне щелкните Просмотр выполнения.

   Примечание.

   Если всплывающее окно исчезнет слишком быстро, сделайте следующее:

   1. На боковой панели в среде Обработка и анализ данных и инженерии или Databricks Mosaic AI щелкните "Рабочие процессы".
   2. На вкладке Запуски заданий щелкните на значении времени начала для последнего задания с covid_report в столбце Задания.

3. Чтобы просмотреть результаты задания, щелкните плитку run_notebook_tests, плитку run_main_notebook или обе из них. Результаты на каждой плитке будут такими же, как если бы вы запускали блокноты поочередно.

(Необязательно) Шаг 6. Настройка репозитория для тестирования кода и автоматического запуска записной книжки при изменении кода

На предыдущем шаге вы использовали задачу для автоматического тестирования вашего общего кода и запуска записных книжек в определенный момент времени или на регулярной основе. Однако вы можете автоматически активировать тесты, если изменения объединяются в репозиторий GitHub, используя средство CI/CD, например GitHub Actions.

Шаг 6.1. Настройка доступа GitHub к рабочей области

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

По соображениям безопасности Databricks не рекомендует предоставлять личный маркер доступа пользователя рабочей области Azure Databricks на GitHub. Вместо этого Databricks рекомендует предоставить GitHub токен Microsoft Entra ID, связанный с сервис-принципалом Microsoft Entra ID. См. инструкции в разделе Azure на странице Выполнение действия GitHub для запуска записной книжки Databricks в GitHub Actions Marketplace.

Шаг 6.2. Добавление рабочего процесса GitHub Actions

На этом шаге вы добавите рабочий процесс GitHub Actions для запуска записной книжки run_unit_tests при каждом запросе на вытягивание в репозиторий.

Этот шаг сохраняет рабочий процесс GitHub Actions в файле, который хранится на нескольких уровнях папок в репозитории GitHub. Для правильной работы GitHub Actions требуется определенная иерархия вложенных папок в репозитории. Чтобы выполнить этот шаг, необходимо использовать веб-сайт для репозитория GitHub, так как пользовательский интерфейс папки Azure Databricks Git не поддерживает создание вложенных иерархий папок.

1. На веб-сайте репозитория GitHub перейдите на вкладку Code (Код).

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

3. В поле Find or create a branch (Найти или создать ветвь) введите adding_github_actions.

4. Нажмите «Создать ветвь»: adding_github_actions от 'main'.

5. Щелкните Add file > Create new file (Добавить файл > Создать файл).

6. Для параметра Name your file (Имя файла) введите .github/workflows/databricks_pull_request_tests.yml.

7. В окне редактора введите следующий код. Этот код использует хук pull_request из действия Run Databricks Notebook GitHub для запуска ноутбука run_unit_tests.

   В коде ниже замените следующее:

   • <your-workspace-instance-URL> с именем экземпляра Azure Databricks.
   • <your-access-token> с токеном, который вы создали ранее.
   • <your-cluster-id> с целевым идентификатором кластера.

   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. Щелкните Зафиксировать изменения.

9. В диалоговом окне "Фиксация изменений" введите Create databricks_pull_request_tests.ymlсообщение фиксации

10. Выберите Коммит непосредственно на ветку adding_github_actions и нажмите Закоммитить изменения.

11. На вкладке "Код" нажмите кнопку "Сравнить" и " Запрос на вытягивание", а затем создайте запрос на вытягивание.

12. На странице пулл-реквеста подождите, пока символ Run pre-merge Databricks tests / unit-test-notebook (pull_request) не покажет зеленую галочку. (На появление значка может потребоваться несколько секунд.) Если вместо зеленой галочки отображается красный значок X, щелкните Details (Сведения), чтобы определить причину. Если значок или Сведения больше не отображаются, щелкните Показать все проверки.

13. Если отобразится зеленая галочка, добавьте запрос на вытягивание в ветвь main.

(Необязательно) Шаг 7. Обновление общего кода в GitHub для активации тестов

На этом шаге вы вносите изменения в общий код, а затем отправляете изменения в репозиторий GitHub, который немедленно активирует тесты автоматически на основе действия GitHub на предыдущем шаге.

Шаг 7.1. Создание другой рабочей ветви в репозитории

1. В браузере рабочей области откройте папку Git с лучшими записными книжками .
2. Нажмите кнопку ветки Git first_tests, расположенную рядом с именем папки.
3. В диалоговом окне best-notebooks щелкните стрелку раскрывающегося списка рядом с ветвью first_tests и выберите main.
4. Нажмите кнопку Pull. Если появится запрос на извлечение, нажмите Confirm (Подтвердить).
5. Нажмите кнопку + (Создать ветвь).
6. Введите trigger_testsи нажмите кнопку "Создать". (Вы можете присвоить ветви другое имя.)
7. Закройте диалоговое окно.

Шаг 7.2. Изменение общего кода

1. В браузере рабочей области в папке best-notebooks щелкните на файл covid_analysis/transforms.py.

2. Измените третью строку этого файла:

   # Filter by country code.
   

   На эту:

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

Шаг 7.3. Проверка изменений для активации тестов

1. Рядом с именем файла нажмите кнопку trigger_tests ветви Git.
2. В диалоговом окне best-notebooks на вкладке Changes (Изменения) убедитесь, что выбран файл covid_analysis/transforms.py.
3. Для сообщения о фиксации (обязательно)введите Updated comment.
4. Для параметра Description (optional) (Описание (необязательно)) введите This updates the comment for filter_country..
5. Нажмите Зафиксировать и Отправить.
6. Щелкните ссылку на pull request в Create a pull request on your git provider в баннере, а затем создайте pull request в GitHub.
7. На странице пулл-реквеста подождите, пока символ Run pre-merge Databricks tests / unit-test-notebook (pull_request) не покажет зеленую галочку. (На появление значка может потребоваться несколько секунд.) Если вместо зеленой галочки отображается красный значок X, щелкните Details (Сведения), чтобы определить причину. Если значок или Сведения больше не отображаются, щелкните Показать все проверки.
8. Если отобразится зеленая галочка, добавьте запрос на вытягивание в ветвь main.