Pular para o conteúdo principal

práticas recomendadas de engenharia de software para Notebook

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 a Databricks Git pastas 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 a Databricks. O passo a passo deste artigo usa o site GitHub. Este passo a passo pressupõe que o senhor tenha um repositório do GitHub chamado best-notebooks disponível. (Você pode dar um nome diferente ao seu repositório. Se você fizer isso, substitua best-notebooks pelo nome do seu repositório ao longo deste passo a passo.) Crie um repositório do GitHub se o senhor ainda não tiver um.
nota

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

Etapa 1: Configurar as pastas do Databricks Git​

Nesta etapa, o senhor conecta o seu repositório GitHub existente a Databricks Git pastas no 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.

Etapa 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 do Git , para o provedor do Git , selecione GitHub .
  4. Clique em Personal access tokens (Tokens de acesso pessoal ).
  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: Conecte-se ao seu repositório do GitHub​

  1. Na barra lateral do site workspace, clique em workspace .
  2. No navegador do espaço de trabalho , expanda o espaço de trabalho > Users.
  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 a URL do repositório do Git, insira o GitHub Clone com a URL HTTPS do seu repositório do GitHub. Este artigo pressupõe que seu URL termina 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 com o nome do seu repositório, por exemplo, best-notebooks.
    4. Clique em Create Git folder (Criar pasta Git ).

Etapa 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ê

Etapa 2.1: Crie uma ramificação ativa no repositório​

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.)

nota

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 da Etapa 1.2 deve estar aberta. Caso contrário, na barra lateral do espaço de trabalho , expanda espaço de trabalho > Usuários , 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 da ramificação principal Git.

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

nota

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.

  1. Digite eda e clique em Criar .

  2. Feche essa caixa de diálogo.

Etapa 2.2: Importar o Notebook para o repositório​

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 o Pandas API no Spark DataFrame como uma tabelaDelta em seu workspace.
  • Exibe o conteúdo do índice Delta.

Embora o senhor possa criar seu próprio Notebook em seu repositório 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 o uso básico dos arquivos de espaço de trabalho.

  1. Na pasta best-Notebook 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. Digite o URL do conteúdo bruto do Notebook covid_eda_raw no repositório databricks/notebook-best-practices em GitHub. Para obter esse URL: i. Acesse https://github.com/databricks/notebook-best-practices. ii. Clique na pasta notebooks. iii. Clique no arquivo covid_eda_raw.py. iv. Clique em Raw . v. Copie o URL completo da barra de endereço do seu navegador 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.

  1. Clique em Importar .

Etapa 2.3: execução do Notebook​

  1. Se o Notebook ainda não estiver sendo exibido, abra a pasta Notebook e, em seguida, clique no Notebook covid_eda_raw dentro da pasta.
  2. Selecione o clustering ao qual anexar esse Notebook. Para obter instruções sobre como criar um clustering, consulte Criar um clustering.
  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.

Etapa 2.4: Faça o check-in e acesse merge the 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 Notebook, clique no botão de ramificação eda Git.
  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 a mensagem de confirmação (obrigatória) , 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 pull request em Criar uma pull request no seu provedor git no banner.
  7. No GitHub, crie a solicitação pull e, em seguida, faça o merge da solicitação pull 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.

Etapa 3: mover 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.

Etapa 3.1: Crie outra ramificação ativa no repositório​

  1. Ao lado do nome do Notebook, clique no botão de ramificação eda Git.
  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 Criar filial .
  5. Digite first_modules e clique em Criar . (Você pode dar um nome diferente à sua filial.)
  6. Feche essa caixa de diálogo.

Etapa 3.2: Importar o Notebook para o repositório​

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 do espaço de trabalho , 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. Digite o URL do conteúdo bruto do Notebook covid_eda_modular no repositório databricks/notebook-best-practices em GitHub. Para obter esse URL: i. Acesse https://github.com/databricks/notebook-best-practices. ii. Clique na pasta notebooks. iii. Clique no arquivo covid_eda_modular.py. iv. Clique em Raw . v. Copie o URL completo da barra de endereços do navegador da Web para a caixa de diálogo Import Notebook .

nota

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

  1. Clique em Importar .

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

  1. No navegador do espaço de trabalho , clique com o botão direito do mouse na pasta best-Notebook Git e, em seguida, 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_analysis , clique em 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 , insira o seguinte código:

    Python
    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 Databricks Notebook.

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. 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 do espaço de trabalho , clique com o botão direito do mouse na pasta best-Notebook Git e, em seguida, clique em Create > File (Criar > Arquivo ).
nota

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 .

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

  2. Na janela do editor requirements.txt , insira o seguinte código:

nota

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
nota

O arquivo anterior lista versões específicas do pacote. Para maior compatibilidade, o senhor pode cruzar essas versões com as que estão instaladas em seus clusters todo-propósito. Consulte a seção "Ambiente do sistema" para obter informações sobre a versão do seu clustering em Databricks Runtime em Databricks Runtime notas sobre 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

Etapa 3.5: execução do 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 do espaço de trabalho , clique no Notebook covid_eda_modular dentro da pasta Notebook .
  2. Selecione o clustering ao qual anexar esse 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.

Etapa 3.6: Verificar o Notebook e seu código relacionado​

  1. Ao lado do nome do Notebook, clique no botão de ramificação first_modules Git.

  2. Na caixa de diálogo dos melhores notebooks , na tab Changes (Alterações), verifique se os seguintes itens estão selecionados:

    • requirements.txt
    • covid_analysis/transforms.py
    • notebooks/covid_eda_modular.py

  3. Para a mensagem de confirmação (obrigatória) , digite Added refactored notebook.

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

  5. Clique em Confirmar e enviar .

  6. Clique no link da pull request em Criar uma pull request no seu provedor git no banner.

  7. No GitHub, crie a solicitação pull e, em seguida, faça o merge da solicitação pull 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.

Etapa 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 de testes para o Notebook, bem como testes para R e Scala Notebook, consulte Testes de unidade para o Notebook.

Etapa 4.1: criar outra ramificação ativa no repositório​

  1. Ao lado do nome do Notebook, clique no botão de ramificação first_modules Git.
  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 Criar filial .
  5. Digite first_tests e clique em Criar . (Você pode dar um nome diferente à sua filial.)
  6. Feche essa caixa de diálogo.

Etapa 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 do espaço de trabalho , 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 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 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 , insira o código de teste a seguir. Esses testes usam dispositivos padrão pytest, bem como uma simulação na memória Pandas DataFrame:

    Python
    # 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

Etapa 4.3: execução dos testes​

Para acelerar esse passo a passo, nesta subetapa o senhor usa um Notebook importado para executar os testes anteriores. Este Notebook downloads e instala o pacote Python dependente dos testes em seu workspace, executa os testes e relata os resultados dos testes. Embora o senhor possa executar o pytest a partir do terminal da Web do seu clustering, executar o a partir pytest de um Notebook pode ser mais conveniente.

nota

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 do espaço de trabalho , 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. Digite o URL do conteúdo bruto do Notebook run_unit_tests no repositório databricks/notebook-best-practices em GitHub. Para obter esse URL: i. Acesse https://github.com/databricks/notebook-best-practices. ii. Clique na pasta notebooks. iii. Clique no arquivo run_unit_tests.py. iv. Clique em Raw . v. Copie o URL completo da barra de endereços do navegador da Web para a caixa de diálogo Import Notebook .

nota

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

  1. Clique em Importar .

  2. Selecione o clustering ao qual anexar esse Notebook.

  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ê 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

Etapa 4.4: Verificar o Notebook e os testes relacionados​

  1. Ao lado do nome do Notebook, clique no botão de ramificação first_tests Git.

  2. Na caixa de diálogo dos melhores notebooks , na tab Changes (Alterações), verifique se os seguintes itens estão selecionados:

    • testes/transforms_test.py
    • notebooks/run_unit_tests.py
    • testes/testdata.csv

  3. Para a mensagem de confirmação (obrigatória) , digite Added tests.

  4. Para Descrição (opcional) , insira These are the unit tests for the shared code..

  5. Clique em Confirmar e enviar .

  6. Clique no link da pull request em Criar uma pull request no seu provedor git no banner.

  7. No GitHub, crie a solicitação pull e, em seguida, faça o merge da solicitação pull 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.

Etapa 5: Criar um trabalho para executar o Notebook​

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.

Etapa 5.1: Criar uma tarefa de trabalho para executar o Notebook 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 trabalho a ser 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 a URL do repositório do Git, insira o GitHub Clone com a URL HTTPS do seu repositório do GitHub. Este artigo pressupõe que seu URL termina 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 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 .

nota

Nesse cenário, Databricks o site não recomenda que o senhor use o botão programar no Notebook, conforme descrito em Criar e gerenciar um Job agendado no Notebook para programar um Job para executar esse Notebook periodicamente. Isso ocorre porque o botão programar cria um trabalho usando a última cópia de trabalho do Notebook no repositório workspace. Em vez disso, o site Databricks recomenda que o senhor siga as instruções anteriores para criar um trabalho que use a versão mais recente do Notebook no repositório .

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

  1. Clique no ícone + Adicionar 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. O valor Verify Depends on é run_notebook-tests.
  8. Clique em Criar tarefa .

Etapa 5.3 Execução do trabalho​

  1. Clique em Run now (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 ciência de dados & engenharia ou Databricks Mosaic AI ambiente, clique em fluxo 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 .

  1. 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.
nota

Este trabalho é executado sob demanda. Para configurar esse trabalho para ser executado regularmente, consulte Automatização de trabalhos com programar e acionadores.

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

Na etapa anterior, o senhor usou um 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 repositório GitHub, usando uma ferramenta CI/CD, como o GitHub Actions.

Etapa 6.1: Configure o acesso GitHub para o senhor. workspace​

Nesta subetapa, o senhor configura um GitHub Actions fluxo de trabalho que executa o Job no workspace sempre que as alterações são mescladas no seu repositório. O senhor faz isso fornecendo a GitHub um Databricks tokens 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.

important

Os notebooks são executados com todas as permissões workspace da identidade associada aos tokens, portanto, o site Databricks recomenda o uso de uma entidade de serviço. Se realmente quiser fornecer os tokens de acesso pessoal do usuário Databricks workspace para GitHub apenas para fins de exploração pessoal e entender que, por motivos de segurança, o Databricks não incentiva essa prática, consulte as instruções para criar os tokens de acesso pessoal do usuário workspace.

Etapa 6.2: Adicionar o fluxo de trabalho 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 repositório do GitHub. O GitHub Actions exige que exista uma hierarquia específica de pastas aninhadas em seu repositório para funcionar corretamente. Para concluir esta etapa, o senhor deve usar o site do seu repositório do GitHub, 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 principal para expandir a lista suspensa de ramificações ou tags do Switch .

  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, insira o código a seguir. Esse código usa o gancho pull_request da execução Databricks Notebook GitHub Actionspara 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 a ID de clustering de destino.
    YAML
    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 de confirmação de alterações , digite Create databricks_pull_request_tests.yml na mensagem de confirmação

  10. Selecione fazer o 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) Etapa 7: Atualize o código compartilhado no GitHub para acionar os testes​

Nesta etapa, o senhor faz uma alteração no código compartilhado e, em seguida, envia a alteração para o seu repositório GitHub, que imediatamente aciona os testes automaticamente, com base no GitHub Actions da etapa anterior.

Etapa 7.1: criar outra ramificação ativa no repositório​

  1. No navegador do espaço de trabalho , 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 Criar . (Você pode dar um nome diferente à sua filial.)
  7. Feche essa caixa de diálogo.

Etapa 7.2: alterar o código compartilhado​

  1. No navegador do espaço de trabalho , na pasta best-Notebook Git, clique no arquivo covid_analysis/transforms.py .

  2. Altere a terceira linha desse arquivo:

    Python
    # Filter by country code.

    Para:

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

Etapa 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 a mensagem de confirmação (obrigatória) , 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.
Última atualização em