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, substituabest-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.
A Databricks clusters todo-propósito workspaceno. Para executar o Notebook durante a fase de projeto, clustero senhor anexa o Notebook a um site em execução s todo-propósito. Mais adiante, este passo a passo usa um Databricks trabalho do para automatizar a execução do Notebook cluster neste. (O senhor também pode executar o Job no site clusters que existe apenas para o tempo de vida do Job). Crie um clusters todo-propósito se o senhor 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
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.
Na barra lateral Settings (Configurações ), em User (Usuário), clique em Linked account (Conta vinculada).
Em integração Git, para provedor Git, selecione GitHub.
Clique em access tokenpessoal.
Para nome de usuário ou e-mail do provedor Git, insira seu nome de usuário do GitHub.
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.
Clique em Salvar.
Etapa 1.2: conectar-se ao repositório do GitHub
Na barra lateral do site workspace, clique em workspace.
No navegador workspace navegador, expanda workspace > Usuários.
Clique com o botão direito do mouse na pasta de nome de usuário e clique em Create > Git folder.
Na caixa de diálogo Criar pasta Git:
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 exemplohttps://github.com/<your-GitHub-username>/best-notebooks.git
.Para provedor Git, selecione GitHub.
Deixe o nome da pasta Git definido como o nome do seu site repo, por exemplo,
best-notebooks
.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.
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.
Ao lado do nome da pasta na barra de navegação workspace, clique no botão do ramo principal do Git.
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.Digite
eda
e clique em Create.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.
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.
Na pasta best-Noteb ook Git, clique em Create > Folder (Criar pasta).
Na caixa de diálogo Nova pasta, digite
notebooks
e clique em Criar.Na pasta Notebook, clique no botão e, em seguida, em Import (Importar).
Na caixa de diálogo Importar:
Para Importar de, selecione o URL.
Insira a URL do conteúdo bruto do
covid_eda_raw
notebook nodatabricks/notebook-best-practices
repo no GitHub. Para obter esse URL:Acesse https://github.com/databricks/notebook-best-practices.
Clique na pasta
notebooks
.Clique no arquivo
covid_eda_raw.py
.Clique em Bruto.
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.
Clique em Importar.
Passo 2.3: execute o notebook
Se o site Notebook ainda não estiver sendo exibido, abra a pasta Notebook e clique em covid_eda_raw Notebook dentro da pasta.
Selecione o endereço cluster para anexar esse Notebook. Para obter instruções sobre como criar um cluster, consulte Criar um cluster.
Clique em Executar tudo.
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.
Ao lado do nome do site Notebook, clique no botão eda Git branch.
Na caixa de diálogo melhores notebooks, na tab Alterações, verifique se o arquivo notebooks/covid_eda_raw.py está selecionado.
Para commit message (obrigatório), digite
Added raw notebook
.Para Descrição (opcional), insira
This is the first version of the notebook.
Clique em Confirmar e enviar.
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.
No GitHub, crie a pull request e, em seguida, faça o merge da pull request no branch
main
.De volta à área de trabalho do Databricks, feche a caixa de diálogo melhores notebooks se ela ainda estiver sendo exibida.
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 .
Na barra lateral workspace, clique em fluxo de trabalho.
Na tab Trabalhos, clique em Criar Job.
Edite o nome do site Job para que seja
covid_report
.Em Nome da tarefa, insira
run_notebook_tests
.Para o Tipo, selecione Notebook.
Em Source (Fonte), selecione o provedor Git.
Clique em Adicionar uma referência Git.
Na caixa de diálogo Informações do Git:
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 exemplohttps://github.com/<your-GitHub-username>/best-notebooks.git
.Para provedor Git, selecione GitHub.
Para referência do Git (ramificação/tag/commit), insira
main
.Próximo a Referência do Git (ramificação/tag/commit), selecione ramificação.
Clique em Confirm (Confirmar).
Para o Caminho, insira
notebooks/run_unit_tests
. Não adicione a extensão de arquivo.py
.Para Cluster, selecione o cluster na etapa anterior.
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
Clique no ícone + Adicionar tarefa.
Será exibido um menu pop-up. Selecione Notebook.
Em Nome da tarefa, insira
run_main_notebook
.Para o Tipo, selecione Notebook.
Para o Caminho, insira
notebooks/covid_eda_modular
. Não adicione a extensão de arquivo.py
.Para Cluster, selecione o cluster na etapa anterior.
Verificar se o valor Depende de é
run_notebook-tests
.Clique em Criar tarefa.
Passo 5.3: Executar o trabalho
Clique em Run now (Executar agora).
No pop-up, clique em Exibir execução.
Observação
Se o pop-up desaparecer muito rapidamente, faça o seguinte:
Na barra lateral do ambiente ciência de dados & engenharia ou Databricks Mosaic AI ambiente, clique em fluxo de trabalho.
Na tab Execuções do trabalho, clique no valor Iniciar horário do job mais recente com covid_report na coluna Jobs.
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 trabalho é executado sob demanda. Para configurar esse Job para ser executado regularmente, consulte Trigger types for Databricks Jobs.
(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 desencoraja você de fornecer workspace pessoal do usuário do seu do Databricks access token ao GitHub. Para obter instruções, consulte a seção GCP da página de execução do 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.
No site do seu repos GitHub, clique na tab Código .
Clique na seta ao lado de main para expandir a lista suspensa Switch branches or tags.
Na caixa Localizar ou criar uma ramificação, insira
adding_github_actions
.Clique em "Criar ramificação: adding_github_actions" em "principal".
Clique em "Adicionar arquivo > Criar novo arquivo".
Em Nomeie seu arquivo, insira
.github/workflows/databricks_pull_request_tests.yml
.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"
Clique em Confirmar alterações.
Na caixa de diálogo commit changes, digite
Create databricks_pull_request_tests.yml
na mensagemcommitSelecione commit diretamente no branch adding_github_actions e clique em commit changes.
Na tab Código, clique em "Comparar e solicitação de pull" e, em seguida, crie a solicitação do pull.
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'.
Se a marca de verificação verde for exibida, faça o marge na solicitação pull na ramificação
main
.