Partilhar via

Usar dbx com o Visual Studio Code

  • Artigo

Importante

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

O Databricks recomenda que você use o Databricks Asset Bundles em vez do dbx Databricks Labs. Consulte O que são Databricks Asset Bundles? e Migrar de dbx para bundles.

Para usar o Azure Databricks com o Visual Studio Code, consulte o artigo Extensão Databricks para 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:

Este artigo usa dbx by Databricks Labs junto com o Visual Studio Code para enviar o exemplo de código para um espaço de trabalho remoto do Azure Databricks. dbx instrui o Azure Databricks a Visão geral da orquestração no Databricks executar o código enviado em um cluster de trabalhos do Azure Databricks nesse espaço de trabalho.

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

Para CI/CD, dbx suporta as seguintes plataformas 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 dbxe este exemplo de código, juntamente com as ações do GitHub e do GitHub.

Requisitos de exemplo de código

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

  • Um espaço de trabalho do Azure Databricks na sua conta do Azure Databricks.
  • Uma conta GitHub. Crie uma conta no GitHub, se ainda não tiver uma.

Além disso, em sua máquina 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 do terminal Web do cluster para executar o comando . Consulte também a seção "Ambiente do sistema" nas notas de versão do Databricks Runtime, versões e compatibilidade para a versão do Databricks Runtime para seus clusters de destino. Em qualquer caso, a versão do Python deve ser 3.8 ou superior.

    Para obter a versão do Python que está atualmente referenciada na sua máquina local, execute python --version a partir do seu terminal local. (Dependendo de como você configura o Python em sua máquina local, talvez seja necessário executápython3 em vez de python ao longo deste artigo.) Consulte também Selecione um interpretador 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 seu terminal local. (Dependendo de como você configura o Python ou pip em sua máquina local, talvez seja necessário executápip3 em vez de pip ao longo deste artigo.)

  • DBX versão 0.8.0 ou superior. Você pode instalar o dbx pacote a partir do Python Package Index (PyPI) executando pip install dbx.

    Nota

    Não é necessário instalar 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 Python para garantir que você esteja usando as versões corretas do Python e dependências de pacote em seus dbx projetos. Este artigo abrange pipenv.

  • O Databricks CLI versão 0.18 ou inferior, configurado com autenticação.

    Nota

    Não é necessário instalar a CLI do Databricks herdada (Databricks CLI versão 0.17) agora. Você pode instalá-lo posteriormente na seção de configuração de exemplo de código. Se quiser instalá-lo mais tarde, lembre-se de configurar a autenticação nesse momento.

  • Visual Studio Code.

  • A extensão Python para Visual Studio Code.

  • A extensão Pull Requests and Issues do GitHub para Visual Studio Code.

  • Git.

Sobre o exemplo de código

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

  1. Obtém dados do repositório owid/covid-19-data no GitHub.
  2. Filtra os dados para um código de país ISO 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 de código em funções reutilizáveis.
  6. A unidade testa as funções.
  7. Fornece as configurações e definições do projeto dbx para permitir que o código grave os dados numa tabela Delta num ambiente remoto do Azure Databricks.

Configurar o exemplo de código

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.

Nota

Estas etapas não incluem a configuração deste exemplo de código para CI/CD. Não é necessário configurar o CI/CD para executar este exemplo de código. Se você quiser configurar o CI/CD mais tarde, consulte Executar com ações do GitHub.

Etapa 1: Criar um ambiente virtual Python

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

    Para Linux e macOS:

    mkdir ide-demo
cd ide-demo
code .

    Gorjeta

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

    Para Windows:

    md ide-demo
cd ide-demo
code .

  2. No Visual Studio Code, na barra de menus, clique em Exibir > Terminal.

  3. A partir da raiz da pasta ide-demo, execute o comando pipenv com a seguinte opção, onde <version> é a versão de destino do Python que você já instalou localmente (e, idealmente, uma versão que corresponda à versão do Python dos seus clusters de destino), por exemplo 3.8.14.

    pipenv --python <version>

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

  4. Selecione o interpretador Python de destino e ative o ambiente virtual Python:

    1. Na barra de menus, clique em Exibir > Paleta de Comandos, digite Python: Selecte, em seguida, clique em Python: Select Interpreter.

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

    3. Na barra de menus, clique em > de Comandos, digite e clique em Terminal: Create.

    4. Verifique se o prompt de comando indica que você está no pipenv shell. Para confirmar, você deve ver algo como (<your-username>) antes do prompt de comando. Se você não vê-lo, execute o seguinte comando:

      pipenv shell

      Para sair do pipenv shell, execute o comando exite os parênteses desaparecem.

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

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

  1. No Visual Studio Code, abra a ide-demo pasta (File > Open Folder), se ainda não estiver aberta.
  2. Clique em > de comandos, digite e, em seguida, clique em Git: Clone.
  3. Em Fornecer URL do repositório ou escolher uma fonte de repositório, insira https://github.com/databricks/ide-best-practices
  4. Navegue até a pasta ide-demo e clique em Selecionar local do repositório.

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

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

    pip install dbx

  2. Confirme se dbx está instalado. Para tal, 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 estiver abaixo de 0.8.0, atualize 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

  3. Quando você instala dbxo , a CLI do Databricks herdada (Databricks CLI versão 0.17) também é instalada automaticamente. Para confirmar se a CLI do Databricks herdada (Databricks CLI versão 0.17) está instalada, execute o seguinte comando:

    databricks --version

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

  4. Se ainda não tiver configurado a CLI herdada do Databricks (versão 0.17) com de autenticação, tem de fazê-lo agora. Para confirmar se a autenticação está configurada, execute o seguinte comando básico para obter algumas informações resumidas sobre seu espaço de trabalho do Azure Databricks. Certifique-se de incluir a barra (/) após o ls subcomando:

    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.

  5. Instale os pacotes Python dos quais este exemplo de código depende. Para fazer isso, execute o seguinte comando da ide-demo/ide-best-practices pasta:

    pip install -r unit-requirements.txt

  6. Confirme se os pacotes dependentes do exemplo de código estão instalados. Para tal, execute o seguinte comando:

    pip list

    Se os pacotes listados nos arquivos requirements.txt e unit-requirements.txt estiverem em algum lugar nessa lista, os pacotes dependentes serão instalados.

    Nota

    Os arquivos listados em requirements.txt são para versões de pacotes específicos. Para melhor compatibilidade, você pode fazer referência cruzada dessas versões com o tipo de nó de cluster que deseja que seu espaço de trabalho do Azure Databricks use para executar implantações posteriormente. 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.

Etapa 4: Personalizar o exemplo de código para seu espaço de trabalho do Azure Databricks

  1. Personalize as configurações do projeto do dbx repo. Para fazer isto, no ficheiro .dbx/project.json, altere o valor do objeto profile de DEFAULT para o nome do perfil que corresponde ao que foi configurado para a autenticação com a CLI legada do Databricks (Databricks CLI 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
}

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

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

    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'

Gorjeta

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

Explore o exemplo de código

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

Modularização de código

Código não modularizado

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

Código modularizado

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

Testar

Testes de unidade

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

Corredor de teste unitário

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

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

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.

Packaging

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

Outros ficheiros

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

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

Execute o exemplo de código

Você pode usar dbx em sua máquina local para instruir o Azure Databricks a executar o exemplo de código em seu espaço de trabalho remoto sob demanda, conforme descrito na próxima subseção. Ou você pode usar as Ações do GitHub para que o GitHub execute o exemplo de código toda vez que enviar alterações de código para o repositório do GitHub.

Executar com dbx

  1. Instale o covid_analysis conteúdo da pasta como um pacote no modosetuptools executando o seguinte comando a partir da raiz do seu dbx projeto (por exemplo, a ide-demo/ide-best-practices pasta). Certifique-se de incluir o ponto (.) no final deste comando:

    pip install -e .

    Este comando cria uma covid_analysis.egg-info pasta, que contém informações sobre a versão compilada dos covid_analysis/__init__.py arquivos e covid_analysis/transforms.py .

  2. Execute os testes executando o seguinte comando:

    pytest tests/

    Os resultados dos testes são exibidos no terminal. Todos os quatro testes devem mostrar como aprovados.

    Gorjeta

    Para abordagens adicionais de teste, incluindo testes para notebooks R e Scala, consulte Teste de unidade para notebooks.

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

    coverage run -m pytest tests/

    Nota

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

    Para exibir os resultados da cobertura do teste, execute o seguinte comando:

    coverage report -m

  4. Se todos os quatro testes forem aprovados, envie o conteúdo do projeto para seu dbx espaço de trabalho do Azure Databricks, executando o seguinte comando:

    dbx deploy --environment=default

    As informações sobre o projeto e suas execuções são enviadas para o local especificado no workspace_directory objeto no .dbx/project.json arquivo.

    O conteúdo do projeto é enviado para o local especificado no artifact_location objeto no .dbx/project.json arquivo.

  5. 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 corrida é exibido no terminal. Deve ter um aspeto semelhante a:

    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.

  6. 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 corrida é exibido no terminal. Deve ter um aspeto semelhante a:

    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 ações do GitHub

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

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

Nota

Um arquivo adicional de Ações do GitHub, databricks_pull_request_tests.yml, é fornecido para você como um modelo para experimentar, sem afetar os arquivos e onpush.yml as Ações do onrelease.yml GitHub. Você pode executar este exemplo de código sem o arquivo de ações do databricks_pull_request_tests.yml GitHub. A sua utilização não é abordada neste artigo.

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

Configurar para usar as Ações do GitHub

Configure o seu espaço de trabalho do Azure Databricks seguindo as instruções em Principais de serviço para CI/CD. Isso inclui as seguintes ações:

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

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

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

Executar ações do GitHub

Etapa 1: Publicar 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, habilite a extensão Pull Requests and Issues do GitHub através da visualização Extensions (View > Extensions) primeiro.
  2. Se o botão Entrar estiver visível, clique nele e siga as instruções na tela para entrar na sua conta do GitHub.
  3. Na barra de menus, clique em > de Comandos, digite e clique em Publicar no Publish to GitHub.
  4. Selecione uma opção para publicar seu repositório clonado em sua conta do GitHub.
Etapa 2: adicionar segredos criptografados ao seu repositório

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

  • Crie um segredo criptografado chamado DATABRICKS_HOST, defina o valor do URL por espaço de trabalho , por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.
  • Crie um segredo criptografado chamado DATABRICKS_TOKEN, definido com o valor do token do ID do Microsoft Entra para o principal de serviço.
Etapa 3: Criar e publicar uma ramificação no repositório
  1. No Visual Studio Code, na vista Controlo de Código-Fonte (Vista > Controlo de Código-Fonte), clique no ícone … (Vistas 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 da qual deseja criar outra ramificação, por exemplo, principal.
  5. Faça uma pequena alteração em um dos arquivos no repositório local e salve o arquivo. Por exemplo, faça uma pequena alteração em um comentário de código no tests/transforms_test.py arquivo.
  6. Na vista Controlo de Código-Fonte, clique novamente no ícone … (Vistas e Mais Ações).
  7. Clique em Alterações > Estágio Todas as alterações.
  8. Clique novamente no ícone ... (Views and More Actions).
  9. Clique em Confirmar > Confirmação em Estágios.
  10. Insira uma mensagem para a confirmação.
  11. Clique novamente no ícone ... (Views and More Actions).
  12. Clique em Branch > Publish Branch.
Etapa 4: Criar uma solicitação pull e mesclar
  1. Vá para o site do GitHub para o seu repositório publicado, https://github/<your-GitHub-username>/ide-best-practices.
  2. Na guia Solicitações pull, ao lado de my-branch had recent pushes, clique em Compare & pull request.
  3. Clique em Criar pedido Pull.
  4. Na página de solicitação pull, aguarde até que o ícone ao lado de CI pipleline / ci-pipeline (push) exiba uma marca de seleção verde. (Pode levar 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 aparecendo, clique em Mostrar todas as verificações.
  5. Se a marca de seleção verde aparecer, mescle a solicitação pull na main ramificação clicando em Merge pull request.