Melhores práticas de engenharia de software para notebooks

Neste artigo, você encontrará um guia prático que mostra como aplicar as melhores práticas de engenharia de software aos seus notebooks Databricks, incluindo controle de versão, compartilhamento de código, testes e, opcionalmente, integração contínua (CI) e entrega contínua (CD)

Neste guia, você irá:

  • Adicione o Notebook às pastas Git do Databricks para controle de versão.

  • Extrair partes do código de um dos notebooks em um módulo compartilhável.

  • Testar o código compartilhado.

  • Executar os notebooks em um job do 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 o GitHub. Este passo a passo pressupõe que você tenha um repositório GitHub chamado best-notebooks disponível. (Você pode dar um nome diferente ao seu repositório. Se o fizer, substitua best-notebooks pelo nome do seu repositório ao longo deste passo a passo.) Crie um repositório do GitHub se ainda não tiver um.

    Observação

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

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

  • Um Databricks agrupa todo-propósito no workspace. Para executar Notebook durante a fase de design, você anexa o Notebook a um cluster em execução todo-propósito. Posteriormente, este passo a passo usa um Job do Databricks para automatizar a execução do Notebook nesses clusters. (Você também pode executar Job em Job trabalho que existem apenas para os Jobtempos de vida do .) Crie um cluster todo-propósito se ainda não tiver um.

o passo 1: Configurar as pastas do Databricks Git

Neste passo, o senhor conecta seu GitHub repo existente às pastas Git da Databricks em seu Databricks workspace existente.

Para permitir que seu workspace se conecte ao repo do GitHub, você deve primeiro fornecer ao seu workspace suas credenciais do GitHub, se ainda não tiver feito isso.

Passo 1.1: forneça suas credenciais do GitHub

  1. Clique no seu nome de usuário no canto superior direito do site workspace e, em seguida, clique em Settings (Configurações ) na lista dropdown.

  2. Na barra lateral Settings (Configurações ), em User (Usuário), clique em Linked account (Conta vinculada).

  3. Em integração Git, para provedor Git, selecione GitHub.

  4. Clique em access tokenpessoal.

  5. Para nome de usuário ou e-mail do provedor Git, insira seu nome de usuário do GitHub.

  6. Para Token, insira seu token de acesso pessoal do GitHub (clássico). Este token de acesso pessoal (clássico) deve ter as permissões repo e fluxo de trabalho.

  7. Clique em Salvar.

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

  1. Na barra lateral do site workspace, clique em workspace.

  2. No navegador workspace navegador, expanda workspace > Usuários.

  3. Clique com o botão direito do mouse na pasta de nome de usuário e clique em Create > Git folder.

  4. Na caixa de diálogo Criar pasta Git:

    1. Para o URL do repositório do Git, insira o clone do GitHub com o URL HTTPS do repo do seu GitHub. Este artigo pressupõe que seu URL termine com best-notebooks.git, por exemplo https://github.com/<your-GitHub-username>/best-notebooks.git.

    2. Para provedor Git, selecione GitHub.

    3. Deixe o nome da pasta Git definido como o nome do seu site repo, por exemplo, best-notebooks.

    4. Clique em Create Git folder (Criar pasta Git).

Passo 2: importar e executar o notebook

Nesta etapa, você importa um Notebook externo existente para seu repositório. Você poderia criar seus próprios notebooks para este tutorial, mas para agilizar, fornecemos os notebooks aqui para você

Passo 2.1: Crie uma ramificação funcional no repo

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

Observação

Em alguns repos, a ramificação main pode ser chamada de master. Se for o caso, substitua main por master ao longo deste guia.

Dica

Se você não estiver acostumado a trabalhar com ramificações Git, consulte Git Branches - Branches in a Nutshell (Ramificações Git - Um resumo sobre as ramificações) no site do Git.

  1. A pasta Git do passo 1.2 deve estar aberta. Caso contrário, na barra lateral workspace barra lateral, expanda workspace > Users, expanda a pasta de nome de usuário e clique na pasta Git.

  2. Ao lado do nome da pasta na barra de navegação workspace, clique no botão do ramo principal do Git.

  3. Na caixa de diálogo Best-Notebook, clique no botão Create branch (Criar ramificação ).

    Observação

    Caso o seu repo tenha um nome diferente de best-notebooks, o título desta caixa de diálogo será diferente, aqui e durante todo este guia.

  4. Digite eda e clique em Create.

  5. Feche essa caixa de diálogo.

Passo 2.2: importe o notebook para o repo

Nesta subpasso, você importa um Notebook existente de outro repo para o seu repo. Este Notebook faz o seguinte:

  • Copia um arquivo CSV do repositório GitHub owid/covid-19-data para um cluster no workspace. Este arquivo CSV contém dados públicos sobre hospitalizações de COVID-19 e métricas de cuidados intensivos de todo o mundo.

  • Lê o conteúdo do arquivo CSV em um pandas DataFrame.

  • Filtra os dados para conter métricas apenas dos Estados Unidos.

  • Exibe um gráfico dos dados.

  • Salva o DataFrame do pandas como uma API do Pandas no Spark DataFrame.

  • Executa a limpeza de dados na API do Pandas no Spark DataFrame.

  • Grava a API do Pandas no Spark DataFrame como uma tabela Delta em seu workspace.

  • Exibe o conteúdo do índice Delta.

Embora o senhor possa criar seu próprio Notebook em seu repo aqui, importar um Notebook existente ajuda a acelerar este passo a passo. Para criar um Notebook nessa ramificação ou mover um Notebook existente para essa ramificação em vez de importar um Notebook, consulte Uso básico dos arquivos de espaço de trabalho.

  1. Na pasta best-Noteb ook Git, clique em Create > Folder (Criar pasta).

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

  3. Na pasta Notebook, clique no botão e, em seguida, em Import (Importar).

  4. Na caixa de diálogo Importar:

    1. Para Importar de, selecione o URL.

    2. Insira a URL do conteúdo bruto do covid_eda_raw notebook no databricks/notebook-best-practices repo no GitHub. Para obter esse URL:

      1. Acesse https://github.com/databricks/notebook-best-practices.

      2. Clique na pasta notebooks .

      3. Clique no arquivo covid_eda_raw.py.

      4. Clique em Bruto.

      5. Copie o URL completo da barra de endereços do navegador da Web para a caixa de diálogo Importar.

        Observação

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

    3. Clique em Importar.

Passo 2.3: execute o notebook

  1. Se o site Notebook ainda não estiver sendo exibido, abra a pasta Notebook e clique em covid_eda_raw Notebook 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.

Após a conclusão da execução do notebook, no próprio notebook, você deverá ver um gráfico dos dados, bem como mais de 600 linhas de dados brutos na tabela Delta.Caso o cluster ainda não estava em execução quando você começou a executar este notebook, pode levar vários minutos para o cluster iniciar antes de exibir os resultados.

Passo 2.4: faça o check-in e o merge do notebook

Neste subpasso, você salva seu trabalho até agora em seu repositório do GitHub. Em seguida, você faz o merge no Notebook de sua ramificação de trabalho na ramificação main de seu repo.

  1. Ao lado do nome do site Notebook, clique no botão eda Git branch.

  2. Na caixa de diálogo melhores notebooks, na tab Alterações, verifique se o arquivo notebooks/covid_eda_raw.py está selecionado.

  3. Para commit message (obrigatório), digite Added raw notebook.

  4. Para Descrição (opcional), insira This is the first version of the notebook.

  5. Clique em Confirmar e enviar.

  6. Clique no link da solicitação pull em Create a pull request on your git provider (Criar uma solicitação pull no seu provedor git ) no banner.

  7. No GitHub, crie a pull request e, em seguida, faça o merge da pull request no branch main.

  8. De volta à área de trabalho do Databricks, feche a caixa de diálogo melhores notebooks se ela ainda estiver sendo exibida.

Passo 3: mova o código para um módulo compartilhado

Neste passo, você move parte do código em seu Notebook para um conjunto de funções compartilhadas fora de seu Notebook. Isso permite que você use essas funções com outros Notebook semelhantes, o que pode acelerar a codificação futura e ajudar a garantir resultados Notebook mais previsíveis e consistentes. Compartilhar esse código também permite que você teste essas funções com mais facilidade, 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.

Passo 3.1: crie outra ramificação de trabalho no repo

  1. Ao lado do nome do site Notebook, clique no botão eda Git branch.

  2. Na caixa de diálogo Melhores Blocos de Anotações , clique na seta suspensa ao lado da ramificação EDA e selecione Principal.

  3. Clique no botão Pull. Caso você receba uma mensagem perguntando se deseja continuar com o pull, clique em Confirmar.

  4. Clique no botão Create Branch (Criar filial ).

  5. Digite first_modules e clique em Create. (O senhor pode dar um nome diferente à sua filial).

  6. Feche essa caixa de diálogo.

Passo 3.2: importe o Notebook para o repo

Para acelerar este guia, neste subpasso você importa outro Notebook existente para seu repositório. Este Notebook faz as mesmas coisas que o Notebook anterior, exceto que este Notebook chamará funções de código compartilhado que são armazenadas fora do Notebook. Novamente, você pode criar seu próprio Notebook em seu repositório aqui e fazer o compartilhamento de código por conta própria.

  1. No navegador workspace No navegador, clique com o botão direito do mouse na pasta Notebook e clique em Importar.

  2. Na caixa de diálogo Importar:

    1. Para Importar de, selecione o URL.

    2. Insira a URL do conteúdo bruto do covid_eda_modular notebook no databricks/notebook-best-practices repo no GitHub. Para obter esse URL:

      1. Acesse https://github.com/databricks/notebook-best-practices.

      2. Clique na pasta notebooks .

      3. Clique no arquivo covid_eda_modular.py.

      4. Clique em Bruto.

      5. Copie o URL completo da barra de endereços do seu navegador na caixa de diálogo Importar Notebooks.

        Observação

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

    3. Clique em Importar.

Passo 3.3: adicione as funções de código compartilhado do suporte do notebook

  1. No navegador workspace No navegador, clique com o botão direito do mouse na pasta best-Notebook Git e clique em Create > Folder (Criar > Pasta).

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

  3. Na pasta covid_a nalysis, clique em Create > File (Criar arquivo).

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

  5. Na janela do editor 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

Dica

Para outras técnicas de compartilhamento de código, consulte Compartilhar código entre notebooks do Databricks.

Passo 3.4: adicione 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. Neste subpasso, você declara essas dependências de pacote. A declaração de dependências melhora a reprodutibilidade ao usar versões precisamente definidas das bibliotecas.

  1. No navegador workspace No navegador, clique com o botão direito do mouse na pasta best-Notebook Git e clique em Create > File.

    Observação

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

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

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

    Observação

    Se o arquivo requirements.txt não estiver visível, você poderá precisar atualizar seu 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 específicas de pacotes. Para melhor compatibilidade, você pode cruzar essas versões com aquelas que estão instaladas no todo-propósito dos seus clusters . Consulte a seção “Ambiente do sistema” para a versão do Databricks Runtime dos seus clustersem Databricks Runtime notas sobre a versão versões e compatibilidade.

Sua estrutura de repositório agora deve ficar assim:

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

Passo 3.5: execute o notebook refatorado

Neste subpasso, você executa o covid_eda_modular Notebook, que chama o código compartilhado em covid_analysis/transforms.py.

  1. No navegador workspace navegador, clique em covid_eda_modular Notebook dentro da pasta Notebook.

  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 terminar, no bloco de anotações você verá resultados semelhantes aos notebooks covid_eda_raw: um gráfico dos dados, bem como mais de 600 linhas de dados brutos na tabela Delta. A principal diferença com este notebook é que um filtro diferente é usado (uma iso_code de DZA em vez de USA). Caso o cluster ainda não estava em execução quando você começou a executar este notebook, pode levar vários minutos para o cluster iniciar antes de exibir os resultados.

Passo 4: testar o código compartilhado

Neste passo, você testa o código compartilhado do último passo. No entanto, você deseja testar esse código sem executar o próprio Notebook covid_eda_modular. Isso ocorre porque, se o código compartilhado não for executado, o próprio Notebook provavelmente também não será executado. Você deseja detectar falhas em seu código compartilhado primeiro, antes que seu Notebook principal eventualmente falhe mais tarde. Essa técnica de teste é uma prática recomendada de engenharia de software.

Dica

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

Passo 4.1: criar outra ramificação de trabalho no repositório

  1. Ao lado do nome Notebook, clique no botão first_modules Git branch.

  2. na caixa de diálogo melhores livros, clique na seta suspensa ao lado da ramificação first_modules e selecione principal.

  3. Clique no botão Pull. Caso você receba uma mensagem perguntando se deseja continuar com o pull, clique em Confirmar.

  4. Clique em Create Branch.

  5. Digite first_tests e clique em Create. (O senhor pode dar um nome diferente à sua filial).

  6. Feche essa caixa de diálogo.

Passo 4.2: adicionar os testes

Neste subpasso, 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 algum teste produzir um resultado inesperado, esse teste específico falhará na asserção e, portanto, o próprio teste falhará.

  1. No navegador workspace No navegador, clique com o botão direito do mouse na pasta Git e clique em Create > Folder (Criar > Pasta).

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

  3. Na pasta de testes, clique em Create > File (Criar arquivo).

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

  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 Create > File (Criar arquivo).

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

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

Sua estrutura de repositório agora deve ficar assim:

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

Passo 4.3: executar os testes

Para acelerar este guia, neste subpasso você usa um Notebook importado para executar os testes anteriores. Este Notebook faz o download e instala os pacotes 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, executar pytest em um notebook pode ser mais conveniente.

Observação

Executar o pytest todos os arquivos são cujos nomes seguem o test_*.py ou /*_test.py no diretório atual e seus subdiretórios são executados.

  1. No navegador workspace No navegador, clique com o botão direito do mouse na pasta Notebook e clique em Importar.

  2. Na caixa de diálogo Importar notebooks:

    1. Para Importar de, selecione o URL.

    2. Insira a URL do conteúdo bruto do run_unit_tests notebook no databricks/notebook-best-practices repo no GitHub. Para obter esse URL:

      1. Acesse https://github.com/databricks/notebook-best-practices.

      2. Clique na pasta notebooks .

      3. Clique no arquivo run_unit_tests.py.

      4. Clique em Bruto.

      5. Copie o URL completo da barra de endereços do seu navegador na caixa de diálogo Importar Notebooks.

        Observação

        A caixa de diálogo Importar Notebooks funciona apenas com 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.

Após a conclusão da execução do notebook, no próprio notebook você deve ver informações sobre o número de testes aprovados e falhados, juntamente com outros detalhes relacionados.Caso o cluster ainda não estava em execução quando você começou a executar este notebook, pode levar vários minutos para o cluster iniciar antes de exibir os resultados.

Sua estrutura de repositório agora deve ficar assim:

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

Passo 5: criar um trabalho para executar os notebooks

Nos passos anteriores, você testou seu código compartilhado manualmente e executou seu Notebook manualmente. Neste passo, você usa um job do Databricks para testar seu código compartilhado e executar seu Notebook automaticamente, sob demanda ou em um programar regular.

Passo 5.1: Criar uma tarefa de trabalho para executar o notebook de notas de teste .

  1. Na barra lateral workspace, clique em fluxo de trabalho.

  2. Na tab Trabalhos, clique em Criar Job.

  3. Edite o nome do site Job para que seja covid_report.

  4. Em Nome da tarefa, insira run_notebook_tests.

  5. Para o Tipo, selecione Notebook.

  6. Em Source (Fonte), selecione o provedor Git.

  7. Clique em Adicionar uma referência Git.

  8. Na caixa de diálogo Informações do Git:

    1. Para o URL do repositório do Git, insira o clone do GitHub com o URL HTTPS do repo do seu GitHub. Este artigo pressupõe que seu URL termine com best-notebooks.git, por exemplo https://github.com/<your-GitHub-username>/best-notebooks.git.

    2. Para provedor Git, selecione GitHub.

    3. Para referência do Git (ramificação/tag/commit), insira main.

    4. Próximo a Referência do Git (ramificação/tag/commit), selecione ramificação.

    5. Clique em Confirm (Confirmar).

  9. Para o Caminho, insira notebooks/run_unit_tests. Não adicione a extensão de arquivo .py.

  10. Para Cluster, selecione o cluster na etapa anterior.

  11. Clique em Criar tarefa.

Observação

Neste cenário, o Databricks não recomenda que você utilize o botão de programação no notebook, conforme descrito em Criar e gerenciar trabalhos programados do notebook para agendar um trabalho para executar este notebook periodicamente. Isso ocorre porque o botão programar cria um Job usando a cópia de trabalho mais recente do Notebook no repo workspace . Em vez disso, o Databricks recomenda que você siga as instruções anteriores para criar um Job que use a versão mais recente confirmada do Notebook no repositório.

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

  1. Clique no ícone + Adicionar tarefa.

  2. Será exibido um menu pop-up. Selecione Notebook.

  3. Em Nome da tarefa, insira run_main_notebook.

  4. Para o Tipo, selecione Notebook.

  5. Para o Caminho, insira notebooks/covid_eda_modular. Não adicione a extensão de arquivo .py.

  6. Para Cluster, selecione o cluster na etapa anterior.

  7. Verificar se o valor Depende de é run_notebook-tests.

  8. Clique em Criar tarefa.

Passo 5.3: Executar o trabalho

  1. Clique em Run now (Executar agora).

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

    Observação

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

    1. Na barra lateral do ambiente Ciência e Engenharia de Dados ou Databricks Machine Learning, clique em Fluxos de Trabalho.

    2. Na tab Execuções do trabalho, clique no valor Iniciar horário do job mais recente com covid_report na coluna Jobs.

  3. Para ver os resultados do job, clique no bloco run_notebook_tests, no bloco run_main_notebook ou em ambos. Os resultados em cada bloco são os mesmos aos obtidos caso você tivesse executado os notebooks você mesmo, um por um.

Observação

Este Job é executado sob demanda. Para configurar esse Job para ser executado regularmente, consulte Adicionar um programa de Job .

(Opcional) Passo 6: configure o repo para testar o código e executar o notebook automaticamente sempre que o código for alterado

No passo anterior, o senhor usou o site Job para testar automaticamente o código compartilhado e executar o Notebook em um determinado momento ou de forma recorrente. No entanto, o senhor pode preferir acionar os testes automaticamente quando as alterações forem mescladas no GitHub repo, usando uma ferramenta de CI/CD, como o GitHub Actions.

Passo 6.1: configurar o acesso do GitHub ao workspace

Nesta subetapa, o senhor configura um fluxo de trabalho do GitHub Actions que executa o Job no site workspace sempre que as alterações são mescladas no seu repositório. O senhor faz isso fornecendo ao GitHub um tokens Databricks exclusivo para acesso.

Por motivos de segurança, o Databricks recomenda que você não compartilhe o token de acesso pessoal do usuário do workspace do Databricks para o GitHub. Em vez disso, o Databricks recomenda que você forneça ao GitHub um token de acesso do Databricks associado a uma entidade de serviço do Databricks.Para obter mais informações, consulte a seção AWS da página Run Databricks Notebook GitHub Action no GitHub Actions Marketplace.

Importante

Notebook são executados com todas as permissões workspace da identidade associada aos tokens, portanto a Databricks recomenda o uso de uma entidade de serviço. Se você realmente deseja fornecer workspace pessoal access token do usuário do Databricks ao GitHub apenas para fins de exploração pessoal e entende que, por motivos de segurança, o Databricks desencoraja essa prática, consulte as instruções para criar workspace pessoal do usuário access token.

Passo 6.2: adicione o fluxo de trabalho do GitHub Actions

Neste subpasso, você adiciona um fluxo de trabalho do GitHub Actions para executar o Notebook run_unit_tests sempre que houver uma solicitação pull para o repo.

Esta subetapa armazena o fluxo de trabalho do GitHub Actions em um arquivo que é armazenado em vários níveis de pasta no seu GitHub repo. O GitHub Actions requer a existência de uma hierarquia específica de pastas aninhadas em seu site repo para funcionar corretamente. Para concluir esse passo, o senhor deve usar o site do GitHub repo, pois a interface de usuário da pasta Git da Databricks não oferece suporte à criação de hierarquias de pastas aninhadas.

  1. No site do seu repos GitHub, clique na tab Código .

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

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

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

  5. Clique em "Adicionar arquivo > Criar novo arquivo".

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

  7. Na janela do editor, digite o seguinte código. Esse código usa o gancho pull_request do Databricks Notebook GitHub Actions para executar o run_unit_tests Notebook.

    No código a seguir, substitua:

    • <your-workspace-instance-URL> com o nome da instância do Databricks.

    • <your-access-token> com o token que você gerou anteriormente.

    • <your-cluster-id> com o IDclusters 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 commit changes, digite Create databricks_pull_request_tests.yml na mensagemcommit

  10. Selecione commit diretamente no branch adding_github_actions e clique em commit changes.

  11. Na tab Código, clique em "Comparar e solicitação de pull" e, em seguida, crie a solicitação do pull.

  12. Na página de solicitação do pull, aguarde até que o ícone ao lado de Executar testes de pré-merge do Databricks / unit-test-notebook (pull_request) exiba uma marca de verificação verde. (Pode levar alguns instantes para que o ícone seja exibido). Se houver um X vermelho em vez de uma marca de verificaçã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 marcas'.

  13. Se a marca de verificação verde for exibida, faça o marge na solicitação pull na ramificação main.

(Opcional) Passo 7: atualize o código compartilhado no GitHub para acionar testes

Neste passo, o senhor faz uma alteração no código compartilhado e, em seguida, envia a alteração para o seu GitHub repo, que imediatamente aciona os testes automaticamente, com base no GitHub Actions do passo anterior.

Passo 7.1: Criar outra ramificação de trabalho no repo

  1. No navegador workspace navegador, abra a pasta best-Notebook Git.

  2. Ao lado do nome da pasta, clique no botão do ramo Git first_tests.

  3. Na caixa de diálogo best-Notebook, clique na seta suspensa ao lado da ramificação first_tests e selecione main.

  4. Clique no botão Pull. Caso você receba uma mensagem perguntando se deseja continuar com o pull, clique em Confirmar.

  5. Clique no botão + (Criar ramificação).

  6. Digite trigger_tests e clique em Create. (O senhor pode dar um nome diferente à sua filial).

  7. Feche essa caixa de diálogo.

Passo 7.2: alterar o código compartilhado

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

  2. Altere a terceira linha desse arquivo:

    # Filter by country code.

    Para:

    # 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 arquivo, clique no botão de ramificação do Git trigger_tests.

  2. Na caixa de diálogo melhores notebooks, na tab Alterações, certifique-se de que covid_analysis/transforms.py esteja selecionado.

  3. Para commit message (obrigatório), digite Updated comment.

  4. Para Descrição (opcional), insira This updates the comment for filter_country.

  5. Clique em Confirmar e enviar.

  6. Clique no link da solicitação pull em Criar uma solicitação pull no seu provedor git no banner e, em seguida, crie a solicitação pull no GitHub.

  7. Na página de solicitação do pull, aguarde até que o ícone ao lado de Executar testes de pré-merge do Databricks / unit-test-notebook (pull_request) exiba uma marca de verificação verde. (Pode levar alguns instantes para que o ícone seja exibido). Se houver um X vermelho em vez de uma marca de verificaçã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 marcas'.

  8. Se a marca de verificação verde for exibida, faça o marge na solicitação pull na ramificação main.