Práticas recomendadas de engenharia de software para notebooks

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

Neste tutorial, você:

• Adicione notebooks às pastas Git do Azure Databricks para controle de versão.
• Extrair trechos de código de um dos notebooks em um módulo compartilhável.
• Testar o código compartilhado.
• Execute os blocos de anotações de um trabalho de Azure Databricks.
• Opcionalmente, aplicar CI/CD ao código compartilhado.

Requisitos

Para concluir este guia, você deve fornecer os seguintes recursos:

• Um repositório remoto com um provedor Git compatível com o Databricks. O passo a passo deste artigo usa GitHub. Este passo a passo pressupõe que você tenha um repositório GitHub chamado best-notebooks disponível. (Você pode dar ao repositório um nome diferente. Se você fizer isso, substitua best-notebooks pelo nome do repositório ao longo deste passo a passo.) Criar um repositório GitHub se 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 Azure Databricks espaço de trabalho. Crie um workspace caso ainda não tenha um.

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

Etapa 1: Configurar pastas Git do Databricks

Nesta etapa, você conecta seu repositório do GitHub existente às pastas Git do Azure Databricks no espaço de trabalho existente do Azure Databricks.

Para permitir que seu workspace se conecte ao seu repositório de GitHub, primeiro você deve fornecer seu workspace com suas credenciais de GitHub, caso ainda não tenha feito isso.

Etapa 1.1: fornecer suas credenciais de GitHub

1. Clique no seu nome de usuário no canto superior direito da área de trabalho e, em seguida, clique em Configurações na lista suspensa.
2. Na barra lateral Configurações, em Usuário, clique em Contas vinculadas.
3. Em Git integration, para Git provider, selecione GitHub.
4. Clique em Token de acesso pessoal.
5. Para Git provider username or email, insira seu nome de usuário GitHub.
6. Para Token, insira seu token de acesso pessoal GitHub (clássico). 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 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. Para URL do repositório Git, insira a URL de Clone com HTTPS do seu repositório GitHub. Este artigo pressupõe que sua URL termine com best-notebooks.git, por exemplo, https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. Para Git provider, 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 para este tutorial, mas, para acelerar as coisas, os fornecemos para você aqui.

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

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

1. A pasta Git da Etapa 1.2 deve estar aberta. Caso contrário, na barra lateral do Workspace, expanda Workspace > Usuários, depois expanda a pasta com o seu 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 do que best-notebooks, o título desta janela de diálogo será diferente, tanto aqui quanto 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 seu repositório. Este notebook faz o seguinte:

• Copia um arquivo CSV do repositório owid/covid-19-data GitHub em um cluster em seu 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 DataFramepandas.
• Filtra os dados para conter métricas somente do Estados Unidos.
• Exibe um gráfico dos dados.
• Salva o Pandas DataFrame como uma API do Pandas no SparkDataFrame.
• 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 Delta no seu workspace.
• Exibe o conteúdo da tabela 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 > Diretório.
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 para o conteúdo bruto do bloco de anotações covid_eda_raw no repositório databricks/notebook-best-practices no 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: Realizar check-in e mesclar o notebook

Nesta subetapa, você salvará seu trabalho até agora em seu repositório do GitHub. Em seguida, mescla o bloco de anotações do branch de trabalho no branch do main repositório.

1. Ao lado do nome do bloco de anotações, clique no botão da ramificação eda do Git.
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 Commit e Push.
6. Clique no link de pull request em Criar um pull request no seu fornecedor de Git no banner.
7. Em GitHub, crie a solicitação de pull e mescle a solicitação de pull no branch main.
8. De volta ao workspace Azure Databricks, feche o diálogo best-notebooks se ainda estiver sendo exibido.

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 bloco de anotações, clique no botão da ramificação eda do Git.
2. Na caixa de diálogo best-notebooks, clique na seta suspensa ao lado da ramificação eda e selecione main.
3. Clique no botão Pull. Se solicitado, clique em Confirmar para prosseguir com 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 compartilhar o código você mesmo.

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 para o conteúdo bruto do bloco de anotações covid_eda_modular no repositório databricks/notebook-best-practices no 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 na caixa de diálogo Importar Blocos de Anotações .

      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
   

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

O código anterior tem várias dependências de pacote Python para permitir que o código seja executado corretamente. 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 que o arquivo que lista as dependências do pacote vá para a raiz do diretório Git, e não para os diretórios 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 comparar essas versões com aquelas instaladas no cluster de uso geral. Consulte a seção "Ambiente do sistema" para a versão do Databricks Runtime do cluster em versões e compatibilidade das notas de lançamento 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 da branch Git 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 Commit e Push.
6. Clique no link de pull request em Criar um pull request no seu fornecedor de Git no banner.
7. Em GitHub, crie a solicitação de pull e mescle a solicitação de pull no branch main.
8. De volta ao workspace Azure Databricks, feche o diálogo best-notebooks se ainda estiver sendo exibido.

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 detectar falhas no seu código compartilhado primeiro, antes que o notebook principal eventualmente falhe depois. Essa técnica de teste é uma prática recomendada de engenharia de software.

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

1. Ao lado do nome do notebook, clique no botão da branch Git 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 Pull. Se solicitado, clique em Confirmar para prosseguir com 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 falha na asserção e, portanto, o teste em si falha.

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 de Python dependentes dos testes em seu workspace, executa os testes e relata os resultados dos testes. Embora você possa executar pytest no terminal Web do cluster, a execução pytest de um notebook pode ser mais conveniente.

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 Blocos de Anotações :

   1. Em Importar de, selecione URL.

   2. Insira a URL para o conteúdo bruto do bloco de anotações run_unit_tests no repositório databricks/notebook-best-practices no 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 na caixa de diálogo Importar Blocos de Anotações .

      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, você deverá ver informações no notebook sobre o número de testes bem-sucedidos e falhados, 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 da branch Git 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 Commit e Push.
6. Clique no link de pull request em Criar um pull request no seu fornecedor de Git no banner.
7. Em GitHub, crie a solicitação de pull e mescle a solicitação de pull no branch main.
8. De volta ao workspace Azure Databricks, feche o diálogo best-notebooks se ainda estiver sendo exibido.

Etapa 5: Criar um trabalho para executar os notebooks

Nas etapas anteriores, você testou manualmente o código compartilhado e executou manualmente os notebooks. Nesta etapa, você usará um trabalho Azure Databricks para testar seu código compartilhado e executar seus blocos de anotações automaticamente, sob demanda ou em um agendamento regular.

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

1. No seu espaço de trabalho, clique no Tarefas e Pipelines na barra lateral.
2. Clique em Criar e depois em Job.
3. Edite o nome do trabalho para que seja covid_report.
4. Clique no bloco do Notebook para configurar a primeira tarefa. Se o Notebook não estiver disponível, clique em Adicionar outro tipo de tarefa e procure por Notebook.
5. Em Nome da tarefa, insira run_notebook_tests.
6. Se necessário, selecione Notebook no menu suspenso Tipo.
7. Em Fonte, selecione Provedor Git.
8. Clique em Adicionar uma referência do Git.
9. Na caixa de diálogo Informações do Git:
   1. Para URL do repositório Git, insira a URL de Clone com HTTPS do seu repositório GitHub. Este artigo pressupõe que sua URL termine com best-notebooks.git, por exemplo, https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. Para Git provider, 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.
10. Em Caminho, insira notebooks/run_unit_tests. Não adicione a extensão de arquivo .py.
11. Em Cluster, selecione o cluster da etapa anterior.
12. Clique em Criar tarefa.

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

1. Clique no ícone + Adicionar tarefa.
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 Databricks Mosaic AI, clique em Trabalhos e Pipelines.
   2. Na guia Execuções de Tarefas, clique no valor de Hora de início da tarefa mais recente com covid_report na coluna Tarefas.

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.

(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 determinado momento ou com recorrência. No entanto, talvez você prefira disparar testes automaticamente quando as alterações forem mescladas em seu repositório de GitHub, usando uma ferramenta de CI/CD, como GitHub Actions.

Etapa 6.1: Configurar o acesso GitHub ao workspace

Neste subetapa, você configura um fluxo de trabalho do GitHub Actions que executa tarefas no espaço de trabalho sempre que as alterações são mescladas em seu repositório. Faça isso dando a GitHub um token de Azure Databricks exclusivo para acesso.

Por motivos de segurança, o Databricks desencoraja você a fornecer o token de acesso pessoal do usuário do workspace Azure Databricks para GitHub. Em vez disso, o Databricks recomenda que você forneça a GitHub um token Microsoft Entra ID associado a uma entidade de serviço Microsoft Entra ID. Para obter instruções, consulte a seção Azure da página Run Databricks Notebook GitHub Action no GitHub Actions Marketplace.

Etapa 6.2: Adicionar o fluxo de trabalho GitHub Actions

Neste substep, você adiciona um fluxo de trabalho GitHub Actions para executar o notebook run_unit_tests sempre que houver uma solicitação de pull para o repositório.

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

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

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

3. Na caixa Localizar ou criar um ramo, digite adding_github_actions.

4. Clique em Criar um branch: adding_github_actions a partir 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 do Run Databricks Notebook GitHub Action para executar o notebook run_unit_tests.

   No seguinte código, substitua:

   • <your-workspace-instance-URL> com seu Azure Databricks nome da instância.
   • <your-access-token> com o token que você gerou anteriormente.
   • <your-cluster-id> com sua ID de computação clássica 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 Confirmar alterações, insira Create databricks_pull_request_tests.yml em Mensagem do 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 solicitar pull e então crie a solicitação de pull.

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 em GitHub para disparar testes

Nesta etapa, você faz uma alteração no código compartilhado e, em seguida, envia a alteração por push para o repositório GitHub, que dispara imediatamente os testes automaticamente, com base na ação GitHub 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 first_tests branch do Git.
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 Pull. Se solicitado, clique em Confirmar para prosseguir com 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 trigger_tests branch do Git.
2. Na caixa de diálogo best-notebooks, na aba Alterações, certifique-se de que covid_analysis/transforms.py esteja 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 Commit e Push.
6. Clique no link de solicitação de pull em Criar uma solicitação pull em seu provedor git no banner e, em seguida, crie a solicitação de pull 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.