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).
Nestas instruções, irá:
- Adicione blocos de anotações às pastas Git do Azure Databricks para controle de versão.
- Extrair partes de código de um dos blocos de notas 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, substituabest-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 blocos de anotações durante a fase de design, anexe os blocos de anotações a um cluster multiuso em execução. Mais tarde, este passo a passo usa um trabalho do Azure Databricks para automatizar a execução dos blocos de anotações 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
- Clique no seu nome de utilizador no canto superior direito da área de trabalho e, em seguida, clique em Definições na lista pendente.
- Na barra lateral Configurações, em Usuário, clique em Contas vinculadas.
- Em Integração com Git, para provedor Git, selecione GitHub.
- Clique em Token de acesso pessoal.
- Para o nome de usuário ou e-mail do provedor Git, digite seu nome de usuário do GitHub.
- Em Token, insira seu token de acesso pessoal do GitHub (clássico). Esse token de acesso pessoal (clássico) deve ter as permissões de repositório e fluxo de trabalho .
- Clique em Guardar.
Etapa 1.2: Conecte-se ao repositório GitHub
- Na barra lateral do espaço de trabalho, clique em Espaço de trabalho.
- No navegador Espaço de trabalho, expanda Usuários do espaço de trabalho>.
- Clique com o botão direito do rato na pasta de nome de utilizador e, em seguida, clique em Criar > pasta Git.
- Na caixa de diálogo Criar pasta Git:
- Para URL do repositório Git, insira o Clone do GitHub com URL HTTPS para seu repositório GitHub. Este artigo pressupõe que o URL termina com
best-notebooks.git
, por exemplohttps://github.com/<your-GitHub-username>/best-notebooks.git
, . - Para o provedor Git, selecione GitHub.
- Deixe o nome da pasta Git definido como o nome do seu repositório, por exemplo
best-notebooks
. - Clique em Criar pasta Git.
- Para URL do repositório Git, insira o Clone do GitHub com URL HTTPS para seu repositório GitHub. Este artigo pressupõe que o URL termina com
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.
A pasta Git da Etapa 1.2 deve estar aberta. Caso contrário, na barra lateral do espaço de trabalho, expanda Usuários do espaço de trabalho>, expanda a pasta de nome de usuário e clique na pasta Git.
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.
Na caixa de diálogo melhores blocos de anotações, clique no botão Criar ramificação.
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.Digite
eda
e clique em Criar.Feche esta caixa de diálogo.
Etapa 2.2: Importar o bloco de anotações para o repositório
Nesta subetapa, você importa um bloco de anotações existente de outro repositório para o 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 arquivo CSV em um DataFrame pandas.
- 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 Spark DataFrame.
- 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.
- Na pasta Git dos melhores blocos de anotações, clique em Criar > pasta.
- Na caixa de diálogo Nova pasta, digite
notebooks
e clique em Criar. - Na pasta de blocos de anotações , clique no kebab e, em seguida , em Importar.
- Na caixa de diálogo Importar:
Em Importar de, selecione URL.
Insira o URL para o conteúdo bruto do bloco de
covid_eda_raw
anotações nodatabricks/notebook-best-practices
repositório no GitHub. Para obter este URL: i. Aceda a https://github.com/databricks/notebook-best-practices. ii. Clique nanotebooks
pasta. iii. Clique nocovid_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 com URLs do Git apenas para repositórios públicos.
Clique em Importar.
Passo 2.3: Executar o bloco de notas
- Se o bloco de notas ainda não estiver a ser apresentado, abra a pasta de blocos de notas e, em seguida, clique no covid_eda_raw bloco de notas dentro da pasta.
- Selecione o cluster ao qual anexar este bloco de anotações. Para obter instruções sobre como criar um cluster, consulte Criar um cluster.
- Clique em Executar tudo.
- Aguarde enquanto o bloco de notas é executado.
Depois que o bloco de anotações terminar de ser executado, você verá um gráfico dos dados, 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: Faça check-in e mescle o bloco de anotações
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.
- Ao lado do nome do bloco de anotações, clique no botão de ramificação eda Git.
- Na caixa de diálogo melhores blocos de notas, no separador Alterações, certifique-se de que o ficheiro de blocos de notas/covid_eda_raw.py está selecionado.
- Em Mensagem de confirmação (obrigatório), digite
Added raw notebook
. - Para Descrição (opcional), insira
This is the first version of the notebook.
- Clique em Confirmar & Push.
- Clique no link pull request em Criar uma pull request no seu provedor git no banner.
- No GitHub, crie a solicitação pull e mescle a pull request na
main
ramificação. - De volta ao seu espaço de trabalho do Azure Databricks, feche a caixa de diálogo dos melhores blocos de anotações se ela ainda estiver sendo exibida.
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. Isso permite que você use essas funções com outros blocos de anotações semelhantes, o que pode acelerar a codificação futura e ajudar a garantir resultados de notebook 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
- Ao lado do nome do bloco de anotações, clique no botão de ramificação eda Git.
- Na caixa de diálogo melhores blocos de anotações, clique na seta suspensa ao lado da ramificação eda e selecione principal.
- Clique no botão Puxar . Se lhe for pedido para continuar a puxar, clique em Confirmar.
- Clique no botão Criar ramificação .
- Introduza
first_modules
e, em seguida, clique em Criar. (Você pode dar um nome diferente ao seu ramo.) - 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. Novamente, você pode criar seu próprio bloco de anotações em seu repositório aqui e fazer o compartilhamento de código real.
- No navegador Espaço de trabalho, clique com o botão direito do mouse na pasta blocos de anotações e clique em Importar.
- Na caixa de diálogo Importar:
Em Importar de, selecione URL.
Insira o URL para o conteúdo bruto do bloco de
covid_eda_modular
anotações nodatabricks/notebook-best-practices
repositório no GitHub. Para obter este URL: i. Aceda a https://github.com/databricks/notebook-best-practices. ii. Clique nanotebooks
pasta. iii. Clique nocovid_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 anotações funciona com URLs do Git apenas para repositórios públicos.
Clique em Importar.
Etapa 3.3: Adicionar as funções de código compartilhado de suporte do bloco de anotações
No navegador Espaço de trabalho, clique com o botão direito do mouse na pasta Git dos melhores blocos de anotações e clique em Criar > pasta.
Na caixa de diálogo Nova pasta, digite
covid_analysis
e clique em Criar.Na pasta covid_analysis, clique em Criar > arquivo.
Na caixa de diálogo Novo Nome do Ficheiro, introduza
transforms.py
e, em seguida, clique em Criar Ficheiro.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.
No navegador Espaço de trabalho, clique com o botão direito do mouse na pasta Git dos melhores blocos de anotações e clique em Criar > arquivo.
Nota
Você deseja que o arquivo que lista as dependências do pacote vá para a raiz da pasta Git, não para os blocos de anotações ou pastas covid_analysis .
Na caixa de diálogo Novo Nome do Ficheiro, introduza
requirements.txt
e, em seguida, clique em Criar Ficheiro.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 obter a versão do Databricks Runtime do cluster em Notas de versão, versões e compatibilidade do Databricks Runtime.
Sua estrutura de recompra 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, você executa o covid_eda_modular
bloco de anotações, que chama o código compartilhado em covid_analysis/transforms.py
.
- No navegador Espaço de trabalho, clique no bloco de anotações covid_eda_modular dentro da pasta blocos de anotações.
- Selecione o cluster ao qual anexar este bloco de anotações.
- Clique em Executar tudo.
- 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 com este notebook é que um filtro diferente é usado (um iso_code
de DZA
em vez de USA
). Se o cluster ainda não estava em execução quando você começou a executar este 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
- Ao lado do nome do bloco de anotações, clique no botão first_modules ramificação do Git.
- Na caixa de diálogo Melhores blocos de anotações, na guia Alterações, verifique se as seguintes opções estão selecionadas:
- requirements.txt
- covid_analysis/transforms.py
- Cadernos/covid_eda_modular.py
- Em Mensagem de confirmação (obrigatório), digite
Added refactored notebook
. - Para Descrição (opcional), insira
This is the second version of the notebook.
- Clique em Confirmar & Push.
- Clique no link pull request em Criar uma pull request no seu provedor git no banner.
- No GitHub, crie a solicitação pull e mescle a pull request na
main
ramificação. - De volta ao seu espaço de trabalho do Azure Databricks, feche a caixa de diálogo dos melhores blocos de anotações se ela ainda estiver sendo exibida.
Etapa 4: Testar o código compartilhado
Nesta etapa, você testa o código compartilhado da última etapa. No entanto, você deseja testar esse código sem executar o covid_eda_modular
bloco de anotações 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
- Ao lado do nome do bloco de anotações, clique no botão first_modules ramificação do Git.
- Na caixa de diálogo Melhores blocos de anotações, clique na seta suspensa ao lado da ramificação first_modules e selecione principal.
- Clique no botão Puxar . Se lhe for pedido para continuar a puxar, clique em Confirmar.
- Clique em Criar ramificação.
- Introduza
first_tests
e, em seguida, clique em Criar. (Você pode dar um nome diferente ao seu ramo.) - 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.
No navegador Espaço de trabalho, clique com o botão direito do mouse na pasta Git e clique em Criar > pasta.
Na caixa de diálogo Nova pasta, digite
tests
e clique em Criar.Na pasta de testes, clique em Criar > arquivo.
Na caixa de diálogo Novo Nome do Ficheiro, introduza
testdata.csv
e, em seguida, clique em Criar Ficheiro.Na janela testdata.csv editor, 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
Na pasta de testes, clique em Criar > arquivo.
Na caixa de diálogo Novo Nome do Ficheiro, introduza
transforms_test.py
e, em seguida, clique em Criar Ficheiro.Na janela transforms_test.py editor, 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()
Sua estrutura de recompra 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 em seu espaço de trabalho, executa os testes e relata os resultados dos testes. Embora você possa executar pytest
a partir do terminal da Web do cluster, executar pytest
a partir de um bloco de anotações 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.
- No navegador Espaço de trabalho, clique com o botão direito do mouse na pasta blocos de anotações e clique em Importar.
- Na caixa de diálogo Importar Blocos de Notas:
Em Importar de, selecione URL.
Insira o URL para o conteúdo bruto do bloco de
run_unit_tests
anotações nodatabricks/notebook-best-practices
repositório no GitHub. Para obter este URL: i. Aceda a https://github.com/databricks/notebook-best-practices. ii. Clique nanotebooks
pasta. iii. Clique norun_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 anotações funciona com URLs do Git apenas para repositórios públicos.
Clique em Importar.
- Selecione o cluster ao qual anexar este bloco de anotações.
- Clique em Executar tudo.
- 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.
Sua estrutura de recompra 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
- Ao lado do nome do bloco de anotações, clique no botão first_tests ramificação do Git.
- Na caixa de diálogo Melhores blocos de anotações, na guia Alterações, verifique se as seguintes opções estão selecionadas:
- testes/transforms_test.py
- Cadernos/run_unit_tests.py
- testes/testdata.csv
- Em Mensagem de confirmação (obrigatório), digite
Added tests
. - Para Descrição (opcional), digite
These are the unit tests for the shared code.
. - Clique em Confirmar & Push.
- Clique no link pull request em Criar uma pull request no seu provedor git no banner.
- No GitHub, crie a solicitação pull e mescle a pull request na
main
ramificação. - De volta ao seu espaço de trabalho do Azure Databricks, feche a caixa de diálogo dos melhores blocos de anotações se ela ainda estiver sendo exibida.
Etapa 5: Criar um trabalho para executar os blocos de anotações
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 bloco de anotações de teste
- Na barra lateral do espaço de trabalho, clique em Fluxos de trabalho.
- Na guia Trabalhos, clique em Criar Trabalho.
- Edite o nome do trabalho a ser
covid_report
. - Em Nome da tarefa, digite
run_notebook_tests
. - Em Tipo, selecione Bloco de Anotações.
- Em Source, selecione Git provider.
- Clique em Adicionar uma referência git.
- Na caixa de diálogo de informações do Git:
- Para URL do repositório Git, insira o Clone do GitHub com URL HTTPS para seu repositório GitHub. Este artigo pressupõe que o URL termina com
best-notebooks.git
, por exemplohttps://github.com/<your-GitHub-username>/best-notebooks.git
, . - Para o provedor Git, selecione GitHub.
- Para referência do Git (branch / tag / commit), digite
main
. - Ao lado de Referência do Git (branch / tag / commit), selecione branch.
- Clique em Confirmar.
- Para URL do repositório Git, insira o Clone do GitHub com URL HTTPS para seu repositório GitHub. Este artigo pressupõe que o URL termina com
- Em Caminho, digite
notebooks/run_unit_tests
. Não adicione a extensão de.py
arquivo. - Em Cluster, selecione o cluster na etapa anterior.
- 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 um trabalho usando a cópia de trabalho mais recente do bloco de anotações no repositório do espaço 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
- Clique no ícone + Adicionar tarefa .
- É apresentado um menu pop-up. Selecione Notebook (Bloco de notas).
- Em Nome da tarefa, digite
run_main_notebook
. - Em Tipo, selecione Bloco de Anotações.
- Em Caminho, digite
notebooks/covid_eda_modular
. Não adicione a extensão de.py
arquivo. - Em Cluster, selecione o cluster na etapa anterior.
- Verificar Depende do valor é
run_notebook-tests
. - Clique em Criar tarefa.
Etapa 5.3 Executar o trabalho
Clique em Executar agora.
No pop-up, clique em Exibir execução.
Nota
Se o pop-up desaparecer muito rapidamente, faça o seguinte:
- Na barra lateral do ambiente Data Science & Engineering ou Databricks Mosaic AI , clique em Fluxos de trabalho.
- Na guia Execuções de trabalho, clique no valor Hora de início do trabalho mais recente com covid_report na coluna Trabalhos.
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 esse trabalho para ser executado regularmente, consulte Tipos de gatilho para trabalhos do Databricks.
(Opcional) Etapa 6: Configurar o repositório para testar o código e executar o bloco de anotações automaticamente sempre que o código for alterado
Na etapa anterior, você usou um trabalho para testar automaticamente seu código compartilhado e executar seus blocos de anotações em um ponto no tempo 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 que você forneça ao GitHub um token de ID do Microsoft Entra associado a uma entidade 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 blocos de anotações são executados com todas as permissões de espaço de trabalho da identidade associada ao token, portanto, o Databricks recomenda o uso de uma entidade 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 subetapa, você adiciona um fluxo de trabalho de Ações do GitHub para executar o run_unit_tests
bloco de anotações sempre que houver uma solicitação pull 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.
No site do repositório GitHub, clique na guia Código .
Clique na seta ao lado de principal para expandir a lista suspensa Alternar ramificações ou tags .
Na caixa Localizar ou criar uma ramificação , digite
adding_github_actions
.Clique em Criar ramificação: adding_github_actions de 'principal'.
Clique em Adicionar arquivo > Criar novo arquivo.
Em Nomeie seu arquivo, digite
.github/workflows/databricks_pull_request_tests.yml
.Na janela do editor, digite o código a seguir. Esse código usa o gancho de pull_request da ação Run Databricks Notebook GitHub para executar o
run_unit_tests
bloco de anotações.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"
Clique em Confirmar alterações.
Na caixa de diálogo Confirmar alterações, insira
Create databricks_pull_request_tests.yml
a mensagem de confirmaçãoSelecione Confirmar diretamente na ramificação adding_github_actions e clique em Confirmar alterações.
Na guia Código, clique em Comparar & pull request e crie a pull request.
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.
Se a marca de seleção verde aparecer, mescle a solicitação pull 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
- No navegador Espaço de trabalho, abra a pasta Git dos melhores blocos de anotações.
- Ao lado do nome da pasta, clique no botão first_tests ramificação do Git.
- Na caixa de diálogo melhores blocos de anotações, clique na seta suspensa ao lado da ramificação first_tests e selecione principal.
- Clique no botão Puxar . Se lhe for pedido para continuar a puxar, clique em Confirmar.
- Clique no + botão (Criar ramificação).
- Introduza
trigger_tests
e, em seguida, clique em Criar. (Você pode dar um nome diferente ao seu ramo.) - Feche esta caixa de diálogo.
Etapa 7.2: Alterar o código compartilhado
No navegador Espaço de trabalho, na pasta Git dos melhores blocos de anotações, clique no arquivo covid_analysis/transforms.py.
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
- Ao lado do nome do arquivo, clique no botão trigger_tests ramificação do Git.
- Na caixa de diálogo Melhores blocos de anotações, na guia Alterações, verifique se covid_analysis/transforms.py está selecionado.
- Em Mensagem de confirmação (obrigatório), digite
Updated comment
. - Para Descrição (opcional), insira
This updates the comment for filter_country.
- Clique em Confirmar & Push.
- Clique no link pull request em Create a pull request on your git provider no banner e, em seguida, crie o pull request no GitHub.
- 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.
- Se a marca de seleção verde aparecer, mescle a solicitação pull na
main
ramificação.