Usar dbx com o Visual Studio Code

Artigo
10/09/2024

Importante

Esta documentação foi desativada e pode não estar atualizada.

O Databricks recomenda que você use os Pacotes de Ativos do Databricks em vez do dbx by Databricks Labs. Consulte O que são os Pacotes de Ativos do Databricks? e Migrar do dbx para os pacotes.

Para usar o Azure Databricks com o Visual Studio Code, consulte o artigo Extensão do Databricks para o Visual Studio Code.

Este artigo descreve um exemplo de código baseado em Python com o qual você pode trabalhar em qualquer IDE compatível com Python. Especificamente, este artigo descreve como trabalhar com esse exemplo de código no Visual Studio Code, que fornece os seguintes recursos de produtividade do desenvolvedor:

Preenchimento de código
Lint
Testes
Depuração de objetos de código que não exigem uma conexão em tempo real com recursos remotos do Azure Databricks.

Este artigo usa o dbx por Databricks Labs junto com o Visual Studio Code para enviar o exemplo de código para um workspace remoto do Azure Databricks. O dbx instrui o Azure Databricks a Agendar e orquestrar fluxos de trabalho para executar o código enviado em um cluster de trabalhos do Azure Databricks nesse workspace.

Você pode usar provedores de Git de terceiros populares para controle de versão CI/CD (integração contínua e entrega contínua) ou implantação contínua do seu código. Para controle de versão, esses provedores de Git incluem o seguinte:

GitHub
Bitbucket
GitLab
Azure DevOps (não está disponível nas regiões do Azure na China)
CodeCommit da AWS
GitHub AE

Para CI/CD, dbx dá suporte às seguintes plataformas de CI/CD:

Para demonstrar como o controle de versão e a CI/CD podem funcionar, este artigo descreve como usar o Visual Studio Code, dbx e este exemplo de código, juntamente com o GitHub e o GitHub Actions.

Requisitos de exemplo de código

Para usar este exemplo de código, você deve ter o seguinte:

Um workspace do Azure Databricks em sua conta do Azure Databricks.
Uma conta do GitHub. Crie uma conta do GitHub, se você ainda não tiver uma.

Além disso, em seu computador de desenvolvimento local, você deve ter o seguinte:

Python versão 3.8 ou superior.

Você deve usar uma versão do Python que corresponda à que está instalada em seus clusters de destino. Para obter a versão do Python instalada em um cluster existente, você pode usar o terminal Web do cluster para executar o comando python --version. Consulte também a seção "Ambiente do sistema" nas notas sobre a versão do Databricks Runtime da versão do Databricks Runtime nos seus clusters de destino. De qualquer forma, a versão do Python deve ser 3.8 ou superior.

Para obter a versão do Python que atualmente é referenciada em seu computador local, execute python --version em seu terminal local. (Dependendo de como configurou o Python em seu computador local, talvez seja necessário executar python3 em vez de python ao longo deste artigo.) Veja também Selecionar um interpretador do Python.
pip. pip é instalado automaticamente com versões mais recentes do Python. Para verificar se pip já está instalado, execute pip --version a partir do terminal local. (Dependendo de como configurou o Python ou pip em seu computador local, talvez seja necessário executar pip3 em vez de pip ao longo deste artigo.)
dbx versão 0.8.0 ou superior. Você pode instalar o pacote dbx do PyPI (Índice de Pacotes do Python) executando pip install dbx.

Observação

Não é necessário instalar o dbx agora. Você pode instalá-lo posteriormente na seção de configuração de exemplo de código.
Um método para criar ambientes virtuais do Python para garantir que você esteja usando as versões corretas do Python e das dependências do pacote em seus projetos de dbx. Este artigo aborda pipenv.
A CLI do Databricks versão 0.18 ou inferior, configurada com a autenticação.

Observação

Você não precisa instalar a CLI herdada do Databricks (CLI do Databricks versão 0.17) agora. Você pode instalá-lo posteriormente na seção de configuração de exemplo de código. Se você quiser instalá-lo mais tarde, lembre-se de configurar a autenticação nesse momento.
Visual Studio Code.
A extensão do Python para Visual Studio Code.
A extensão Problemas e solicitações de pull do GitHub para o Visual Studio Code.
Git.

Sobre o código de exemplo

O exemplo de código do Python para este artigo, disponível no repositório databricks/ide-melhores práticas no GitHub, faz o seguinte:

Obtém dados do repositório owid/covid-19-data no GitHub.
Filtra os dados de um código ISO de país específico.
Cria uma tabela dinâmica com base nos dados.
Executa a limpeza de dados nos dados.
Modulariza a lógica de código em funções reutilizáveis.
A unidade testa as funções.
Fornece dbx configurações e definições de projeto para habilitar o código para gravar os dados em uma tabela Delta em um workspace remoto do Azure Databricks.

Configurar o código de exemplo

Depois de ter os requisitos em vigor para este exemplo de código, conclua as etapas a seguir para começar a usar o exemplo de código.

Observação

Essas etapas não incluem a configuração deste exemplo de código para a CI/CD. Você não precisa configurar a CI/CD para executar este exemplo de código. Se você quiser configurar a CI/CD mais tarde, consulte Executar com o GitHub Actions.

Etapa 1: criar um ambiente virtual do Python

No terminal, crie uma pasta em branco para conter um ambiente virtual para este exemplo de código. Essas instruções usam uma pasta pai chamada ide-demo. Você pode dar a essa pasta qualquer nome que desejar. Se você usar um nome diferente, substitua o nome ao longo este artigo. Depois de criar a pasta, alterne para ela e inicie o Visual Studio Code dessa pasta. Verifique se você incluiu o ponto (.) após o comando code.

No Linux e macOS:
```
mkdir ide-demo
cd ide-demo
code .
```
Dica

Se você obter o erro command not found: code, consulte Inicialização da linha de comando no site da Microsoft.

Para Windows:
```
md ide-demo
cd ide-demo
code .
```
Em Visual Studio Code, na barra de menus, clique em Exibição > Terminal.
Na raiz da pasta ide-demo, execute o comando pipenv com a opção a seguir, onde <version> é a versão de destino do Python que você já instalou localmente (e, idealmente, uma versão que corresponde à versão do Python dos clusters de destino), por exemplo 3.8.14.
```
pipenv --python <version>
```
Anote o valor Virtualenv location na saída do comando pipenv, pois você precisará dele na próxima etapa.
Selecione o interpretador do Python de destino e ative o ambiente virtual do Python:
1. Na barra de menus, clique em Exibição > Paleta de Comandos, digite Python: Select e clique em Python: selecionar Interpretador.
2. Selecione o interpretador do Python dentro do caminho para o ambiente virtual do Python que você acabou de criar. (Esse caminho é listado como o valor Virtualenv location na saída do comando pipenv.)
3. Na barra de menus, clique em Exibição > Paleta de Comandos, digite Terminal: Create e clique em Terminal: criar terminal.
4. Verifique se o prompt de comando indica que você está no shell pipenv. Para confirmar, você deverá ver algo como (<your-username>) antes do prompt de comando. Se você não o vir, execute o seguinte comando:
```
pipenv shell
```
  Para sair do shell pipenv, execute o comando exit e os parênteses desaparecem.
Para obter mais informações, consulte Como usar ambientes do Python no VS Code na documentação do Visual Studio Code.

Etapa 2: clonar o exemplo de código de GitHub

Em Visual Studio Code, abra a pasta ide-demo (Pasta Abrir > Arquivo), se ela ainda não estiver aberta.
Clique em Exibição > Paleta de Comandos, digite Git: Clonee clique em Git: Clonar.
Em Fornecer o URL do repositório ou selecionar uma origem do repositório, insira https://github.com/databricks/ide-best-practices
Navegue até sua pasta ide-demo e clique em Selecionar Local do Repositório.

Etapa 3: instalar as dependências do exemplo de código

Instale uma versão do dbx e da CLI do Databricks versão 0.18 ou inferior que seja compatível com sua versão do Python. Para fazer isso, em Visual Studio Code do terminal, na pasta ide-demo com um shell pipenv ativado (pipenv shell), execute o seguinte comando:
```
pip install dbx
```
Confirme se dbx está instalado. Para fazer isso, execute o seguinte comando:
```
dbx --version
```
Se o número da versão for retornado, dbx será instalado.

Se o número da versão for inferior a 0.8.0, atualize o dbx executando o seguinte comando e verifique o número da versão novamente:
```
pip install dbx --upgrade
dbx --version

# Or ...
python -m pip install dbx --upgrade
dbx --version
```
Ao instalar a dbx, a CLI herdada do Databricks (versões 0.17 e inferiores da CLI do Databricks) também é instalada automaticamente. Para verificar a CLI herdada do Databricks (versão 0.17 da CLI do Databricks) está instalada, execute o seguinte comando:
```
databricks --version
```
Se a CLI do Databricks versão 0.17 for retornada, a CLI herdada do Databricks será instalada.
Se você não tiver configurado a CLI do Databricks (CLI do Databricks versão 0.17) com autenticação, deverá fazer isso agora. Para confirmar se a autenticação está configurada, execute o comando básico a seguir para obter algumas informações resumidas sobre seu workspace do Azure Databricks. Certifique-se de incluir a barra de avanço (/) após o subcomando ls:
```
databricks workspace ls /
```
Se uma lista de nomes de pastas de nível raiz para seu espaço de trabalho for retornada, a autenticação será configurada.
Instale os pacotes do Python dos quais esse exemplo de código depende. Para fazer isso, execute o seguinte comando ide-demo/ide-best-practices a partir da pasta:
```
pip install -r unit-requirements.txt
```
Confirme se os pacotes dependentes do exemplo de código estão instalados. Para fazer isso, execute o seguinte comando:
```
pip list
```
Se os pacotes que estão listados no arquivos requirements.txt e unit-requirements.txt estiverem em algum lugar nessa lista, os pacotes dependentes serão instalados.

Observação

Os arquivos listados requirements.txt são para versões específicas do pacote. Para obter uma melhor compatibilidade, você pode fazer referência cruzada a essas versões com o tipo de nó de cluster que deseja que seu workspace do Azure Databricks use para executar implantações posteriormente. Consulte também a seção "Ambiente do sistema" da versão do Databricks Runtime em das versões de notas sobre a versão e compatibilidade do Databricks Runtime.

Etapa 4: personalizar o exemplo de código para seu workspace do Azure Databricks

Personalize as configurações de projeto dbx do repositório. Para fazer isso, no arquivo .dbx/project.json, altere o valor do objeto profilede DEFAULT para o nome do perfil que corresponde ao que você configurou para autenticação com a CLI do Databricks (CLI do Databricks versão 0.17). Se você não configurou nenhum perfil não padrão, deixe DEFAULT como está. Por exemplo:
```
{
  "environments": {
    "default": {
      "profile": "DEFAULT",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/covid_analysis",
        "artifact_location": "dbfs:/Shared/dbx/projects/covid_analysis"
      }
    }
  },
  "inplace_jinja_support": false
}
```

Personalize as configurações dbx de implantação do projeto. Para fazer isso, no arquivo conf/deployment.yml, altere o valor dos objetos spark_version e node_type_id de 10.4.x-scala2.12 e m6gd.large para a cadeia de caracteres de versão de runtime do Azure Databricks e o tipo de nó de cluster que você deseja que seu workspace do Azure Databricks use para executar implantações.

Por exemplo, para especificar o Databricks Runtime 10.4 LTS e um tipo de nó Standard_DS3_v2:

environments:
  default:
    workflows:
      - name: "covid_analysis_etl_integ"
        new_cluster:
          spark_version: "10.4.x-scala2.12"
          num_workers: 1
        node_type_id: "Standard_DS3_v2"
        spark_python_task:
          python_file: "file://jobs/covid_trends_job.py"
      - name: "covid_analysis_etl_prod"
        new_cluster:
          spark_version: "10.4.x-scala2.12"
          num_workers: 1
          node_type_id: "Standard_DS3_v2"
          spark_python_task:
            python_file: "file://jobs/covid_trends_job.py"
          parameters: ["--prod"]
      - name: "covid_analysis_etl_raw"
        new_cluster:
          spark_version: "10.4.x-scala2.12"
          num_workers: 1
          node_type_id: "Standard_DS3_v2"
          spark_python_task:
            python_file: "file://jobs/covid_trends_job_raw.py"

Dica

Neste exemplo, cada uma dessas três definições de trabalho tem o mesmo valor spark_version e node_type_id. Você pode usar valores diferentes para diferentes definições de trabalho. Você também pode criar valores compartilhados e reutilizá-los entre definições de trabalho, para reduzir erros de digitação e manutenção de código. Consulte o exemplo YAML na documentação dbx.

Explore o exemplo de código

Depois de configurar o exemplo de código, use as informações a seguir para saber mais sobre como os vários arquivos na pasta ide-demo/ide-best-practices funcionam.

Modularidade do código

Código não modificada

O arquivo jobs/covid_trends_job_raw.py é uma versão não modificada da lógica de código. Você pode executar esse arquivo sozinho.

Código modularizado

O arquivo jobs/covid_trends_job.py é uma versão modularizada da lógica de código. Esse arquivo depende do código compartilhado no arquivo covid_analysis/transforms.py. O arquivo covid_analysis/__init__.py trata a pasta covide_analysis como um pacote que contém.

Testando

Testes de unidade

O arquivo tests/testdata.csv contém uma pequena parte dos dados no arquivo covid-hospitalizations.csv para fins de teste. O arquivo tests/transforms_test.py contém os testes de unidade para o arquivo covid_analysis/transforms.py.

Executor de teste de unidade

O arquivo pytest.ini contém opções de configuração para executar testes com pytest. Consulte pytest.ini e Opções de Configuração na documentação pytest.

O arquivo .coveragerc contém opções de configuração para medidas de cobertura de código Python com coverage.py. Consulte a Referência de configuração na documentação coverage.py.

O arquivo requirements.txt, que é um subconjunto do arquivo unit-requirements.txt que você executou anteriormente com pip, contém uma lista de pacotes dos quais os testes de unidade também dependem.

Empacotamento

O arquivo setup.py fornece comandos a serem executados no console (scripts de console), como o comando pip, para empacotar projetos Python com setuptools. Consulte Pontos de Entrada na documentação setuptools.

Outros arquivos

Há outros arquivos neste exemplo de código que não foram descritos anteriormente:

A pasta .github/workflowscontém três arquivos, databricks_pull_request_tests.yml, onpush.yml e onrelease.yaml, que representam o GitHub Actions, que são abordados posteriormente na seção GitHub Actions.
O arquivo .gitignore contém uma lista de pastas locais e arquivos que o Git ignora para seu repositório.

Executar o exemplo de código

Você pode usar dbx em seu computador local para instruir o Azure Databricks a executar o exemplo de código em seu workspace remoto sob demanda, conforme descrito na próxima subseção. Ou você pode usar o GitHub Actions para que o GitHub execute o exemplo de código toda vez que você enviar alterações de código por push para o repositório do GitHub.

Executar com dbx

Instale o conteúdo da pasta covid_analysis como um pacote no setuptools modo de desenvolvimento do Python executando o comando a seguir na raiz do projeto dbx (por exemplo, a pasta ide-demo/ide-best-practices). Certifique-se de incluir o ponto (.) no final deste comando:
```
pip install -e .
```
Esse comando cria uma pasta covid_analysis.egg-info, que contém informações sobre a versão compilada dos arquivos covid_analysis/__init__.py ecovid_analysis/transforms.py.
Execute os testes executando o comando a seguir:
```
pytest tests/
```
Os resultados dos testes são exibidos no terminal. Todos os quatro testes devem ser mostrados como aprovados.

Dica

Para obter abordagens adicionais de teste, incluindo testes para notebooks R e Scala, consulte Teste de unidade para notebooks.
Opcionalmente, obtenha métricas de cobertura de teste para seus testes executando o seguinte comando:
```
coverage run -m pytest tests/
```
Observação

Se uma mensagem for exibida que coverage não pode ser encontrada, execute pip install coverage e tente novamente.

Para exibir os resultados da cobertura de teste, execute o seguinte comando:
```
coverage report -m
```
Se todos os quatro testes forem aprovados, envie o dbx conteúdo do projeto para o workspace do Azure Databricks executando o seguinte comando:
```
dbx deploy --environment=default
```
Informações sobre o projeto e suas execuções são enviadas para o local especificado no objeto workspace_directory no arquivo .dbx/project.json.

O conteúdo do projeto é enviado para o local especificado no objeto artifact_location no arquivo .dbx/project.json.
Execute a versão de pré-produção do código em seu espaço de trabalho executando o seguinte comando:
```
dbx launch covid_analysis_etl_integ
```
Um link para os resultados da execução é exibido no terminal. O resultado deve ser algo como:
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345
```
Siga este link no navegador da Web para ver os resultados da execução em seu espaço de trabalho.
Execute a versão de produção do código em seu espaço de trabalho executando o seguinte comando:
```
dbx launch covid_analysis_etl_prod
```
Um link para os resultados da execução é exibido no terminal. O resultado deve ser algo como:
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456
```
Siga este link no navegador da Web para ver os resultados da execução em seu espaço de trabalho.

Executar com o GitHub Actions

Na pasta do projeto .github/workflows, os arquivos onpush.yml e onrelease.yml do GitHub Actions fazem o seguinte:

Em cada push para uma marca que começa com v, usa dbx para implantar o trabalho covid_analysis_etl_prod.
Em cada push que não é para uma marca que começa com v:
1. Usa pytest para executar os testes de unidade.
2. Usa dbx para implantar o arquivo especificado no trabalho covid_analysis_etl_integ no workspace remoto.
3. Usa dbx para iniciar o arquivo já implantado especificado no trabalho covid_analysis_etl_integ no workspace remoto, rastreando essa execução até que ela seja concluída.

Observação

Um arquivo de GitHub Actions adicional, databricks_pull_request_tests.yml, é fornecido para você como um modelo para experimentar, sem afetar os arquivos onpush.yml e onrelease.yml do GitHub Actions. Você pode executar este exemplo de código sem o arquivo databricks_pull_request_tests.yml do GitHub Actions. Seu uso não é abordados neste artigo.

As subseções a seguir descrevem como configurar e executar os arquivos onpush.yml e onrelease.yml do GitHub Actions.

Configurar para usar o GitHub Actions

Configure seu workspace do Azure Databricks seguindo as instruções nas Entidades de serviço para CI/CD. Isso inclui as seguintes ações:

Crie uma entidade de serviço.
Crie um token do Microsoft Entra ID para a entidade de serviço.

Como prática recomendada de segurança, o Databricks recomenda que você use um token do Microsoft Entra ID para uma entidade de serviço, em vez do token de acesso pessoal do Databricks para o usuário do workspace, para permitir que o GitHub se autentique com seu workspace do Azure Databricks.

Depois de criar a entidade de serviço e seu token do Microsoft Entra ID, pare e anote o valor do token do Microsoft Entra ID, que você usará na próxima seção.

Executar o GitHub Actions

Etapa 1: publicar seu repositório clonado

Em Visual Studio Code, na barra lateral, clique no ícone GitHub. Se o ícone não estiver visível, habilite a extensão Problemas e solicitações de pull do GitHub por meio da exibição das Extensões (Exibição > Extensões) primeiro.
Se o botão Entrar estiver visível, clique nele e siga as instruções na tela para entrar em sua conta do GitHub.
Na barra de menus, clique em Exibição > Paleta de Comandos, digite Publish to GitHub e clique em Publicar no GitHub.
Selecione uma opção para publicar seu repositório clonado em sua conta do GitHub.

Etapa 2: adicionar segredos criptografados ao repositório

No site do GitHub para seu repositório publicado, siga as instruções em Criar segredos criptografados para um repositório para os seguintes segredos criptografados:

Crie um segredo criptografado chamado DATABRICKS_HOST, defina como o valor da URL por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net.
Crie um segredo criptografado chamado DATABRICKS_TOKEN, definido como o valor do token do Microsoft Entra ID para a entidade de serviço.

Etapa 3: criar e publicar uma ramificação no repositório

Em Visual Studio Code, no modo de exibição do Controle do Código-Fonte (Exibição > Controle do Código-Fonte), clique no ícone ... (Modos de Exibição e Mais Ações).
Clique em Branch > Criar Ramificação de .
Insira um nome para o branch, por exemplo my-branch.
Selecione o branch do qual criar a ramificação, por exemplo , principal.
Faça uma alteração secundária em um dos arquivos no repositório local e salve o arquivo. Por exemplo, faça uma alteração secundária em um comentário de código no arquivo tests/transforms_test.py.
No modo de exibição do Controle do Código-Fonte, clique no ícone ... (Modos de Exibição e Mais Ações) novamente.
Clique em Alterações > de Fase de Todas as Alterações.
Clique no ícone ... (Modos de Exibição e Mais Ações) novamente.
Clique em Confirmar > Confirmação em Etapas.
Insira uma mensagem para a confirmação.
Clique no ícone ... (Modos de Exibição e Mais Ações) novamente.
Clique em Branch > Publicar Branch.

Etapa 4: criar uma solicitação de pull e mesclagem

Acesse o site do GitHub para seu repositório publicado, https://github/<your-GitHub-username>/ide-best-practices.
Na guia Solicitações de pull, ao lado do meu branch teve pushs recentes, clique em Comparar e solicitação de pull.
Clique em Criar solicitação de pull.
Na página de solicitação de pull, aguarde o ícone ao lado de CI pipeline / ci-pipeline (push) para exibir uma marca de seleção verde. (Pode demorar alguns minutos 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 visíveis, clique em Mostrar todas as verificações.
Se a marca de seleção verde for exibida, mescle a solicitação de pull no branch main clicando na Mesclar solicitação de pull.

Compartilhar via