Notebook에 대한 소프트웨어 엔지니어링 모범 사례

이 문서에서는 버전 제어, 코드 공유, 테스트 및 선택적으로 CI/CD(연속 통합 및 지속적인 업데이트 또는 배포)를 포함하여 Azure Databricks Notebook에 소프트웨어 엔지니어링 모범 사례를 적용하는 방법을 보여주는 실습 연습을 제공합니다.

이 연습에서는 다음을 수행합니다.

• 버전 제어를 위해 Azure Databricks Git 폴더에 Notebook을 추가합니다.
• Notebook 중 하나에서 코드 부분을 공유 가능한 모듈로 추출합니다.
• 공유 코드를 테스트합니다.
• Azure Databricks 작업에서 Notebook을 실행합니다.
• 필요에 따라 공유 코드에 CI/CD를 적용합니다.

요구 사항

이 연습을 완료하려면 다음 리소스를 제공해야 합니다.

• Git 공급자 Databricks가 지원하는 원격 리포지토리입니다. 이 문서의 연습에서는 GitHub를 사용합니다. 이 연습에서는 best-notebooks라는 GitHub 리포지토리를 사용할 수 있다고 가정합니다. (리포지토리에 다른 이름을 지정할 수 있습니다. 이 경우 이 연습 전체에서 best-notebooks를 리포지토리 이름으로 바꿉니다.) 아직 없는 경우 GitHub 리포지토리를 만듭니다.

  참고 항목

  새 리포지토리를 만드는 경우 하나 이상의 파일(예: README 파일)을 사용하여 리포지토리를 초기화해야 합니다.

• Azure Databricks 작업 영역. 아직 없는 경우 작업 영역을 만듭니다.

• 작업 영역의 Azure Databricks 다목적 클러스터. 디자인 단계에서 Notebook을 실행하려면 실행 중인 다목적 클러스터에 Notebook을 연결합니다. 나중에 이 연습에서는 Azure Databricks 작업을 사용하여 이 클러스터에서 Notebook 실행을 자동화합니다. (작업의 수명 동안만 존재하는 작업 클러스터에서 작업을 실행할 수도 있습니다.) 아직 없는 경우 다목적 클러스터를 만듭니다.

1단계: Databricks Git 폴더 설정

이 단계에서는 기존 GitHub 리포지토리를 기존 Azure Databricks 작업 영역의 Azure Databricks Git 폴더에 연결합니다.

작업 영역이 GitHub 리포지토리에 연결할 수 있도록 하려면 아직 수행하지 않은 경우 먼저 작업 영역에 GitHub 자격 증명을 제공해야 합니다.

1.1단계: GitHub 자격 증명 제공

1. 작업 영역의 오른쪽 위에 있는 사용자 이름을 클릭한 다음 드롭다운 목록에서 설정을 클릭합니다.
2. 설정 사이드바의 사용자에서 연결된 계정을 클릭합니다.
3. Git 통합 탭의 Git 공급자에서 GitHub를 선택합니다.
4. 개인용 액세스 토큰을 클릭합니다.
5. Git 공급자 사용자 이름 또는 이메일에서 GitHub 사용자 이름을 입력합니다.
6. 토큰에서 GitHub 개인용 액세스 토큰(클래식)을 입력합니다. 이 개인용 액세스 토큰(클래식)에는 리포지토리 및 워크플로 권한이 있어야 합니다.
7. 저장을 클릭합니다.

1.2단계: GitHub 리포지토리에 연결

1. 사이드바에서 작업 영역을 클릭합니다.
2. 작업 영역 브라우저에서 작업 영역 > 사용자를 확장합니다.
3. 사용자 이름 폴더를 마우스 오른쪽 버튼으로 클릭한 다음 > Git 폴더 만들기를 클릭합니다.
4. Git 폴더 만들기 대화 상자에서 다음을 수행합니다.
   1. Git 리포지토리 URL의 경우 GitHub 리포지토리의 GitHub HTTPS를 사용한 복제 URL을 입력합니다. 이 문서에서는 URL이 best-notebooks.git로 끝나는 것(예: https://github.com/<your-GitHub-username>/best-notebooks.git)으로 가정합니다.
   2. Git 공급자에서 GitHub를 선택합니다.
   3. Git 폴더 이름을 리포지토리 이름으로 설정합니다(예: best-notebooks).
   4. Git 폴더 만들기를 클릭합니다.

2단계: Notebook 가져오기 및 실행

이 단계에서는 기존 외부 Notebook을 리포지토리로 가져옵니다. 이 연습을 위해 고유한 Notebook을 만들 수 있지만 여기서는 시간 단축을 위해 기존 항목을 제공합니다.

2.1단계: 리포지토리에서 작업 분기 만들기

이 하위 단계에서는 리포지토리에 eda라는 분기를 만듭니다. 이 분기를 사용하면 소프트웨어 엔지니어링 모범 사례인 리포지토리 분기 main과 독립적으로 파일 및 코드를 작업할 수 있습니다. (분기에 다른 이름을 지정할 수 있습니다.)

참고 항목

일부 리포지토리에서는 main 분기 이름을 대신 master로 지정할 수 있습니다. 이 경우 이 연습 전체에서 main을 master로 바꿉니다.

팁

Git 분기에서 작업하는 데 익숙하지 않은 경우 Git 웹 사이트의 Git 분기 - 간단히 말해서 분기를 참조하세요.

1. 1.2단계의 Git 폴더가 열려 있어야 합니다. 그렇지 않은 경우 작업 영역 사이드바에서 작업 영역 > 사용자를 확장한 다음 사용자 이름 폴더를 확장하고 Git 폴더를 클릭합니다.

2. 작업 영역 탐색 이동 경로 아래의 폴더 이름 옆에 있는 기본 Git 분기 버튼을 클릭합니다.

3. best-notebooks 대화 상자에서 분기 만들기 버튼을 클릭합니다.

   참고 항목

   리포지토리의 이름이 best-notebooks와 다른 경우 이 연습 전체에서 이 대화 상자의 제목이 달라집니다.

4. eda을 입력하고 만들기를 클릭합니다.

5. 이 대화 상자를 닫습니다.

2.2단계: Notebook을 리포지토리로 가져오기

이 하위 단계에서는 다른 리포지토리의 기존 Notebook을 사용자의 리포지토리로 가져옵니다. 이 Notebook은 다음을 수행합니다.

• owid/covid-19 데이터 GitHub 리포지토리의 CSV 파일을 작업 영역의 클러스터에 복사합니다. 이 CSV 파일에는 전 세계의 코로나19 입원 및 집중 치료 메트릭에 대한 공개 데이터가 포함되어 있습니다.
• CSV 파일의 내용을 pandasDataFrame으로 읽어 들입니다.
• 미국의 메트릭만 포함하도록 데이터를 필터링합니다.
• 데이터의 플롯을 표시합니다.
• DataFrame을 Pandas API on SparkDataFrame으로 저장합니다.
• Spark의 Pandas API DataFrame에서 데이터 정리를 수행합니다.
• Spark의 Pandas API DataFrame을 작업 영역의 Delta 테이블로 기록합니다.
• Delta 테이블의 내용을 표시합니다.

리포지토리에 고유한 Notebook을 만들 수 있지만 대신 기존 Notebook을 가져오면 이 연습 시간이 단축됩니다. 이 분기에서 Notebook을 만들거나 기존 Notebook을 이 분기로 이동하는 대신 기존 Notebook을 가져오려면 작업 영역 파일 기본 사용량을 참조하세요.

1. best-notebooks Git 폴더에서 > 폴더 만들기를 클릭합니다.
2. 새 폴더 대화 상자에서 notebooks를 입력한 다음, 만들기를 클릭합니다.
3. notebooks 폴더에서 케밥을 클릭한 다음 가져오기를 클릭합니다.
4. 가져오기 대화 상자에서 다음을 수행합니다.

   1. 다음에서 가져오기에서 URL을 선택합니다.

   2. GitHub의 covid_eda_raw 리포지토리에 있는 databricks/notebook-best-practices Notebook의 원시 콘텐츠에 대한 URL을 입력합니다. 이 URL을 가져오려면 다음을 수행합니다. i. https://github.com/databricks/notebook-best-practices(으)로 이동합니다. ii. notebooks 폴더를 클릭합니다. iii. covid_eda_raw.py 파일을 클릭합니다. iv. 원시를 클릭합니다. v. 웹 브라우저의 주소 표시줄에 표시되는 전체 URL을 가져오기 대화 상자로 복사합니다.

      참고 항목

      가져오기 대화 상자는 공용 리포지토리에 대해서만 Git URL에서 작동합니다.

   3. 가져오기를 클릭합니다.

2.3단계: Notebook 실행

1. Notebook이 아직 표시되지 않는 경우 notebooks 폴더를 열고 폴더 내에 있는 covid_eda_raw Notebook을 클릭합니다.
2. 이 Notebook을 연결할 클러스터를 선택합니다. 클러스터를 만드는 방법에 대한 자세한 지침은 클러스터 만들기를 참조하세요.
3. 모두 실행을 클릭합니다.
4. Notebook이 실행되는 동안 기다립니다.

Notebook 실행이 완료되면 Notebook의 Delta 테이블에 600개 이상의 원시 데이터 행뿐만 아니라 데이터 플롯도 표시됩니다. 이 Notebook 실행을 시작할 때 클러스터가 아직 실행되고 있지 않은 경우 결과를 표시하기 전에 클러스터가 시작되는 데 몇 분 정도 걸릴 수 있습니다.

2.4단계: Notebook 체크 인 및 병합

이 하위 단계에서는 지금까지의 작업을 GitHub 리포지토리에 저장합니다. 그런 다음, 작업 분기의 Notebook을 리포지토리의 main 분기에 병합합니다.

1. 전자 필기장 이름 옆에 있는 eda Git 분기 버튼을 클릭합니다.
2. best-notebooks 대화 상자의 변경 내용 탭에서 notebooks/covid_eda_raw.py 파일이 선택되어 있는지 확인합니다.
3. 커밋 메시지(필수)에 Added raw notebook을 입력합니다.
4. 설명(선택 사항)에 This is the first version of the notebook.를 입력합니다.
5. 커밋 & 푸시를 클릭합니다.
6. 배너의 git 공급자에 대한 끌어오기 요청 만들기에서 끌어오기 요청 링크를 클릭합니다.
7. GitHub에서 끌어오기 요청을 만든 다음, 끌어오기 요청을 main 분기에 병합합니다.
8. Azure Databricks 작업 영역으로 돌아가서 best-notebooks 대화 상자를 닫습니다(여전히 표시되는 경우).

3단계: 코드를 공유 모듈로 이동

이 단계에서는 Notebook의 일부 코드를 Notebook 외부의 공유 함수 세트로 이동합니다. 이렇게 하면 이러한 함수를 다른 유사한 Notebook과 함께 사용할 수 있으므로 향후 코딩 속도를 높일 수 있으며 보다 예측 가능하고 일관된 Notebook 결과를 보장할 수 있습니다. 또한 이 코드를 공유하면 이러한 함수를 보다 쉽게 테스트할 수 있으며, 소프트웨어 엔지니어링 모범 사례로 코드의 전반적인 품질을 점차 높일 수 있습니다.

3.1단계: 리포지토리에서 또 다른 작업 분기 만들기

1. 전자 필기장 이름 옆에 있는 eda Git 분기 버튼을 클릭합니다.
2. best-notebooks 대화 상자에서 eda 분기 옆에 있는 드롭다운 화살표를 클릭하고 main을 선택합니다.
3. 끌어오기 단추를 클릭합니다. 끌어오기를 계속할지 묻는 메시지가 표시되면 확인을 클릭합니다.
4. 분기 만들기 버튼을 클릭합니다.
5. first_modules를 입력하고 만들기를 클릭합니다. (분기에 다른 이름을 지정할 수 있습니다.)
6. 이 대화 상자를 닫습니다.

3.2단계: Notebook을 리포지토리로 가져오기

이 연습의 시간을 단축하기 위해 이 하위 단계에서 다른 기존 Notebook을 리포지토리로 가져옵니다. 이 Notebook은 이전 Notebook과 동일한 작업을 수행합니다. 단, 이 Notebook은 Notebook 외부에 저장된 공유 코드 함수를 호출합니다. 다시 말하지만, 여기에서 리포지토리에 고유한 Notebook을 만들고 실제 코드 공유를 직접 수행할 수 있습니다.

1. 작업 영역 브라우저에서 notebooks 폴더를 마우스 오른쪽 버튼으로 클릭한 다음 가져오기를 클릭합니다.
2. 가져오기 대화 상자에서 다음을 수행합니다.

   1. 다음에서 가져오기에서 URL을 선택합니다.

   2. GitHub의 covid_eda_modular 리포지토리에 있는 databricks/notebook-best-practices Notebook의 원시 콘텐츠에 대한 URL을 입력합니다. 이 URL을 가져오려면 다음을 수행합니다. i. https://github.com/databricks/notebook-best-practices(으)로 이동합니다. ii. notebooks 폴더를 클릭합니다. iii. covid_eda_modular.py 파일을 클릭합니다. iv. 원시를 클릭합니다. v. 웹 브라우저의 주소 표시줄에 표시되는 전체 URL을 Notebook 가져오기 대화 상자로 복사합니다.

      참고 항목

      Notebook 가져오기 대화 상자는 공용 리포지토리에 대해서만 Git URL에서 작동합니다.

   3. 가져오기를 클릭합니다.

3.3단계: Notebook의 지원 공유 코드 함수 추가

1. 작업 영역 브라우저에서 best-notebooks Git 폴더를 마우스 오른쪽 버튼으로 클릭한 다음 > 폴더 만들기를 클릭합니다.

2. 새 폴더 대화 상자에서 covid_analysis를 입력한 다음, 만들기를 클릭합니다.

3. covid_analysis 폴더에서 > 파일 만들기를 클릭합니다.

4. 새 파일 이름 대화 상자에서 transforms.py를 입력한 다음, 파일 만들기를 클릭합니다.

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 Notebook 간에 코드 공유를 참조하세요.

3.4단계: 공유 코드의 종속성 추가

이전 코드에는 코드가 제대로 실행되도록 하는 몇 가지 Python 패키지 종속성이 있습니다. 이 하위 단계에서는 이러한 패키지 종속성을 선언합니다. 종속성을 선언하면 정확하게 정의된 버전의 라이브러리를 사용하여 재현성이 향상됩니다.

1. 작업 영역 브라우저에서 best-notebooks Git 폴더를 마우스 오른쪽 버튼으로 클릭한 다음 > 파일 만들기를 클릭합니다.

   참고 항목

   패키지 종속성 목록이 나열된 파일을 notebooks 또는 covid_analysis 폴더가 아닌 Git 폴더의 루트로 이동하려고 합니다.

2. 새 파일 이름 대화 상자에서 requirements.txt를 입력한 다음, 파일 만들기를 클릭합니다.

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단계: 리팩터링된 Notebook 실행

이 하위 단계에서는 covid_eda_modular에서 공유 코드를 호출하는 covid_analysis/transforms.py Notebook을 실행합니다.

1. 작업 영역 브라우저에서 notebooks 폴더 내의 covid_eda_modular Notebook을 클릭합니다.
2. 이 Notebook을 연결할 클러스터를 선택합니다.
3. 모두 실행을 클릭합니다.
4. Notebook이 실행되는 동안 기다립니다.

Notebook 실행이 완료되면 Notebook에서 covid_eda_raw Notebook과 동일한 결과, 즉 Delta 테이블의 원시 데이터 행 600개 이상뿐만 아니라 데이터 플롯도 표시됩니다. 이 Notebook의 주요 차이점은 다른 필터가 사용된다는 것입니다(iso_code 대신 DZA의 USA). 이 Notebook 실행을 시작할 때 클러스터가 아직 실행되고 있지 않은 경우 결과를 표시하기 전에 클러스터가 시작되는 데 몇 분 정도 걸릴 수 있습니다.

3.6단계: Notebook 및 관련 코드 체크 인

1. 전자 필기장 이름 옆에 있는 first_modules Git 분기 버튼을 클릭합니다.
2. best-notebooks 대화 상자의 변경 내용 탭에서 다음이 선택되어 있는지 확인합니다.
   • requirements.txt
   • covid_analysis/transforms.py
   • notebooks/covid_eda_modular.py
3. 커밋 메시지(필수)에 Added refactored notebook을 입력합니다.
4. 설명(선택 사항)에 This is the second version of the notebook.를 입력합니다.
5. 커밋 & 푸시를 클릭합니다.
6. 배너의 git 공급자에 대한 끌어오기 요청 만들기에서 끌어오기 요청 링크를 클릭합니다.
7. GitHub에서 끌어오기 요청을 만든 다음, 끌어오기 요청을 main 분기에 병합합니다.
8. Azure Databricks 작업 영역으로 돌아가서 best-notebooks 대화 상자를 닫습니다(여전히 표시되는 경우).

4단계: 공유 코드 테스트

이 단계에서는 마지막 단계에서 공유 코드를 테스트합니다. 그러나 covid_eda_modular Notebook 자체를 실행하지 않고 이 코드를 테스트하려고 합니다. 이는 공유 코드가 실행되지 않으면 Notebook 자체도 실행되지 않을 수 있기 때문입니다. 주 Notebook이 나중에 실패하도록 하기 전에 먼저 공유 코드에서 오류를 catch하려고 합니다. 이 테스트 기술은 소프트웨어 엔지니어링 모범 사례입니다.

팁

Notebook 테스트와 R 및 Scala Notebook 테스트에 대한 추가 접근 방식은 Notebook에 대한 단위 테스트를 참조하세요.

4.1단계: 리포지토리에서 또 다른 작업 분기 만들기

1. 전자 필기장 이름 옆에 있는 first_modules Git 분기 버튼을 클릭합니다.
2. best-notebooks 대화 상자에서 first_modules 분기 옆에 있는 드롭다운 화살표를 클릭하고 main을 선택합니다.
3. 끌어오기 단추를 클릭합니다. 끌어오기를 계속할지 묻는 메시지가 표시되면 확인을 클릭합니다.
4. 분기 만들기를 클릭합니다.
5. first_tests를 입력하고 만들기를 클릭합니다. (분기에 다른 이름을 지정할 수 있습니다.)
6. 이 대화 상자를 닫습니다.

4.2단계: 테스트 추가

이 하위 단계에서는 pytest 프레임워크를 사용하여 공유 코드를 테스트합니다. 이러한 테스트에서는 특정 테스트 결과가 달성되는지 여부를 어설션합니다. 테스트가 예기치 않은 결과를 생성하는 경우 해당 특정 테스트는 어설션에 실패하므로 테스트 자체가 실패합니다.

1. 작업 영역 브라우저에서 Git 폴더를 마우스 오른쪽 버튼으로 클릭한 다음 > 폴더 만들기를 클릭합니다.

2. 새 폴더 대화 상자에서 tests를 입력한 다음, 만들기를 클릭합니다.

3. tests 폴더에서 > 파일 만들기를 클릭합니다.

4. 새 파일 이름 대화 상자에서 testdata.csv를 입력한 다음, 파일 만들기를 클릭합니다.

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. tests 폴더에서 > 파일 만들기를 클릭합니다.

7. 새 파일 이름 대화 상자에서 transforms_test.py를 입력한 다음, 파일 만들기를 클릭합니다.

8. transforms_test.py 편집기 창에 다음 테스트 코드를 입력합니다. 이러한 테스트는 모의 메모리 내 pandas DataFrame뿐만 아니라 표준 pytest픽스쳐도 사용합니다.

   # 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단계: 테스트 실행

이 연습의 속도를 높이기 위해 이 하위 단계에서는 가져온 Notebook을 사용하여 이전 테스트를 실행합니다. 이 Notebook은 테스트의 종속 Python 패키지를 다운로드하여 작업 영역에 설치하고, 테스트를 실행하고, 테스트 결과를 보고합니다. 클러스터의 pytest에서 를 실행할 수 있지만 Notebook에서 pytest를 실행하는 것이 더 편리할 수 있습니다.

참고 항목

pytest를 실행하면 이름이 현재 디렉터리 및 해당 하위 디렉터리에 있는 폼 test_*.py 또는 /*_test.py 형식을 따르는 모든 파일이 실행됩니다.

1. 작업 영역 브라우저에서 notebooks 폴더를 마우스 오른쪽 버튼으로 클릭한 다음 가져오기를 클릭합니다.
2. Notebook 가져오기 대화 상자에서 다음을 수행합니다.

   1. 다음에서 가져오기에서 URL을 선택합니다.

   2. GitHub의 run_unit_tests 리포지토리에 있는 databricks/notebook-best-practices Notebook의 원시 콘텐츠에 대한 URL을 입력합니다. 이 URL을 가져오려면 다음을 수행합니다. i. https://github.com/databricks/notebook-best-practices(으)로 이동합니다. ii. notebooks 폴더를 클릭합니다. iii. run_unit_tests.py 파일을 클릭합니다. iv. 원시를 클릭합니다. v. 웹 브라우저의 주소 표시줄에 표시되는 전체 URL을 Notebook 가져오기 대화 상자로 복사합니다.

      참고 항목

      Notebook 가져오기 대화 상자는 공용 리포지토리에 대해서만 Git URL에서 작동합니다.

   3. 가져오기를 클릭합니다.

3. 이 Notebook을 연결할 클러스터를 선택합니다.
4. 모두 실행을 클릭합니다.
5. Notebook이 실행되는 동안 기다립니다.

Notebook 실행이 완료되면 Notebook에 통과 및 실패한 테스트 수에 대한 정보와 기타 관련 세부 정보가 표시됩니다. 이 Notebook 실행을 시작할 때 클러스터가 아직 실행되고 있지 않은 경우 결과를 표시하기 전에 클러스터가 시작되는 데 몇 분 정도 걸릴 수 있습니다.

이제 리포지토리 구조가 다음과 같이 표시됩니다.

├── 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단계: Notebook 및 관련 테스트 체크 인

1. 전자 필기장 이름 옆에 있는 first_tests Git 분기 버튼을 클릭합니다.
2. best-notebooks 대화 상자의 변경 내용 탭에서 다음이 선택되어 있는지 확인합니다.
   • 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단계: Notebook을 실행하는 작업 만들기

이전 단계에서는 공유 코드를 수동으로 테스트하고 Notebook을 수동으로 실행했습니다. 이 단계에서는 Azure Databricks 작업을 사용하여 공유 코드를 테스트하고 주문형으로 또는 정기적으로 Notebook을 자동으로 실행합니다.

5.1단계: 테스트 Notebook을 실행하는 작업 만들기

1. 작업 영역 사이드바에서 워크플로를 클릭합니다.
2. 작업 탭에서 작업 만들기를 클릭합니다.
3. covid_report할 작업의 이름을 편집합니다.
4. 작업 이름에서 run_notebook_tests를 입력합니다.
5. 유형에서 Notebook을 선택합니다.
6. 원본에서 Git 공급자를 선택합니다.
7. Git 참조 추가를 클릭합니다.
8. Git 정보 대화 상자에서 다음을 수행합니다.
   1. Git 리포지토리 URL의 경우 GitHub 리포지토리의 GitHub HTTPS를 사용한 복제 URL을 입력합니다. 이 문서에서는 URL이 best-notebooks.git로 끝나는 것(예: https://github.com/<your-GitHub-username>/best-notebooks.git)으로 가정합니다.
   2. Git 공급자에서 GitHub를 선택합니다.
   3. Git 참조(분기/태그/커밋)에서 main을 입력합니다.
   4. Git 참조(분기/태그/커밋) 옆에 있는 분기를 선택합니다.
   5. 확인을 클릭합니다.
9. 경로에서 notebooks/run_unit_tests를 입력합니다. .py 파일 확장명은 추가하지 마세요.
10. 클러스터에서 이전 단계의 클러스터를 선택합니다.
11. 작업 만들기를 클릭합니다.

참고 항목

이 시나리오에서 Databricks는 예약된 Notebook 작업 만들기 및 관리에 설명된 대로 Notebook의 예약 단추를 사용하여 이 Notebook을 주기적으로 실행하는 작업을 예약하지 않을 것을 권장합니다. 예약 단추는 작업 영역 리포지토리에서 Notebook의 최신 작업 복사본을 사용하여 작업을 만들기 때문입니다. 대신 Databricks는 이전 지침에 따라 리포지토리에 있는 Notebook의 커밋된 최신 버전을 사용하는 작업을 만들 것을 권장합니다.

5.2단계: 주 Notebook을 실행하는 작업 만들기

1. + 작업 추가 아이콘을 클릭합니다.
2. 팝업 메뉴가 나타납니다. Notebook을 선택합니다.
3. 작업 이름에서 run_main_notebook를 입력합니다.
4. 유형에서 Notebook을 선택합니다.
5. 경로에서 notebooks/covid_eda_modular를 입력합니다. .py 파일 확장명은 추가하지 마세요.
6. 클러스터에서 이전 단계의 클러스터를 선택합니다.
7. 종속 값이 run_notebook-tests인지 확인합니다.
8. 작업 만들기를 클릭합니다.

5.3단계 작업 실행

1. 지금 실행을 클릭합니다.

2. 팝업에서 실행 보기를 클릭합니다.

   참고 항목

   팝업이 너무 빨리 사라지면 다음을 수행합니다.

   1. 데이터 과학 및 엔지니어링 또는 Databricks Mosaic AI 환경의 사이드바에서 워크플로를 클릭합니다.
   2. 작업 실행 탭에서 작업 열에 covid_report가 있는 최신 작업의 시작 시간 값을 클릭합니다.

3. 작업 결과를 보려면 run_notebook_tests 타일, run_main_notebook 타일 또는 둘 다를 클릭합니다. 각 타일의 결과는 Notebook을 직접 하나씩 실행한 경우와 동일합니다.

참고 항목

이 작업은 주문형으로 실행되었습니다. 이 작업을 정기적으로 실행하도록 설정하려면 일정 및 트리거를 사용한 작업 자동화을 참조하세요.

(선택 사항) 6단계: 코드가 변경될 때마다 자동으로 코드를 테스트하고 Notebook을 실행하도록 리포지토리 설정

이전 단계에서는 공유 코드를 자동으로 테스트하고 특정 시점에 또는 반복적으로 Notebook을 실행하는 작업을 사용했습니다. 그러나 변경 내용이 GitHub 리포지토리에 병합될 때 GitHub Actions와 같은 CI/CD 도구를 사용하여 자동으로 테스트를 트리거하는 것이 좋습니다.

6.1단계: 작업 영역에 대한 GitHub 액세스 설정

이 하위 단계에서는 변경 내용이 리포지토리에 병합될 때마다 작업 영역에서 작업을 실행하는 GitHub Actions 워크플로를 설정합니다. 이렇게 하려면 GitHub에 액세스를 위한 고유한 Azure Databricks 토큰을 제공합니다.

보안상의 이유로 Databricks는 Azure Databricks 작업 영역 사용자의 개인용 액세스 토큰을 GitHub에 제공하지 않을 것을 권장합니다. 대신 Databricks는 GitHub에 Microsoft Entra ID 서비스 주체와 연결된 Microsoft Entra ID 토큰을 제공하는 것이 좋습니다. 자세한 내용은 GitHub Actions Marketplace에서 Databricks Notebook GitHub 작업 실행 페이지의 Azure 섹션을 참조하세요.

Important

Notebook은 토큰과 연결된 ID의 모든 작업 영역 권한으로 실행되므로 Databricks는 서비스 주체를 사용할 것을 권장합니다. 개인 탐색 목적으로만 사용되는 Azure Databricks 작업 영역 사용자의 개인용 액세스 토큰을 GitHub에 제공하려는 경우 Databricks는 보안상의 이유로 이 방법을 권장하지 않는다는 것을 이해하려면 작업 영역 사용자의 개인용 액세스 토큰 생성 지침을 참조하세요.

6.2단계: GitHub Actions 워크플로 추가

이 하위 단계에서는 리포지토리에 대한 끌어오기 요청이 있을 때마다 run_unit_tests Notebook을 실행하는 GitHub Actions 워크플로를 추가합니다.

이 하위 단계는 GitHub 리포지토리의 여러 폴더 수준 내에 저장된 파일에 GitHub Actions 워크플로를 저장합니다. GitHub Actions가 제대로 작동하려면 리포지토리에 특정 중첩 폴더 계층 구조가 있어야 합니다. Azure Databricks Git 폴더 사용자 인터페이스는 중첩된 폴더 계층 구조 만들기를 지원하지 않으므로 이 단계를 완료하려면 GitHub 리포지토리용 웹 사이트를 사용해야 합니다.

1. GitHub 리포지토리용 웹 사이트에서 코드 탭을 클릭합니다.

2. 기본 옆의 화살표를 클릭하여 분기 또는 태그 전환 드롭다운 목록을 확장합니다.

3. 분기 찾기 또는 만들기 상자에 adding_github_actions를 입력합니다.

4. 분기 만들기: 'main'의 adding_github_actions를 클릭합니다.

5. 파일 추가 > 새 파일 만들기를 클릭합니다.

6. 파일 이름 지정에서 .github/workflows/databricks_pull_request_tests.yml을 입력합니다.

7. 편집기 창에 다음 코드를 입력합니다. 이 코드는 Databricks Notebook GitHub Action 실행의 pull_request 후크를 사용하여 run_unit_tests Notebook을 실행합니다.

   다음 코드의 항목을 바꿉니다.

   • <your-workspace-instance-URL>을 Azure Databricks 인스턴스 이름으로.
   • <your-access-token>을 이전에 생성한 토큰으로.
   • <your-cluster-id>를 대상 클러스터 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. 끌어오기 요청 페이지에서 사전 병합 Databricks 테스트/unit-test-notebook(pull_request) 실행 옆에 있는 아이콘에 녹색 확인 표시가 표시될 때까지 기다립니다. (아이콘이 표시되는 데 몇 분 정도 걸릴 수 있습니다.) 녹색 확인 표시 대신 빨간색 X가 있는 경우 세부 정보를 클릭하여 이유를 확인합니다. 아이콘 또는 세부 정보가 더 이상 표시되지 않으면 모든 검사 표시를 클릭합니다.

13. 녹색 확인 표시가 나타나면 끌어오기 요청을 main 분기에 병합합니다.

(선택 사항) 7단계: GitHub의 공유 코드를 업데이트하여 테스트 트리거

이 단계에서는 공유 코드를 변경한 다음, GitHub 리포지토리로 변경 내용을 푸시하여 이전 단계의 GitHub Action에 따라 즉시 테스트를 자동으로 트리거합니다.

7.1단계: 리포지토리에서 또 다른 작업 분기 만들기

1. 작업 영역 브라우저에서 best-notebooks Git 폴더를 엽니다.
2. 폴더 이름 옆에 있는 first_tests Git 분기 버튼을 클릭합니다.
3. best-notebooks 대화 상자에서 first_tests 분기 옆에 있는 드롭다운 화살표를 클릭하고 main을 선택합니다.
4. 끌어오기 단추를 클릭합니다. 끌어오기를 계속할지 묻는 메시지가 표시되면 확인을 클릭합니다.
5. +(분기 만들기) 단추를 클릭합니다.
6. trigger_tests를 입력하고 만들기를 클릭합니다. (분기에 다른 이름을 지정할 수 있습니다.)
7. 이 대화 상자를 닫습니다.

7.2단계: 공유 코드 변경

1. 작업 영역 브라우저의 best-notebooks 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 대화 상자의 변경 내용 탭에서 covid_analysis/transforms.py가 선택되어 있는지 확인합니다.
3. 커밋 메시지(필수)에 Updated comment을 입력합니다.
4. 설명(선택 사항)에 This updates the comment for filter_country.를 입력합니다.
5. 커밋 & 푸시를 클릭합니다.
6. 배너의 git 공급자에 끌어오기 요청 만들기에서 끌어오기 요청 링크를 클릭한 다음 GitHub에서 끌어오기 요청을 만듭니다.
7. 끌어오기 요청 페이지에서 사전 병합 Databricks 테스트/unit-test-notebook(pull_request) 실행 옆에 있는 아이콘에 녹색 확인 표시가 표시될 때까지 기다립니다. (아이콘이 표시되는 데 몇 분 정도 걸릴 수 있습니다.) 녹색 확인 표시 대신 빨간색 X가 있는 경우 세부 정보를 클릭하여 이유를 확인합니다. 아이콘 또는 세부 정보가 더 이상 표시되지 않으면 모든 검사 표시를 클릭합니다.
8. 녹색 확인 표시가 나타나면 끌어오기 요청을 main 분기에 병합합니다.