Práticas recomendadas de engenharia de software para notebooks

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

Neste guia prático, irá:

• Adicione notebooks às pastas Git do Azure Databricks para controle de versão.
• Extrair partes de código de um dos cadernos para um módulo partilhável.
• Testar o código partilhado.
• Executar os blocos de notas a partir de um trabalho do Azure Databricks.
• Opcionalmente, aplicar CI/CD ao código partilhado.

Requisitos

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

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

  Nota

  Se você criar um novo repositório, certifique-se de inicializar o repositório com pelo menos um arquivo, por exemplo, um README arquivo.

• Um espaço de trabalho do Azure Databricks. Crie um espaço de trabalho se ainda não tiver um.

• Um cluster multiuso do Azure Databricks no espaço de trabalho. Para executar notebooks durante a fase de design, anexe os notebooks a um cluster multiuso em execução. Mais tarde, este passo a passo usa um job do Azure Databricks para automatizar a execução dos notebooks nesse cluster. (Você também pode executar trabalhos em clusters de tarefas que existem apenas para o tempo de vida dos trabalhos.) Crie um cluster polivalente se ainda não tiver um.

Etapa 1: Configurar pastas do Databricks Git

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

Para permitir que seu espaço de trabalho se conecte ao seu repositório GitHub, você deve primeiro fornecer seu espaço de trabalho com suas credenciais do GitHub, se ainda não tiver feito isso.

Etapa 1.1: Forneça suas credenciais do GitHub

1. Clique no seu nome de utilizador no canto superior direito da área de trabalho e, em seguida, clique em Definições na lista pendente.
2. Na barra lateral Configurações, em Usuário, clique em Contas vinculadas.
3. Em Integração com Git, para provedor Git, selecione GitHub.
4. Clique em Token de acesso pessoal.
5. Para o nome de usuário ou e-mail do provedor Git, digite seu nome de usuário do GitHub.
6. Em Token, insira seu token de acesso pessoal do GitHub (clássico). Este token de acesso pessoal (clássico) deve ter as permissões de repo e workflow.
7. Clique em Guardar.

Etapa 1.2: Conecte-se ao repositório GitHub

1. Na barra lateral do espaço de trabalho, clique em Espaço de trabalho.
2. No navegador Workspace, expanda Utilizadores do > Workspace.
3. Clique com o botão direito do rato na pasta de nome de utilizador e, em seguida, 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 para o seu repositório GitHub. Este artigo pressupõe que o URL termina com best-notebooks.git, por exemplo https://github.com/<your-GitHub-username>/best-notebooks.git, .
   2. Para o provedor 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 bloco de anotações

Nesta etapa, você importa um bloco de anotações externo existente para o repositório. Você pode criar seus próprios blocos de anotações para este passo a passo, mas para acelerar as coisas, nós os fornecemos para você aqui.

Etapa 2.1: Criar uma ramificação de trabalho no repositório

Nesta subetapa, você cria uma ramificação nomeada eda em seu repositório. Essa ramificação permite que você trabalhe em arquivos e código independentemente da ramificação do main seu repo, que é uma prática recomendada de engenharia de software. (Você pode dar um nome diferente ao seu ramo.)

Nota

Em alguns repositórios, o main ramo pode ser nomeado master em vez disso. Em caso afirmativo, substitua main por master ao longo deste passo a passo.

Gorjeta

Se você não estiver familiarizado com o trabalho em ramificações do Git, consulte Ramificações do Git - Ramificações em poucas palavras no site do Git.

1. A pasta Git da Etapa 1.2 deve estar aberta. Caso contrário, na barra lateral do Workspace, expanda , em seguida, expanda a pasta com o seu nome de utilizador e clique na sua pasta Git.

2. Ao lado do nome da pasta sob a trilha de navegação do espaço de trabalho, clique no botão de ramificação principal do Git.

3. Na caixa de diálogo de melhores cadernos, clique no botão Criar ramo.

   Nota

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

4. Digite edae clique em Criar.

5. Feche esta caixa de diálogo.

Etapa 2.2: Importar o bloco de anotações para o repositório

Nesta subetapa, importas um notebook existente de outro repositório para o teu repositório. Este bloco de notas faz o seguinte:

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

Embora você possa criar seu próprio bloco de anotações em seu repositório aqui, importar um bloco de anotações existente ajuda a acelerar este passo a passo. Para criar um bloco de notas nesta ramificação ou mover um bloco de notas existente para esta ramificação em vez de importar um bloco de notas, consulte Utilização básica de ficheiros de espaço de trabalho.

1. Na pasta Git dos melhores blocos de notas, clique em Criar > Pasta.

2. Na caixa de diálogo Nova pasta, digite notebookse clique em Criar.

3. Na pasta de blocos de anotações , clique no kebab e, em seguida , em Importar.

4. Na caixa de diálogo Importar :

   1. Em Importar de, selecione URL.

   2. Insira o URL para os conteúdos brutos do covid_eda_raw notebook no repositório databricks/notebook-best-practices no GitHub. Para obter este URL: i. Aceda a https://github.com/databricks/notebook-best-practices. II. Clique na notebooks pasta. iii. Clique no covid_eda_raw.py arquivo. iv. Clique em Raw. v. Copie o URL completo da barra de endereço do navegador da Web para a caixa de diálogo Importar .

      Nota

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

   3. Clique em Importar.

Passo 2.3: Executar o caderno

1. Se o bloco de notas ainda não estiver a ser apresentado, abra a pasta de blocos de notas e, em seguida, clique no bloco de notas covid_eda_raw dentro da pasta.
2. Selecione o cluster ao qual anexar este bloco de anotações. Para obter instruções sobre como criar um cluster, consulte Criar um cluster.
3. Clique em Executar tudo.
4. Aguarde enquanto o bloco de notas é executado.

Depois de o notebook terminar de correr, deverá ver um gráfico dos dados apresentados, bem como mais de 600 linhas de dados brutos na tabela Delta. Se o cluster ainda não estava em execução quando você começou a executar este bloco de anotações, pode levar vários minutos para que o cluster seja iniciado antes de exibir os resultados.

Etapa 2.4: Registe e funde o caderno

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

1. Ao lado do nome do bloco de anotações, clique no botão de ramificação eda Git.
2. Na caixa de diálogo best-notebooks, no separador Alterações, certifique-se de que o ficheiro notebooks/covid_eda_raw.py está selecionado.
3. Em Mensagem de confirmação (obrigatório), digite Added raw notebook.
4. Para Descrição (opcional), insira This is the first version of the notebook.
5. Clique em Confirmar & Push.
6. Clique no link de pedido de pull no banner em Criar um pedido de pull no provedor Git.
7. No GitHub, crie o pedido de pull e, em seguida, faça o merge do pedido de pull na ramificação main.
8. De volta ao seu espaço de trabalho do Azure Databricks, feche a caixa de diálogo dos melhores notebooks se ainda estiver visível.

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

Nesta etapa, você move parte do código do bloco de anotações para um conjunto de funções compartilhadas fora do bloco de anotações. Isto permite que tu uses estas funções com outros notebooks semelhantes, o que pode acelerar a codificação futura e ajudar a garantir resultados de notebooks mais previsíveis e consistentes. Compartilhar esse código também permite que você teste mais facilmente essas funções, o que, como uma prática recomendada de engenharia de software, pode aumentar a qualidade geral do seu código à medida que você avança.

Etapa 3.1: Criar outra ramificação de trabalho no repositório

1. Ao lado do nome do bloco de anotações, clique no botão de ramificação eda Git.
2. Na caixa de diálogo melhores cadernos, clique na seta suspensa ao lado da ramificação eda e selecione main.
3. Clique no botão Puxar . Se lhe for pedido para continuar a puxar, clique em Confirmar.
4. Clique no botão Criar ramificação .
5. Introduza first_modulese, em seguida, clique em Criar. (Você pode dar um nome diferente ao seu ramo.)
6. Feche esta caixa de diálogo.

Etapa 3.2: Importar o bloco de anotações para o repositório

Para acelerar este passo a passo, nesta subetapa você importa outro bloco de anotações existente para o seu repositório. Este bloco de notas faz as mesmas coisas que o bloco de notas anterior, exceto que este bloco de notas irá chamar funções de código partilhado que são armazenadas fora do bloco de notas. Mais uma vez, podes criar o teu próprio bloco de anotações no teu repositório aqui e partilhar o código propriamente dito.

1. No navegador do Espaço de Trabalho, clique com o botão direito do rato na pasta blocos de notas, e depois clique em Importar.

2. Na caixa de diálogo Importar :

   1. Em Importar de, selecione URL.

   2. Insira o URL para os conteúdos brutos do covid_eda_modular notebook no repositório databricks/notebook-best-practices no GitHub. Para obter este URL: i. Aceda a https://github.com/databricks/notebook-best-practices. II. Clique na notebooks pasta. iii. Clique no covid_eda_modular.py arquivo. iv. Clique em Raw. v. Copie o URL completo da barra de endereço do navegador da Web para a caixa de diálogo Importar blocos de anotações .

      Nota

      A caixa de diálogo Importar Blocos de Notas funciona com URLs Git apenas para repositórios públicos.

   3. Clique em Importar.

Etapa 3.3: Adicionar as funções de suporte do código compartilhado do caderno

1. No navegador Espaço de Trabalho, clique com o botão direito do rato na pasta Git best-notebooks e depois clique em Criar > pasta.

2. Na caixa de diálogo Nova pasta, digite covid_analysise clique em Criar.

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

4. Na caixa de diálogo Novo Nome do Ficheiro, introduza transforms.py, e, em seguida, clique em Criar Ficheiro.

5. Na janela do editor de transforms.py , digite 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
   

Gorjeta

Para outras técnicas de compartilhamento de código, consulte Compartilhar código entre blocos de anotações Databricks.

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

O código anterior tem várias dependências do 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 melhora a reprodutibilidade usando versões definidas com precisão das bibliotecas.

1. No navegador Espaço de trabalho, clique com o botão direito do rato na pasta Git best-notebooks e clique em Criar Ficheiro.

   Nota

   Você deseja que o arquivo que lista as dependências do pacote vá para a raiz da pasta Git, e não para as pastas notebooks ou covid_analysis.

2. Na caixa de diálogo Novo Nome do Ficheiro, introduza requirements.txt, e, em seguida, clique em Criar Ficheiro.

3. Na janela do editor de requirements.txt , digite o seguinte código:

   Nota

   Se o requirements.txt arquivo 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
   

   Nota

   O arquivo anterior lista versões específicas do pacote. Para melhor compatibilidade, você pode fazer referência cruzada dessas versões com as que estão instaladas no cluster multiuso. Consulte a seção "Ambiente do sistema" para saber a versão do Databricks Runtime do seu cluster em Notas de versão, versões e compatibilidade do Databricks Runtime.

A sua estrutura do repositório agora deve ter esta aparência:

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

Etapa 3.5: Executar o bloco de anotações refatorado

Nesta subetapa, executa o covid_eda_modular notebook, que chama o código partilhado 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 bloco de anotações.
3. Clique em Executar tudo.
4. Aguarde enquanto o bloco de notas é executado.

Depois que o bloco de anotações terminar de ser executado, no bloco de anotações você verá resultados semelhantes aos do covid_eda_raw bloco de anotações: um gráfico dos dados, bem como mais de 600 linhas de dados brutos na tabela Delta. A principal diferença neste notebook é que usa-se um filtro diferente (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 bloco de anotações, pode levar vários minutos para que o cluster seja iniciado antes de exibir os resultados.

Passo 3.6: Verifique o bloco de notas e o respetivo código

1. Clique no botão de ramificação Git first_modules ao lado do nome do bloco de anotações.
2. Na caixa de diálogo Melhores blocos de anotações, na seção Alterações, verifique se as seguintes opções estão selecionadas:
   • requirements.txt
   • covid_analysis/transforms.py
   • Cadernos/covid_eda_modular.py
3. Em Mensagem de confirmação (obrigatório), digite Added refactored notebook.
4. Para Descrição (opcional), insira This is the second version of the notebook.
5. Clique em Confirmar & Push.
6. Clique no link de pedido de pull no banner em Criar um pedido de pull no provedor Git.
7. No GitHub, crie o pedido de pull e, em seguida, faça o merge do pedido de pull na ramificação main.
8. De volta ao seu espaço de trabalho do Azure Databricks, feche a caixa de diálogo dos melhores notebooks se ainda estiver visível.

Etapa 4: Testar o código compartilhado

Nesta etapa, você testa o código compartilhado da última etapa. No entanto, quer testar este código sem executar o covid_eda_modular notebook em si. Isso ocorre porque, se o código compartilhado falhar ao ser executado, o próprio bloco de anotações provavelmente também não será executado. Você quer detetar falhas em seu código compartilhado primeiro antes de ter seu bloco de anotações principal eventualmente falhar mais tarde. Esta técnica de teste é uma prática recomendada de engenharia de software.

Gorjeta

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

Etapa 4.1: Criar outra ramificação de trabalho no repositório

1. Clique no botão de ramificação Git first_modules ao lado do nome do bloco de anotações.
2. Na caixa de diálogo best-notebooks, clique na seta suspensa ao lado da first_modules e selecione main.
3. Clique no botão Puxar . Se lhe for pedido para continuar a puxar, clique em Confirmar.
4. Clique em Criar ramificação.
5. Introduza first_testse, em seguida, clique em Criar. (Você pode dar um nome diferente ao seu ramo.)
6. Feche esta caixa de diálogo.

Passo 4.2: Adicionar os testes

Nesta subetapa, você usa a estrutura pytest para testar seu código compartilhado. Nesses testes, você afirma se determinados resultados de teste são alcançados. Se qualquer teste produzir um resultado inesperado, esse teste específico falha na asserção e, portanto, o próprio teste falha.

1. No navegador Espaço de trabalho, clique com o botão direito do mouse na pasta Git e clique em Criar > pasta.

2. Na caixa de diálogo Nova pasta, digite testse clique em Criar.

3. Na pasta de testes, clique em Criar > arquivo.

4. Na caixa de diálogo Novo Nome do Ficheiro, introduza testdata.csv, e, em seguida, clique em Criar Ficheiro.

5. Na janela do editor 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 de testes, clique em Criar > arquivo.

7. Na caixa de diálogo Novo Nome do Ficheiro, introduza transforms_test.py, e, em seguida, clique em Criar Ficheiro.

8. Na janela do editor transforms_test.py, insira o seguinte código de teste. Esses testes usam equipamentos padrão pytest, bem como um DataFrame simulado de pandas 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()
   

A sua estrutura do repositório agora deve ter esta aparência:

├── 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 este passo a passo, nesta subetapa você usa um bloco de anotações importado para executar os testes anteriores. Este bloco de anotações baixa e instala os pacotes Python dependentes dos testes no seu espaço de trabalho, executa os testes e apresenta os resultados dos testes. Embora você possa executar pytest a partir do terminal da Web do cluster, executar pytest a partir de um caderno pode ser mais conveniente.

Nota

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

1. No navegador do Espaço de Trabalho, clique com o botão direito do rato na pasta blocos de notas, e depois clique em Importar.

2. Na caixa de diálogo Importar Blocos de Notas :

   1. Em Importar de, selecione URL.

   2. Insira o URL para os conteúdos brutos do run_unit_tests notebook no repositório databricks/notebook-best-practices no GitHub. Para obter este URL: i. Aceda a https://github.com/databricks/notebook-best-practices. II. Clique na notebooks pasta. iii. Clique no run_unit_tests.py arquivo. iv. Clique em Raw. v. Copie o URL completo da barra de endereço do navegador da Web para a caixa de diálogo Importar blocos de anotações .

      Nota

      A caixa de diálogo Importar Blocos de Notas funciona com URLs Git apenas para repositórios públicos.

   3. Clique em Importar.

3. Selecione o cluster ao qual anexar este bloco de anotações.

4. Clique em Executar tudo.

5. Aguarde enquanto o bloco de notas é executado.

Depois que o bloco de anotações terminar de ser executado, você verá informações sobre o número de testes aprovados e reprovados, juntamente com outros detalhes relacionados. Se o cluster ainda não estava em execução quando você começou a executar este bloco de anotações, pode levar vários minutos para que o cluster seja iniciado antes de exibir os resultados.

A sua estrutura do repositório agora deve ter esta aparência:

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

Passo 4.4: Verifique o caderno e os testes relacionados

1. Ao lado do nome do bloco de anotações, clique no botão de ramo do Git first_tests.
2. Na caixa de diálogo Melhores blocos de anotações, na seção Alterações, verifique se as seguintes opções estão selecionadas:
   • testes/transforms_test.py
   • Cadernos/run_unit_tests.py
   • testes/testdata.csv
3. Em Mensagem de confirmação (obrigatório), digite Added tests.
4. Para Descrição (opcional), digite These are the unit tests for the shared code..
5. Clique em Confirmar & Push.
6. Clique no link de pedido de pull no banner em Criar um pedido de pull no provedor Git.
7. No GitHub, crie o pedido de pull e, em seguida, faça o merge do pedido de pull na ramificação main.
8. De volta ao seu espaço de trabalho do Azure Databricks, feche a caixa de diálogo dos melhores notebooks se ainda estiver visível.

Etapa 5: Criar um trabalho para executar os notebooks

Nas etapas anteriores, você testou seu código compartilhado manualmente e executou seus blocos de anotações manualmente. Nesta etapa, você usa um trabalho do Azure Databricks para testar seu código compartilhado e executar seus blocos de anotações automaticamente, sob demanda ou em uma programação regular.

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

1. No espaço de trabalho, clique no Jobs & Pipelines na barra lateral.
2. Clique em Criar e depois Trabalho.
3. Edite o nome da função para ser covid_report.
4. Em Nome da tarefa, digite run_notebook_tests.
5. Para Tipo, selecione Portátil.
6. Em Source, selecione Git provider.
7. Clique em Adicionar uma referência git.
8. Na caixa de diálogo Informações do Git:
   1. Para URL do repositório Git, insira a URL de Clone com HTTPS para o seu repositório GitHub. Este artigo pressupõe que o URL termina com best-notebooks.git, por exemplo https://github.com/<your-GitHub-username>/best-notebooks.git, .
   2. Para o provedor Git, selecione GitHub.
   3. Para referência do Git (branch / tag / commit), digite main.
   4. Ao lado de referência do Git (ramo / tag / commit), selecione ramo.
   5. Clique em Confirmar.
9. Em Caminho, digite notebooks/run_unit_tests. Não adicione a extensão de arquivo .py.
10. Em Cluster, selecione o cluster a partir da etapa anterior.
11. Clique em Criar tarefa.

Nota

Nesse cenário, o Databricks não recomenda que você use o botão agendar no bloco de anotações, conforme descrito em Criar e gerenciar trabalhos agendados do bloco de anotações para agendar um trabalho para executar esse bloco de anotações periodicamente. Isso ocorre porque o botão agendar cria uma tarefa usando a cópia de trabalho mais recente do bloco de anotações no repositório do ambiente de trabalho. Em vez disso, o Databricks recomenda que você siga as instruções anteriores para criar um trabalho que use a versão confirmada mais recente do bloco de anotações no repositório.

Etapa 5.2: Criar uma tarefa de trabalho para executar o bloco de anotações principal

1. Clique no ícone + Adicionar tarefa .
2. É apresentado um menu pop-up. Selecione Notebook (Bloco de notas).
3. Em Nome da tarefa, digite run_main_notebook.
4. Para Tipo, selecione Portátil.
5. Em Caminho, digite notebooks/covid_eda_modular. Não adicione a extensão de arquivo .py.
6. Em Cluster, selecione o cluster a partir da etapa anterior.
7. Verificar se o valor de Depende do é 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.

   Nota

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

   1. Na barra lateral do ambiente Data Science & Engineering ou Databricks Mosaic AI , clique em Jobs & Pipelines.
   2. Na guia Execuções de trabalho, clique no valor 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 , no bloco run_main_notebook ou em ambos. Os resultados em cada bloco são os mesmos como se você mesmo executasse os cadernos, um a um.

Nota

Este trabalho era executado sob demanda. Para configurar este trabalho para ser executado regularmente, consulte Automatização de trabalhos com horários e gatilhos.

(Opcional) Etapa 6: Configurar o repositório para testar o código e executar o bloco de anotações automaticamente sempre que o código for alterado

Na etapa anterior, utilizou um trabalho para testar automaticamente o seu código partilhado e executar as suas anotações num momento específico ou de forma recorrente. No entanto, você pode preferir acionar testes automaticamente quando as alterações são mescladas no seu repositório GitHub, usando uma ferramenta de CI/CD, como Ações do GitHub.

Etapa 6.1: Configurar o acesso do GitHub ao seu espaço de trabalho

Nesta subetapa, você configura um fluxo de trabalho de Ações do GitHub que executa trabalhos no espaço de trabalho sempre que as alterações são mescladas em seu repositório. Você faz isso dando ao GitHub um token exclusivo do Azure Databricks para acesso.

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

Importante

Os notebooks são executados com todas as permissões de espaço de trabalho da conta associada ao token, portanto, o Databricks recomenda o uso de um principal de serviço. Se você realmente quiser fornecer o token de acesso pessoal do usuário do espaço de trabalho do Azure Databricks ao GitHub apenas para fins de exploração pessoal e entender que, por motivos de segurança, o Databricks desencoraja essa prática, consulte as instruções para criar o token de acesso pessoal do usuário do espaço de trabalho.

Etapa 6.2: Adicionar o fluxo de trabalho Ações do GitHub

Nesta etapa, você adiciona um fluxo de trabalho de GitHub Actions para executar o run_unit_tests notebook sempre que houver um pull request para o repositório.

Esta subetapa armazena o fluxo de trabalho de Ações do GitHub em um arquivo armazenado em vários níveis de pasta no repositório do GitHub. As Ações do GitHub exigem que exista uma hierarquia de pastas aninhada específica em seu repositório para funcionar corretamente. Para concluir esta etapa, você deve usar o site para seu repositório GitHub, porque a interface do usuário da pasta Git do Azure Databricks não oferece suporte à criação de hierarquias de pastas aninhadas.

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

2. Clique na seta ao lado de principal para expandir a lista suspensa Alternar ramificações ou tags.

3. Na caixa Localizar ou criar uma ramificação , digite adding_github_actions.

4. Clique em Criar ramificação: adding_github_actions de 'principal'.

5. Clique em Adicionar arquivo > Criar novo arquivo.

6. Em Nomeie seu arquivo, digite .github/workflows/databricks_pull_request_tests.yml.

7. Na janela do editor, digite o código a seguir. Este código usa o gatilho de pull_request da ação do GitHub Run Databricks Notebook para executar o run_unit_tests caderno.

   No código a seguir, substitua:

   • <your-workspace-instance-URL>com o nome da instância do Azure Databricks.
   • <your-access-token> com o token que você gerou anteriormente.
   • <your-cluster-id>com o 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 Confirmar alterações, insira Create databricks_pull_request_tests.yml a mensagem de confirmação

10. Selecione Confirmar diretamente no ramo adding_github_actions e clique em Confirmar alterações.

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

12. Na página de solicitação pull, aguarde até que o ícone ao lado de Run pre-merge Databricks tests / unit-test-notebook (pull_request) exiba uma marca de seleção verde. (Pode levar alguns momentos para 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 aparecendo, clique em Mostrar todas as verificações.

13. Se a marca de seleção verde aparecer, integre o pull request na main ramificação.

(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, em seguida, envia a alteração para o repositório GitHub, que imediatamente aciona os testes automaticamente, com base na Ação do GitHub da etapa anterior.

Etapa 7.1: Criar outra ramificação de trabalho no repositório

1. No navegador de espaço de trabalho, abra a pasta Git best-notebooks.
2. Ao lado do nome da pasta, clique no botão de ramificação do Git first_tests.
3. Na caixa de diálogo best-notebooks, clique na seta suspensa ao lado do ramo first_tests e selecione main.
4. Clique no botão Puxar . Se lhe for pedido para continuar a puxar, clique em Confirmar.
5. Clique no + botão (Criar ramificação).
6. Introduza trigger_testse, em seguida, clique em Criar. (Você pode dar um nome diferente ao seu ramo.)
7. Feche esta caixa de diálogo.

Etapa 7.2: Alterar o código compartilhado

1. No navegador Espaço de trabalho, na pasta Git best-notebooks, clique no ficheiro covid_analysis/transforms.py.

2. Altere a terceira linha deste ficheiro:

   # Filter by country code.
   

   Para isso:

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

Passo 7.3: Verifique a alteração para acionar os testes

1. Ao lado do nome do ficheiro, clique no botão da ramificação Git trigger_tests.
2. Na caixa de diálogo melhores notebooks, no separador Alterações, verifique se covid_analysis/transforms.py está selecionado.
3. Em Mensagem de confirmação (obrigatório), digite Updated comment.
4. Para Descrição (opcional), insira This updates the comment for filter_country.
5. Clique em Confirmar & Push.
6. Clique no link de pedido de pull em Crie um pedido de pull no seu fornecedor git no banner e, em seguida, crie o pedido de pull no GitHub.
7. Na página de solicitação pull, aguarde até que o ícone ao lado de Run pre-merge Databricks tests / unit-test-notebook (pull_request) exiba uma marca de seleção verde. (Pode levar alguns momentos para 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 aparecendo, clique em Mostrar todas as verificações.
8. Se a marca de seleção verde aparecer, integre o pull request na main ramificação.