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

В этой статье приведены практические пошаговые инструкции по применению лучших методик программной инженерии к записным книжкам 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. В браузере >".
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, что является лучшей методикой программной инженерии. (Вы можете присвоить ветви другое имя.)

Примечание.

В некоторых репозиториях ветвь main может иметь имя master. Если это так, замените main на master на протяжении всего руководства.

Совет

Если вы не знаете, как работать с ветвями Git, см. раздел Ветви Git — коротко о ветвях на веб-сайте Git.

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

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

3. В диалоговом окне "Лучшие записные книжки" нажмите кнопку "Создать ветвь ".

   Примечание.

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

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

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

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

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

• Копирует CSV-файл из репозитория GitHub owid/covid-19-data в кластер в рабочей области. Этот CSV-файл содержит общедоступные данные о госпитализациях и метриках интенсивной терапии, связанных с COVID-19, со всего мира.
• Считывает содержимое CSV-файла в кадр данных pandas.
• Фильтрует данные для включения метрик только из США.
• Отображает график данных.
• Сохраняет кадр данных Pandas в виде API Pandas вSpark DataFrame.
• Выполняет очистку данных в кадре данных API Pandas в Spark.
• Записывает 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 (Необработанный). v. Скопируйте полный URL-адрес из адресной строки веб-браузера в диалоговое окно импорта.

      Примечание.

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

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

Шаг 2.3. Выполнение записной книжки

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

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

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

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

1. Рядом с именем записной книжки нажмите кнопку ветви eda Git.
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. Щелкните ссылку на запрос на вытягивание в разделе "Создание запроса на вытягивание" для поставщика Git в баннере.
7. В GitHub создайте запрос на вытягивание и объедините запрос на вытягивание в main ветвь.
8. Вернитесь в рабочую область Azure Databricks и закройте диалоговое окно best-notebooks, если оно еще отображается.

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

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

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

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

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

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

1. В браузере рабочей области щелкните правой кнопкой мыши папку записных книжек и нажмите кнопку "Импорт".
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 (Необработанный). v. Скопируйте полный URL-адрес из адресной строки веб-браузера в диалоговое окно Import Notebooks (Импорт записных книжек).

      Примечание.

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

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

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

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

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
   

Совет

Сведения о других методах совместного использования кода см. в статье "Общий доступ к коду между записными книжками Databricks".

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

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

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

   Примечание.

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

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

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

Совет

Дополнительные подходы к тестированию записных книжек, а также тестирование записных книжек R и Scala см. в разделе Модульное тестирование записных книжек.

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

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

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

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

1. В браузере рабочей области щелкните правой

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 из записной книжки более удобен.

Примечание.

При выполнении команды pytest выполняются все файлы в текущем каталоге и его подкаталогах, имена которых соответствуют форме test_*.py или /*_test.py.

1. В браузере рабочей области щелкните правой кнопкой мыши папку записных книжек и нажмите кнопку "Импорт".
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 (Необработанный). v. Скопируйте полный URL-адрес из адресной строки веб-браузера в диалоговое окно Import Notebooks (Импорт записных книжек).

      Примечание.

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

Примечание.

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

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

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

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

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

2. Во всплывающем окне щелкните View run (Просмотреть выполнение).

   Примечание.

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

   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 не рекомендует предоставлять GitHub личный маркер доступа пользователя рабочей области Azure Databricks. Вместо этого Databricks рекомендует предоставить GitHub маркер идентификатора Microsoft Entra ID, связанный с субъектом-службой Идентификатора Microsoft Entra. Инструкции см. в разделе для Azure на странице Действие GitHub для запуска записной книжки Databricks в GitHub Actions Marketplace.

Внимание

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

Шаг 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. Щелкните Create branch: adding_github_actions from "main" (Создать ветвь: 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) (Выполнение тестов Databricks перед объединением/unit-test-notebook (pull_request)) не отобразится зеленая галочка. (На появление значка может потребоваться несколько секунд.) Если вместо зеленой галочки отображается красный значок X, щелкните Details (Сведения), чтобы определить причину. Если значок или Сведения больше не отображаются, щелкните Показать все проверки.

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

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

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

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

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

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

1. В браузере рабочей области в папке Git лучшие записные книжки щелкните файл 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. Щелкните ссылку на запрос на вытягивание в приложении Create a pull request on your git provider in the баннер, а затем создайте запрос на вытягивание в GitHub.
7. На странице запроса на вытягивание подождите, пока рядом со значком Run pre-merge Databricks tests / unit-test-notebook (pull_request) (Выполнение тестов Databricks перед объединением/unit-test-notebook (pull_request)) не отобразится зеленая галочка. (На появление значка может потребоваться несколько секунд.) Если вместо зеленой галочки отображается красный значок X, щелкните Details (Сведения), чтобы определить причину. Если значок или Сведения больше не отображаются, щелкните Показать все проверки.
8. Если отобразится зеленая галочка, добавьте запрос на вытягивание в ветвь main.