Práticas recomendadas de engenharia de software para notebooks

Este artigo oferece um passo a passo prático que demonstra como aplicar práticas recomendadas de engenharia de software aos notebooks do Azure Databricks, incluindo controle de versão, compartilhamento de código, teste e, opcionalmente, CI/CD (integração contínua e entrega ou implantação contínua).

Neste passo a passo, você vai:

• Adicionar notebooks a pastas Git do Azure Databricks para controle de versão.
• Extrair partes de código de um dos notebooks em um módulo compartilhável.
• Testar o código compartilhado.
• Executar os notebooks por meio de um trabalho do Azure Databricks.
• Opcionalmente, aplicar CI/CD ao código compartilhado.

Requisitos

Para concluir este passo a passo, você precisa instalar os seguintes recursos:

• Um repositório remoto com um provedor Git compatível com o Databricks. O passo a passo deste artigo usa o GitHub. Este passo a passo pressupõe que você tenha um repositório do GitHub chamado best-notebooks disponível. (Você pode dar um nome diferente ao repositório. Se fizer isso, substitua best-notebooks pelo nome do repositório neste passo a passo.) Crie um repositório do GitHub se você ainda não tiver um.

  Observação

  Se você criar um repositório, não deixe de inicializá-lo com pelo menos um arquivo, por exemplo, um arquivo README.

• Um workspace do Azure Databricks. Crie um workspace, se você ainda não tiver um.

• Um cluster para todas as finalidades do Azure Databricks no workspace. Para executar notebooks durante a fase de design, você anexa os notebooks a um cluster para todas as finalidades em execução. Mais tarde, este passo a passo usará um trabalho do Azure Databricks para automatizar a execução dos notebooks nesse cluster. (Você também pode executar trabalhos em clusters de trabalho que existem apenas durante o tempo de vida dos trabalhos). Crie um cluster para todos as finalidades se você ainda não tiver um.

Etapa 1: Configurar pastas Git do Databricks

Nesta etapa, você conectará o repositório do GitHub existente às pastas Git do Azure Databricks no workspace do Azure Databricks existente.

Para permitir que o workspace se conecte ao repositório do GitHub, primeiro forneça ao workspace suas credenciais do GitHub, caso ainda não tenha feito isso.

Etapa 1.1: Fornecer as credenciais do GitHub

1. Clique no nome de usuário no canto superior direito do workspace e clique em Configurações na lista suspensa.
2. Na barra lateral Configurações, em Usuário, clique em Contas vinculadas.
3. Em Integração do Git, em Provedor do Git, selecione GitHub.
4. Clique em Token de acesso pessoal.
5. Em Nome de usuário ou email do provedor do Git, insira seu nome de usuário do GitHub.
6. Em Token, insira seu token de acesso pessoal do GitHub. Esse token de acesso pessoal (clássico) deve ter as permissões de repositório e fluxo de trabalho.
7. Clique em Save (Salvar).

Etapa 1.2: Conectar-se ao repositório do GitHub

1. Na barra lateral do workspace, clique em Workspace.
2. No navegador do Workspace, expanda Workspace > Usuários.
3. Clique com o botão direito do mouse na pasta com o nome de usuário e clique em Criar > Pasta Git.
4. Na caixa de diálogo Criar pasta Git:
   1. Em URL do repositório do Git, insira a URL Clonar com HTTPS do GitHub do repositório do GitHub. Este artigo pressupõe que a URL termine com best-notebooks.git, por exemplo https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. Em Provedor do Git, selecione GitHub.
   3. Deixe o Nome da pasta Git definido como o nome do seu repositório, por exemplo best-notebooks.
   4. Clique em Criar pasta Git.

Etapa 2: Importar e executar o notebook

Nesta etapa, você importará um notebook externo existente para o repositório. Você pode criar seus próprios notebooks neste passo a passo, mas para acelerar as coisas, já os fornecemos aqui para você.

Etapa 2.1: Criar um branch de trabalho no repositório

Nesta subetapa, você cria um branch chamado eda no repositório. Esse branch permite que você trabalhe em arquivos e códigos independentemente do branch do repositório main, o que é uma prática recomendada de engenharia de software. (Você pode dar um nome diferente ao branch.)

Observação

Em alguns repositórios, o branch main pode ser nomeado como master. Nesse caso, substitua main por master neste passo a passo.

Dica

Se você não estiver familiarizado com o trabalho em branches do Git, consulte Git Branches - Branches in a Nutshell no site do Git.

1. A pasta Git da Etapa 1.2 deve estar aberta. Caso contrário, na barra lateral do Workspace, expanda Workspace Usuários>, expanda a pasta com o nome de usuário e clique na pasta Git.

2. Ao lado do nome da pasta na trilha de navegação do workspace, clique no botão main do Git branch.

3. Na caixa de diálogo best-notebooks, clique no botão Criar branch.

   Observação

   Se o repositório tiver um nome diferente de best-notebooks, o título dessa caixa de diálogo será diferente, aqui e ao longo deste passo a passo.

4. Insira eda e clique em Criar.

5. Feche este diálogo.

Etapa 2.2: Importar o notebook para o repositório

Nesta subetapa, você importa um notebook existente de outro repositório para o repositório. Este notebook faz o seguinte:

• Copia um arquivo CSV do repositório do GitHub owid/covid-19-data para um cluster no workspace. Esse arquivo CSV contém dados públicos sobre internações decorrentes da COVID-19 e métricas de cuidados intensivos do mundo todo.
• Lê o conteúdo do arquivo CSV em um Pandas DataFrame.
• Filtra os dados para conter métricas somente dos Estados Unidos.
• Exibe um gráfico dos dados.
• Salva o Pandas DataFrame como uma API do Pandas no Spark DataFrame.
• Executa a limpeza de dados na API do pandas no DataFrame do Spark.
• Grava a API do pandas no DataFrame do Spark como uma tabela do Delta no workspace.
• Exibe o conteúdo da tabela do Delta.

Embora você possa criar seu próprio notebook no repositório aqui, a importação de um notebook existente acelera este passo a passo. Para criar um notebook nesse branch ou transferir um notebook existente para esse branch em vez de importar um notebook, confira Uso básico de arquivos de workspace.

1. Na pasta Git best-notebooks, clique em Criar > Pasta.
2. Na caixa de diálogo Nova pasta, insira notebooks e clique em Criar.
3. Na pasta notebooks, clique no kebab e, em seguida, Importar.
4. Na caixa de diálogo Importar:

   1. Em Importar de, selecione URL.

   2. Insira a URL do conteúdo bruto do notebook covid_eda_raw no repositório databricks/notebook-best-practices do GitHub. Para obter essa URL: i. Ir para https://github.com/databricks/notebook-best-practices. ii. Clique na pasta notebooks. III. Clique no arquivo covid_eda_raw.py. iv. Clique em Bruto. .v Copie a URL completa da barra de endereços do navegador da Web para a caixa de diálogo Importar.

      Observação

      A caixa de diálogo Importar só funciona com as URLs do Git para repositórios públicos.

   3. Clique em Importar.

Etapa 2.3: Executar o notebook

1. Se o notebook ainda não estiver sendo exibido, abra a pasta notebooks e clique no notebook covid_eda_raw dentro da pasta.
2. Selecione o cluster ao qual anexar este notebook. Para obter instruções sobre como criar um cluster, consulte Criar um cluster.
3. Clique em Executar Tudo.
4. Aguarde enquanto o notebook é executado.

Depois que a execução do notebook for concluída, no notebook você verá um gráfico dos dados, além de mais de 600 linhas de dados brutos na tabela do Delta. Se o cluster ainda não estava em execução quando você começou a executar este notebook, ele pode precisar de vários minutos para ser iniciado e exibir os resultados.

Etapa 2.4: Fazer check-in e mesclar o notebook

Neste subetapa, você salvará o trabalho até agora no repositório do GitHub. Depois, você mesclará o notebook do branch de trabalho no branch main do repositório.

1. Ao lado do nome do notebook, clique no botão do Git branch eda.
2. Na caixa de diálogo best-notebooks, na guia Alterações, verifique se o arquivo notebooks/covid_eda_raw.py está selecionado.
3. Para Mensagem de commit (obrigatório), insira Added raw notebook.
4. Em Descrição (opcional), insira This is the first version of the notebook.
5. Clique em Fazer Commit e Efetuar Push.
6. Clique no link de pull request em Criar um pull request no seu provedor Git na faixa de opções.
7. No GitHub, crie o pull request e mescle-o no branch main.
8. De volta ao workspace do Azure Databricks, feche a caixa de diálogo best-notebooks se ela ainda estiver exibida.

Etapa 3: Mover um código para um módulo compartilhado

Nesta etapa, você moverá parte do código do notebook para um conjunto de funções compartilhadas fora do notebook. Isso permite que você use essas funções com outros notebooks semelhantes, o que pode acelerar a codificação futura e garantir resultados mais previsíveis e consistentes para o notebook. O compartilhamento desse código também permite que você teste essas funções com mais facilidade, o que pode elevar a qualidade geral do código ao longo do processo por ser um prática recomendada de engenharia de software.

Etapa 3.1: Criar outro branch de trabalho no repositório

1. Ao lado do nome do notebook, clique no botão do Git branch eda.
2. Na caixa de diálogo best-notebooks, clique na seta suspensa ao lado do branch eda e selecione main.
3. Clique no botão Efetuar Pull. Se solicitado, clique em Confirmar para continuar o pull.
4. Clique no botão Criar Branch.
5. Insira first_modules e, em seguida, clique em Criar. (Você pode dar um nome diferente ao branch.)
6. Feche este diálogo.

Etapa 3.2: Importar o notebook para o repositório

Para acelerar esse passo a passo, nesta subetapa você importará outro notebook existente para seu repositório. Esse notebook faz o mesmo que o anterior, exceto que ele chamará funções de código compartilhado armazenadas fora dele. Novamente, você pode criar seu próprio notebook no repositório aqui e fazer o compartilhamento de código real por conta própria.

1. No navegador do Workspace, clique com o botão direito do mouse na pasta notebooks e clique em Importar.
2. Na caixa de diálogo Importar:

   1. Em Importar de, selecione URL.

   2. Insira a URL do conteúdo bruto do notebook covid_eda_modular no repositório databricks/notebook-best-practices do GitHub. Para obter essa URL: i. Ir para https://github.com/databricks/notebook-best-practices. ii. Clique na pasta notebooks. III. Clique no arquivo covid_eda_modular.py. iv. Clique em Bruto. V. Copie a URL completa da barra de endereços do navegador da Web para a caixa de diálogo Importar Notebooks.

      Observação

      A caixa de diálogo Importar Notebooks só funciona com as URLs do Git para repositórios públicos.

   3. Clique em Importar.

Etapa 3.3: Adicionar as funções de código compartilhado compatíveis com o notebook

1. No navegador do Workspace, clique com o botão direito do mouse na pasta Git best-notebooks e clique em Criar > Pasta.

2. Na caixa de diálogo Nova pasta, insira covid_analysis e clique em Criar.

3. Na pasta covid_analysis, clique em Criar > Arquivo.

4. Na caixa de diálogo Nome do Novo Arquivo, insira transforms.py e clique em Criar Arquivo.

5. Na janela do editor transforms.py, insira o seguinte código:

   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
   

Dica

Para conhecer outras técnicas de compartilhamento de código, confira Compartilhar código entre notebooks dp Databricks.

Etapa 3.4: Adicionar dependências do código compartilhado

O código anterior tem várias dependências de pacote Python que permitem a execução correta. Nesta subetapa, você declara essas dependências de pacote. A declaração de dependências aprimora a capacidade de reprodução usando versões de bibliotecas definidas com precisão.

1. No navegador do Workspace, clique com o botão direito do mouse na pasta Git best-notebooks e clique em Criar > Arquivo.

   Observação

   Você quer adicionar o arquivo que lista as dependências do pacote na raiz da pasta Git, não nas pastas notebooks ou covid_analysis.

2. Na caixa de diálogo Nome do Novo Arquivo, insira requirements.txt e clique em Criar Arquivo.

3. Na janela do editor de requirements.txt, insira o código a seguir:

   Observação

   Se o arquivo requirements.txt não estiver visível, talvez seja necessário atualizar o navegador da Web.

   -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
   

   Observação

   O arquivo anterior lista versões de pacote específicas. Para aprimorar a compatibilidade, você pode fazer referência cruzada a essas versões com as que estão instaladas no cluster para todos as finalidades. Consulte também a seção "Ambiente do sistema" da versão do Databricks Runtime em das versões de notas sobre a versão e compatibilidade do Databricks Runtime.

Agora, a estrutura do repositório será a seguinte:

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

Etapa 3.5: Executar o notebook refatorado

Nesta subetapa, você executa o notebook covid_eda_modular, que chama o código compartilhado em covid_analysis/transforms.py.

1. No navegador do Workspace, clique no notebook covid_eda_modular dentro da pasta notebooks.
2. Selecione o cluster ao qual anexar este notebook.
3. Clique em Executar Tudo.
4. Aguarde enquanto o notebook é executado.

Depois que a execução do notebook for concluída, no notebook você verá resultados semelhantes aos do notebook covid_eda_raw: um gráfico dos dados, além de mais de 600 linhas de dados brutos na tabela do Delta. A principal diferença com esse notebook é que um filtro diferente é usado (um iso_code de DZA em vez de USA). Se o cluster ainda não estava em execução quando você começou a executar este notebook, ele pode precisar de vários minutos para ser iniciado e exibir os resultados.

Etapa 3.6: Verificar o notebook e o código relacionado

1. Ao lado do nome do notebook, clique no botão do GIT branch first_modules.
2. Na caixa de diálogo best-notebooks, na guia Alterações, verifique se as seguintes opções estão selecionadas:
   • requirements.txt
   • covid_analysis/transforms.py
   • notebooks/covid_eda_modular.py
3. Para Mensagem de commit (obrigatório), insira Added refactored notebook.
4. Em Descrição (opcional), insira This is the second version of the notebook.
5. Clique em Fazer Commit e Efetuar Push.
6. Clique no link de pull request em Criar um pull request no seu provedor Git na faixa de opções.
7. No GitHub, crie o pull request e mescle-o no branch main.
8. De volta ao workspace do Azure Databricks, feche a caixa de diálogo best-notebooks se ela ainda estiver exibida.

Etapa 4: Testar o código compartilhado

Nesta etapa, você testará o código compartilhado na última etapa. Mas você deve testar esse código sem executar o notebook covid_eda_modular em si. O motivo é que, se o código compartilhado não for executado, provavelmente o notebook em si também não será executado. Você quer capturar falhas no código compartilhado primeiro, antes que o notebook principal possa falhar depois. Essa técnica de teste é uma prática recomendada de engenharia de software.

Dica

Para obter abordagens adicionais de teste para notebooks, bem como testes para notebooks R e Scala, consulte Teste de unidade para notebooks.

Etapa 4.1: Criar outro branch de trabalho no repositório

1. Ao lado do nome do notebook, clique no botão do GIT branch first_modules.
2. Na caixa de diálogo best-notebooks, clique na seta suspensa ao lado do branch first_modules e selecione main.
3. Clique no botão Efetuar Pull. Se solicitado, clique em Confirmar para continuar o pull.
4. Clique em Criar Branch.
5. Insira first_tests e, em seguida, clique em Criar. (Você pode dar um nome diferente ao branch.)
6. Feche este diálogo.

Etapa 4.2: Adicionar os testes

Nesta subetapa, você usa a estrutura pytest para testar o código compartilhado. Nesses testes, você declara se determinados resultados de teste são alcançados. Se algum teste produzir um resultado inesperado, esse teste específico não será declarado e, portanto, o próprio teste falhará.

1. No navegador do Workspace, clique com o botão direito do mouse na pasta Git e clique em Criar > Pasta.

2. Na caixa de diálogo Nova pasta, insira tests e clique em Criar.

3. Na pasta tests, clique em Criar > Arquivo.

4. Na caixa de diálogo Nome do Novo Arquivo, insira testdata.csv e clique em Criar Arquivo.

5. Na janela do editor de testdata.csv, insira os seguintes dados de teste:

   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. Na pasta tests, clique em Criar > Arquivo.

7. Na caixa de diálogo Nome do Novo Arquivo, insira transforms_test.py e clique em Criar Arquivo.

8. Na janela do editor de transforms_test.py, insira o seguinte código de teste. Esses testes usam pytestacessórios padrão, bem como um Pandas DataFrame simulado na memória:

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

Agora, a estrutura do repositório será a seguinte:

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

Etapa 4.3: Executar os testes

Para acelerar esse passo a passo, nesta subetapa você usa um notebook importado para executar os testes anteriores. Este notebook baixa e instala os pacotes Python dependentes dos testes no workspace, executa os testes e relata os resultados dos testes. Embora você possa executar pytest no terminal Web do cluster, pode ser mais conveniente executar pytest em um notebook.

Observação

A execução de pytest executa todos os arquivos cujos nomes seguem o formato test_*.py ou /*_test.py no diretório atual e seus subdiretórios.

1. No navegador do Workspace, clique com o botão direito do mouse na pasta notebooks e clique em Importar.
2. Na caixa de diálogo Importar Notebooks:

   1. Em Importar de, selecione URL.

   2. Insira a URL do conteúdo bruto do notebook run_unit_tests no repositório databricks/notebook-best-practices do GitHub. Para obter essa URL: i. Ir para https://github.com/databricks/notebook-best-practices. ii. Clique na pasta notebooks. III. Clique no arquivo run_unit_tests.py. iv. Clique em Bruto. V. Copie a URL completa da barra de endereços do navegador da Web para a caixa de diálogo Importar Notebooks.

      Observação

      A caixa de diálogo Importar Notebooks só funciona com as URLs do Git para repositórios públicos.

   3. Clique em Importar.

3. Selecione o cluster ao qual anexar este notebook.
4. Clique em Executar Tudo.
5. Aguarde enquanto o notebook é executado.

Depois que a execução do notebook for concluída, no notebook você verá informações sobre o número de testes aprovados e com falha, juntamente com outros detalhes relacionados. Se o cluster ainda não estava em execução quando você começou a executar este notebook, ele pode precisar de vários minutos para ser iniciado e exibir os resultados.

Agora, a estrutura do repositório será a seguinte:

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

Etapa 4.4: Verificar o notebook e os testes relacionados

1. Ao lado do nome do notebook, clique no botão do GIT branch first_tests.
2. Na caixa de diálogo best-notebooks, na guia Alterações, verifique se as seguintes opções estão selecionadas:
   • tests/transforms_test.py
   • notebooks/run_unit_tests.py
   • tests/testdata.csv
3. Para Mensagem de commit (obrigatório), insira Added tests.
4. Em Descrição (opcional), insira These are the unit tests for the shared code..
5. Clique em Fazer Commit e Efetuar Push.
6. Clique no link de pull request em Criar um pull request no seu provedor Git na faixa de opções.
7. No GitHub, crie o pull request e mescle-o no branch main.
8. De volta ao workspace do Azure Databricks, feche a caixa de diálogo best-notebooks se ela ainda estiver exibida.

Etapa 5: Criar um trabalho para executar os notebooks

Nas etapas anteriores, você testou o código compartilhado e executou os notebooks manualmente. Nesta etapa, você usará um trabalho do Azure Databricks para testar o código compartilhado e executar os notebooks automaticamente, sob demanda ou mediante um agendamento regular.

Etapa 5.1: Criar uma tarefa de trabalho para executar o notebook de teste

1. Na barra lateral do workspace, clique em Fluxos de trabalho.
2. Na guia Trabalhos, clique em Criar Trabalho.
3. Edite o nome do trabalho para que seja covid_report.
4. Em Nome da tarefa, insira run_notebook_tests.
5. Em Tipo, selecione Notebook.
6. Em Fonte, selecione Provedor Git.
7. Clique em Adicionar uma referência do Git.
8. Na caixa de diálogo Informações do Git:
   1. Em URL do repositório do Git, insira a URL Clonar com HTTPS do GitHub do repositório do GitHub. Este artigo pressupõe que a URL termine com best-notebooks.git, por exemplo https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. Em Provedor do Git, selecione GitHub.
   3. Em Referência do Git (branch/tag/commit), insira main.
   4. Em Referência do Git (branch/tag/commit), selecione branch.
   5. Clique em Confirmar.
9. Em Caminho, insira notebooks/run_unit_tests. Não adicione a extensão de arquivo .py.
10. Em Cluster, selecione o cluster da etapa anterior.
11. Clique em Criar tarefa.

Observação

Nesse cenário, o Databricks não recomenda que você use o botão de agendamento no notebook, conforme a descrição em Criar e gerenciar trabalhos de notebook agendados, a fim agendar um trabalho para executar esse notebook periodicamente. O motivo é que o botão de agendamento cria um trabalho usando a cópia funcional mais recente do notebook no repositório do workspace. Nesse caso, a Databricks recomenda que você siga as instruções anteriores para criar um trabalho que use a versão com o commit mais recente do notebook no repositório.

Etapa 5.2: Criar uma tarefa de trabalho para executar o notebook principal

1. Clique no ícone + Adicionar.
2. Um menu pop-up é exibido. Selecionar Notebook.
3. Em Nome da tarefa, insira run_main_notebook.
4. Em Tipo, selecione Notebook.
5. Em Caminho, insira notebooks/covid_eda_modular. Não adicione a extensão de arquivo .py.
6. Em Cluster, selecione o cluster da etapa anterior.
7. Verifique se o valor Depende de é run_notebook-tests.
8. Clique em Criar tarefa.

Etapa 5.3: Executar o trabalho

1. Clique em Executar agora.

2. No pop-up, clique em Exibir execução.

   Observação

   Se o pop-up desaparecer rapidamente, faça o seguinte:

   1. Na barra lateral no ambiente de Ciência de Dados e Engenharia ou do ambiente do Databricks Mosaic AI, clique em Fluxos de Trabalho.
   2. Na guia Execuções de trabalho, clique no valor de Hora de início do trabalho mais recente com covid_report na coluna Trabalhos.

3. Para ver os resultados do trabalho, clique no bloco run_notebook_tests e/ou no bloco run_main_notebook. Os resultados em cada bloco são os mesmos que se você executasse os notebooks por conta própria, um por um.

Observação

Este trabalho foi executado sob demanda. Para configurar esse trabalho para ser executado regularmente, consulte Tipos de gatilho para trabalhos do Databricks.

(Opcional) Etapa 6: Configurar o repositório para testar o código e executar o notebook automaticamente sempre que o código for alterado

Na etapa anterior, você usou um trabalho para testar automaticamente o código compartilhado e executar os notebooks em um ponto no tempo ou com recorrência. Mas, talvez você prefira disparar os testes automaticamente quando as alterações forem mescladas no repositório do GitHub usando uma ferramenta de CI/CD, como o GitHub Actions.

Etapa 6.1: Configurar o acesso do GitHub ao workspace

Nesta subetapa, você configura um fluxo de trabalho do GitHub Actions que executa trabalhos no workspace sempre que as alterações são mescladas no repositório. Isso é feito dando ao GitHub um token exclusivo para acesso ao Azure Databricks.

Por motivos de segurança, a Databricks não recomenda que você forneça o token de acesso pessoal do usuário do workspace do Azure Databricks ao GitHub. Alternativamente, o Databricks recomenda que você forneça ao GitHub um token do Microsoft Entra ID que esteja associado a uma entidade de serviço do Microsoft Entra ID. Para obter instruções, confira a seção Azure da página Executar a Ação do GitHub de Notebook do Databricks no GitHub Actions Marketplace.

Importante

Os notebooks são executados com todas as permissões de workspace da identidade associada ao token, portanto, a Databricks recomenda o uso de uma entidade de serviço. Se você quiser fornecer o token de acesso pessoal do usuário do workspace do Azure Databricks ao GitHub apenas para fins de exploração pessoal mesmo entendendo que, por motivos de segurança, a Databricks não recomenda essa prática, confira as instruções para criar o token de acesso pessoal do usuário do workspace.

Etapa 6.2: Adicionar o fluxo de trabalho do GitHub Actions

Nesta subetapa, você adiciona um fluxo de trabalho do GitHub Actions para executar o notebook run_unit_tests sempre que há uma solicitação de pull para o repositório.

Esta subetapa armazena o fluxo de trabalho do GitHub Actions em um arquivo armazenado em vários níveis de pasta no repositório do GitHub. O GitHub Actions exige que uma hierarquia de pastas aninhada específica exista no repositório para funcionar corretamente. Para concluir esta etapa, você precisa usar o site do repositório do GitHub, pois a interface do usuário das pastas Git do Azure Databricks não dá suporte à criação de hierarquias de pasta aninhadas.

1. No site do repositório do GitHub, clique na guia Código.

2. Clique na seta ao lado de main para expandir a lista suspensa Alternar branches ou tags.

3. Na caixa Localizar ou criar um branch, insira adding_github_actions.

4. Clique em Criar branch: adding_github_actions de ‘main’.

5. Clique em Adicionar arquivo > Criar arquivo.

6. Em Nomear o arquivo, insira .github/workflows/databricks_pull_request_tests.yml.

7. Na janela do editor, insira o código a seguir. Esse código usa o gancho de pull_request da opção Executar o GitHub Action de notebook do Databricks para executar o notebook run_unit_tests.

   No seguinte código, substitua:

   • <your-workspace-instance-URL> pelo nome da instância do Azure Databricks.
   • <your-access-token> pelo token que você já havia gerado.
   • <your-cluster-id> pela ID do cluster de destino.

   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. Clique em Confirmar alterações.

9. Na caixa de diálogo Fazer commit das alterações, insira Create databricks_pull_request_tests.yml na Mensagem de commit

10. Selecione Fazer commit diretamente no branch adding_github_actions e clique em Fazer commit das alterações.

11. Na guia Código, clique em Comparar e pull request e crie o pull request.

12. Na página da solicitação de pull, aguarde o ícone ao lado de Executar testes do Databricks de pré-mesclagem/unit-test-notebook (pull_request) exibir uma marca de seleção verde. (Pode demorar um pouco até que o ícone apareça). Se houver um X vermelho em vez de uma marca de seleção verde, clique em Detalhes para descobrir o motivo. Se o ícone ou Detalhes não estiverem mais visíveis, clique em Mostrar todas as verificações.

13. Se a marca de seleção verde aparecer, mescle a solicitação de pull no branch main.

(Opcional) Etapa 7: Atualizar o código compartilhado no GitHub para disparar testes

Nesta etapa, você faz uma alteração no código compartilhado e depois efetua push da alteração para o repositório do GitHub, que dispara os testes de imediato automaticamente, com base no GitHub Action da etapa anterior.

Etapa 7.1: Criar outro branch de trabalho no repositório

1. No navegador do Workspace, abra a pasta Git best-notebooks.
2. Ao lado do nome da pasta, clique no botão do GIT branch first_tests.
3. Na caixa de diálogo best-notebooks, clique na seta suspensa ao lado do branch first_tests e selecione main.
4. Clique no botão Efetuar Pull. Se solicitado, clique em Confirmar para continuar o pull.
5. Clique no botão + (Criar branch).
6. Insira trigger_tests e, em seguida, clique em Criar. (Você pode dar um nome diferente ao branch.)
7. Feche este diálogo.

Etapa 7.2: Alterar o código compartilhado

1. No navegador do Workspace, na pasta Git best-notebooks, clique no arquivo covid_analysis/transforms.py.

2. Altere a terceira linha deste arquivo:

   # Filter by country code.
   

   Para isso:

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

Etapa 7.3: Verificar a alteração para disparar os testes

1. Ao lado do nome do arquivo, clique no botão do GIT branch trigger_tests.
2. Na caixa best-notebooks, na guia Alterações, verifique se covid_analysis/transforms.py está selecionado.
3. Para Mensagem de commit (obrigatório), insira Updated comment.
4. Em Descrição (opcional), insira This updates the comment for filter_country.
5. Clique em Fazer Commit e Efetuar Push.
6. Clique no link de pull request em Criar um pull request no seu provedor Git na faixa de opções e, em seguida, crie o pull request no GitHub.
7. Na página da solicitação de pull, aguarde o ícone ao lado de Executar testes do Databricks de pré-mesclagem/unit-test-notebook (pull_request) exibir uma marca de seleção verde. (Pode demorar um pouco até que o ícone apareça). Se houver um X vermelho em vez de uma marca de seleção verde, clique em Detalhes para descobrir o motivo. Se o ícone ou Detalhes não estiverem mais visíveis, clique em Mostrar todas as verificações.
8. Se a marca de seleção verde aparecer, mescle a solicitação de pull no branch main.