Pular para o conteúdo principal

Use dbx com o Visual Studio Code

important

Essa documentação foi descontinuada e pode não estar atualizada.

Databricks recomenda que o senhor use Databricks ativo Bundles em vez de dbx da Databricks Labs. Consulte O que são Databricks ativo Bundles? e Migrar de dbx para bundles.

Para usar Databricks o com o Visual Studio Code, consulte a extensão Databricks artigos para o Visual Studio Code.

Este artigo descreve um exemplo de Python código baseado em com o qual o senhor pode trabalhar em qualquer PythonIDE compatível com. 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:

Este artigo usa o dbx do Databricks Labs junto com o Visual Studio Code para enviar a amostra de código para um site remoto Databricks workspace. dbx instrui Databricks a solicitar o uso de Databricks Jobs para executar o código enviado em um Databricks Job agrupado naquele workspace.

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

Para CI/CD, o site dbx é compatível com as seguintes plataformas de CI/CD:

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

Requisitos de amostra de código​

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

Além disso, em sua máquina de desenvolvimento local, você deve ter o seguinte:

  • Python versão 3.8 ou acima.

    O senhor deve usar uma versão do Python que corresponda à que está instalada no clustering de destino. Para obter a Python versão do que está instalada em um cluster existente, o python --version senhor pode usar o terminal da Web do cluster para executar o comando. Consulte também a seção "System environment" (Ambiente do sistema) no site Databricks Runtime notas sobre as versões e a compatibilidade da versão Databricks Runtime para o seu clustering de destino. De qualquer forma, a versão do Python deve ser 3.8 ou superior.

    Para obter a versão do Python atualmente referenciada em seu computador local, execute python --version em seu terminal local. (Dependendo de como o senhor configurou o site Python no computador local, talvez seja necessário executar python3 em vez de python ao longo deste artigo). Consulte também Selecionar um interpretador Python.

  • pip. pip é instalado automaticamente com as versões mais recentes do Python. Para verificar se o site pip já está instalado, execute pip --version em seu terminal local. (Dependendo de como o senhor configurou 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 acima. O senhor pode instalar o pacote dbx a partir do Python pacote Index (PyPI) executando pip install dbx.

nota

Você não precisa instalar o dbx agora. Você pode instalá-lo posteriormente na seção de configuração da amostra de código.

nota

O senhor não precisa instalar o Databricks CLI herdado (Databricks CLI versão 0.17) agora. Você pode instalá-lo posteriormente na seção de configuração da amostra de código. Se quiser instalá-lo mais tarde, lembre-se de configurar a autenticação naquele momento.

Sobre a amostra de código​

O exemplo de código Python para esse artigo, disponível no repositório databricks/ide-best-practices em GitHub, faz o seguinte:

  1. Obtém dados do repositório owid/covid-19-data no GitHub.
  2. Filtra os dados de um código ISO de país específico.
  3. Cria uma tabela dinâmica a partir dos dados.
  4. Executa a Limpeza de dados nos dados.
  5. Modulariza a lógica do código em funções reutilizáveis.
  6. A unidade testa as funções.
  7. Fornece configurações e definições do projeto dbx para permitir que o código grave os dados em uma tabela Delta em um site remoto Databricks workspace.

Configurar a amostra de código​

Depois de definir os requisitos para essa amostra de código, conclua as etapas a seguir para começar a usar a amostra de código.

nota

Essas etapas não incluem a configuração desse exemplo de código para CI/CD. O senhor não precisa configurar o site CI/CD para executar este exemplo de código. Se o senhor quiser configurar o site CI/CD posteriormente, consulte execução com GitHub Actions.

Etapa 1: Criar um ambiente virtual Python​

  1. No seu terminal, crie uma pasta em branco para conter um ambiente virtual para essa amostra de código. Essas instruções usam uma pasta principal chamada ide-demo. Você pode dar a essa pasta o nome que quiser. Se o senhor usar um nome diferente, substitua o nome em todo este artigo. Depois de criar a pasta, mude para ela e, em seguida, inicie o Visual Studio Code a partir dessa pasta. Não se esqueça de incluir o ponto (.) após o comando code.

    No Linux e macOS:

    Bash
    mkdir ide-demo
    cd ide-demo
    code .
dica

Se o senhor receber o erro command not found: code, consulte Iniciar a partir da linha de comando no site da Microsoft.

No Windows:

PowerShell
md ide-demo
cd ide-demo
code .

  1. No Visual Studio Code, na barra de menus, clique em view > Terminal .

  2. Na raiz da pasta ide-demo, execute o comando pipenv com a seguinte opção, em que <version> é a versão de destino do Python que o senhor já tem instalada localmente (e, idealmente, uma versão que corresponda à versão do Python do clustering de destino), por exemplo, 3.8.14.

    Bash
    pipenv --python <version>

    Anote o valor Virtualenv location na saída do comando pipenv , pois você precisará dele na próxima passo.

  3. Selecione o interpretador Python de destino e, em seguida, ative o ambiente virtual Python:

    1. Na barra de menus, clique em Exibir > Paleta de comandos , digite Python: Select e clique em Python: Select Interpreter.

    2. Selecione o interpretador Python no caminho para o ambiente virtual Python que o senhor acabou de criar. (Esse caminho é listado como o valor Virtualenv location na saída do comando pipenv ).

    3. Na barra de menus, clique em view > comando Palette , digite Terminal: Create e clique em Terminal: Create New Terminal .

    4. Certifique-se de que o prompt de comando indique que o senhor está no shell pipenv. Para confirmar, o senhor deve ver algo como (<your-username>) antes do prompt de comando. Se o senhor não o vir, execute o seguinte comando:

      Bash
      pipenv shell

      Para sair do pipenv shell, execute o comando exit, e os parênteses desaparecerão.

    Para obter mais informações, consulte Usando ambientes Python no VS Code na documentação do Visual Studio Code.

Etapa 2: clonar a amostra de código do GitHub​

  1. No Visual Studio Code, abra a pasta ide-demo ( Arquivo > Abrir pasta ), se ela ainda não estiver aberta.
  2. Clique em view > comando Palette , digite Git: Clone e, em seguida, clique em Git: Clone.
  3. Em Forneça o URL do repositório ou escolha uma fonte do repositório , digite https://github.com/databricks/ide-best-practices
  4. Navegue até sua pasta ide-demo e clique em Selecionar localização do repositório .

Etapa 3: instalar as dependências da amostra de código​

  1. Instale uma versão de dbx e Databricks CLI versão 0.18 ou abaixo que seja compatível com sua versão de Python. Para isso, no Visual Studio Code, em seu terminal, a partir da pasta ide-demo com pipenv shell ativado (pipenv shell), execute o seguinte comando:

    Bash
    pip install dbx

  2. Confirme se o dbx está instalado. Para fazer isso, execute o seguinte comando:

    Bash
    dbx --version

    Se o número da versão for retornado, o dbx será instalado.

    Se o número da versão for abaixo de 0.8.0, atualize o site dbx executando o seguinte comando e, em seguida, verifique novamente o número da versão:

    Bash
    pip install dbx --upgrade
    dbx --version

    # Or ...
    python -m pip install dbx --upgrade
    dbx --version

  3. Quando o senhor instala o site dbx, a CLI legada da Databricks (Databricks CLI versão 0.17) também é instalada automaticamente. Para confirmar que o legado Databricks CLI (Databricks CLI versão 0.17) está instalado, execute o seguinte comando:

    Bash
    databricks --version

    Se a versão 0.17 da Databricks CLI for retornada, a Databricks CLI herdada será instalada.

  4. Se o senhor não tiver configurado a CLI antiga da Databricks (Databricks CLI versão 0.17) com autenticação, deverá fazê-lo agora. Para confirmar que a autenticação está configurada, execute o seguinte comando básico para obter algumas informações resumidas sobre o seu Databricks workspace. Certifique-se de incluir a barra frontal (/) após o subcomando ls:

    Bash
    databricks workspace ls /

    Se uma lista de nomes de pastas em nível de raiz para seu workspace for retornada, a autenticação será configurada.

  5. Instale o pacote Python do qual este exemplo de código depende. Para fazer isso, execute o seguinte comando na pasta ide-demo/ide-best-practices:

    Bash
    pip install -r unit-requirements.txt

  6. Confirme se o pacote dependente da amostra de código está instalado. Para fazer isso, execute o seguinte comando:

    Bash
    pip list

    Se o pacote listado nos arquivos requirements.txt e unit-requirements.txt estiver em algum lugar dessa lista, o pacote dependente será instalado.

nota

Os arquivos listados em requirements.txt são para versões específicas do pacote. Para maior compatibilidade, o senhor pode fazer referência cruzada dessas versões com o tipo de nó de clustering que deseja que o Databricks workspace use para executar implantações posteriormente. Consulte a seção "Ambiente do sistema" para obter a versão do seu clustering em Databricks Runtime em Databricks Runtime notas sobre versões e compatibilidade.

Etapa 4: Personalize o exemplo de código para seu site Databricks workspace​

  1. Personalize as configurações do projeto dbx do repositório. Para fazer isso, no arquivo .dbx/project.json, altere o valor do objeto profile de DEFAULT para o nome do perfil que corresponda ao que o senhor configurou para autenticação com a CLI legada da Databricks (versão 0.17 da CLI da Databricks). Se o senhor não configurou nenhum perfil que não sejadefault, deixe DEFAULT como está. Por exemplo:

    JSON
    {
      "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
    }

  2. Personalize as configurações de implantação do projeto dbx. Para isso, no conf/deployment.yml arquivo, altere o valor dos spark_version node_type_id objetos e 10.4.x-scala2.12 de e para as cadeias de caracteres m6gd.large da Databricks versão de tempo de execução do e o tipo de nó de clustering que o senhor deseja que Databricks workspace o use para executar implantações.

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

    YAML
    environments:
      default:
        workflows:
          - name: 'covid_analysis_etl_integ'
            new_cluster:
              spark_version: '10.4.x-scala2.12'
              num_workers: 1
            node_type_id: 'i3.xlarge'
            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: 'i3.xlarge'
              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: 'i3.xlarge'
              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. O senhor pode usar valores diferentes para definições de trabalho diferentes. O senhor também pode criar valores compartilhados e reutilizá-los nas definições de trabalho para reduzir os erros de digitação e a manutenção do código. Veja o exemplo de YAML na documentação dbx.

Explore a amostra de código​

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

Modularização de código​

Código não modularizado​

O arquivo jobs/covid_trends_job_raw.py é uma versão não modularizada da lógica do código. O senhor pode executar esse arquivo sozinho.

Código modularizado​

O arquivo jobs/covid_trends_job.py é uma versão modularizada da lógica do 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 a contém.

Testando​

Testes unitários​

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 unitário​

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 medições 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 o senhor executou anteriormente com pip, contém uma lista de pacotes dos quais os testes de unidade também dependem.

Embalagem​

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/workflows contém três arquivos, databricks_pull_request_tests.yml, onpush.yml e onrelease.yaml, que representam as GitHub Actions, abordadas posteriormente na seção GitHub Actions.
  • O arquivo .gitignore contém uma lista de pastas e arquivos locais que o Git ignora para o seu repositório.

execução do exemplo de código​

O senhor pode usar dbx no computador local para instruir o Databricks a executar o exemplo de código no workspace remoto sob demanda, conforme descrito na próxima subseção. Ou o senhor pode usar GitHub Actions para que GitHub execute a amostra de código sempre que fizer alterações de código no seu repositório GitHub.

execução com dbx​

  1. Instale o conteúdo da pasta covid_analysis como um pacote no modo de desenvolvimento Python setuptools executando o seguinte comando na raiz do seu projeto dbx (por exemplo, a pasta ide-demo/ide-best-practices ). Não se esqueça de incluir o ponto (.) no final desse comando:

    Bash
    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 e covid_analysis/transforms.py.

  2. Execute os testes executando o seguinte comando:

    Bash
    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 R e Scala Notebook, consulte Teste de unidade para Notebook.

  1. Opcionalmente, obtenha métricas de cobertura de teste para seus testes executando o seguinte comando:

    Bash
    coverage run -m pytest tests/
nota

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

Para acessar view os resultados da cobertura de teste, execute o seguinte comando:

Bash
coverage report -m

  1. Se todos os quatro testes forem aprovados, envie o conteúdo do projeto dbx para o site Databricks workspace, executando o seguinte comando:

    Bash
    dbx deploy --environment=default

    As informações sobre o projeto e sua execução 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.

  2. Execute a versão de pré-produção do código em seu site workspace, executando o seguinte comando:

    Bash
    dbx launch covid_analysis_etl_integ

    Um link para os resultados da execução é exibido no terminal. Deve ter a seguinte aparência:

    Bash
    https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345

    Siga este link em seu navegador da Web para ver os resultados da execução em seu site workspace.

  3. Execute a versão de produção do código em seu site workspace, executando o seguinte comando:

    Bash
    dbx launch covid_analysis_etl_prod

    Um link para os resultados da execução é exibido no terminal. Deve ter a seguinte aparência:

    Bash
    https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456

    Siga este link em seu navegador da Web para ver os resultados da execução em seu site workspace.

execução com GitHub Actions​

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

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

Um arquivo GitHub Actions adicional, databricks_pull_request_tests.yml, é fornecido para o senhor experimentar como padrão, sem afetar os arquivos onpush.yml e onrelease.yml GitHub Actions. O senhor pode executar esse exemplo de código sem o arquivo databricks_pull_request_tests.yml GitHub Actions. Seu uso não é abordado neste artigo.

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

Configurar para usar o GitHub Actions​

Configure seu Databricks workspace seguindo as instruções em entidade de serviço para CI/CD. Isso inclui as seguintes ações:

  1. Crie uma entidade de serviço Databricks.
  2. Crie um Databricks tokens de acesso para a Databricks entidade de serviço.

Como prática recomendada de segurança, Databricks recomenda que o senhor use tokens de acesso Databricks para uma Databricks entidade de serviço, em vez dos tokens de acesso pessoal Databricks para seu usuário workspace, para permitir que GitHub se autentique com seu Databricks workspace.

Depois de criar a Databricks entidade de serviço e seus tokens de acesso Databricks, pare e anote o valor dos tokens de acesso Databricks, que será usado na próxima seção.

execução GitHub Actions​

Etapa 1: publique seu repositório clonado​
  1. No Visual Studio Code, na barra lateral, clique no ícone do GitHub . Se o ícone não estiver visível, ative primeiro a extensão GitHub Pull Requests and Issues por meio das Extensões view (view > Extensions ).
  2. Se o botão Sign In estiver visível, clique nele e siga as instruções na tela para entrar no site GitHub account.
  3. Na barra de menus, clique em Exibir > Paleta de comandos , digite Publish to GitHub e clique em Publicar em GitHub .
  4. Selecione uma opção para publicar o repositório clonado no site GitHub account.
Etapa 2: adicionar segredos criptografados ao seu 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 denominado DATABRICKS_HOST, definido como o valor do URL da instânciaworkspace, por exemplo, https://dbc-a1b2345c-d6e7.cloud.databricks.com.
  • Crie um segredo criptografado chamado DATABRICKS_TOKEN, definido como o valor dos tokens de acesso Databricks para a entidade de serviço Databricks.
Etapa 3: crie e publique uma ramificação em seu repositório​
  1. No Visual Studio Code, no Controle de código-fonte view (Exibir > Controle de código-fonte ), clique no ícone ... (Exibir e Mais ações ).
  2. Clique em Branch > Create Branch From .
  3. Insira um nome para a ramificação, por exemplo my-branch.
  4. Selecione a ramificação a partir da qual criar a ramificação, por exemplo, principal .
  5. Faça uma pequena alteração em um dos arquivos em seu repositório local e salve o arquivo. Por exemplo, faça uma pequena alteração em um comentário de código no arquivo tests/transforms_test.py.
  6. No Source Control view, clique novamente no ícone ... (view and More Actions ).
  7. Clique em Alterações > Estágio de todas as alterações .
  8. Clique novamente no ícone ... (visualizar e mais ações ).
  9. Clique em commit > commit Staged .
  10. Digite uma mensagem para o commit.
  11. Clique novamente no ícone ... (visualizar e mais ações ).
  12. Clique em Branch > Publish Branch .
Etapa 4: criar uma solicitação pull e fazer o merge​
  1. Acesse o site do GitHub para seu repositório publicado, https://github/<your-GitHub-username>/ide-best-practices.
  2. Em Pull requests tab, ao lado de my-branch had recent pushes , clique em Compare & pull request .
  3. Clique em Criar pull request .
  4. Na página de pull request, aguarde até que o ícone ao lado de CI pipleline / ci-pipeline (push) exiba uma marca de seleção verde. (Pode levar alguns minutos até 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 os Detalhes não estiverem mais sendo exibidos, clique em Mostrar todas as verificações .
  5. Se a marca de seleção verde aparecer, merge o pull request no branch main clicando em merge pull request .
Última atualização em