Share via

Depurar código usando Databricks Connect para a extensão Databricks para Visual Studio Code

  • Artigo

Este artigo descreve como depurar código usando a integração Databricks Connect na extensão Databricks para Visual Studio Code. Consulte O que é a extensão Databricks para Visual Studio Code?.

Essas informações pressupõem que você já tenha instalado e configurado a extensão Databricks para Visual Studio Code. Consulte Instalar a extensão Databricks para Visual Studio Code.

Nota

Este recurso é Experimental.

A integração do Databricks Connect dentro da extensão Databricks para Visual Studio Code suporta apenas uma parte do padrão de autenticação unificada do cliente Databricks. Para obter mais informações, consulte Configuração de autenticação para a extensão Databricks para VS Code.

A extensão Databricks para Visual Studio Code inclui Databricks Connect. Você pode usar o Databricks Connect de dentro da extensão Databricks para Visual Studio Code para executar e fazer depuração passo a passo de arquivos Python (.py) individuais e blocos de anotações Python Jupyter (.ipynb). A extensão Databricks para Visual Studio Code inclui Databricks Connect for Databricks Runtime 13.0 e superior. Não há suporte para versões anteriores do Databricks Connect.

Requisitos

Antes de poder usar o Databricks Connect de dentro da extensão Databricks para Visual Studio Code, você deve primeiro atender aos requisitos do Databricks Connect. Esses requisitos incluem coisas como um espaço de trabalho habilitado com o Unity Catalog, um cluster executando o Databricks Runtime 13.0 ou superior e com um modo de acesso ao cluster de Usuário Único ou Compartilhado, e uma versão local do Python instalada com suas versões principais e secundárias correspondentes às do Python instaladas no cluster.

Etapa 1: Criar um ambiente virtual Python

Crie e ative um ambiente virtual Python para seu projeto de código Python. Os ambientes virtuais Python ajudam a certificar-se de que o seu projeto de código está a utilizar versões compatíveis dos pacotes Python e Python (neste caso, o pacote Databricks Connect). As instruções e exemplos neste artigo usam venv ou Poetry para ambientes virtuais Python. O Databricks não testou totalmente o pacote Databricks Connect com outros tipos de ambientes virtuais Python, como o Conda.

Crie um ambiente virtual Python usando venv

  1. A partir do seu terminal de código do Visual Studio (View > Terminal) definido para o diretório raiz do seu projeto de código Python, instrua venv a usar Python para o ambiente virtual e, em seguida, crie os arquivos de suporte do ambiente virtual em um diretório oculto nomeado .venv dentro do diretório raiz do seu projeto de código Python, executando o seguinte comando:

    # Linux and macOS
python3.10 -m venv ./.venv
# Windows
python3.10 -m venv .\.venv

    O comando anterior usa Python 3.10, que corresponde à versão principal e secundária do Python que o Databricks Runtime 13.0 usa. Certifique-se de usar a versão principal e secundária do Python que corresponda à versão instalada do Python no seu cluster.

  2. Se o Visual Studio Code exibir a mensagem "Notamos que um novo ambiente foi criado. Deseja selecioná-lo para a pasta do espaço de trabalho", clique em Sim.

  3. Use venv para ativar o ambiente virtual. Consulte a documentação do venv para obter o comando correto a ser usado, com base no seu sistema operacional e tipo de terminal. Por exemplo, no macOS executando zsh:

    source ./.venv/bin/activate

    Você saberá que seu ambiente virtual é ativado quando o nome do ambiente virtual (por exemplo, .venv) é exibido entre parênteses imediatamente antes do prompt do terminal.

    Para desativar o ambiente virtual a qualquer momento, execute o comando deactivate.

    Você saberá que seu ambiente virtual será desativado quando o nome do ambiente virtual não for mais exibido entre parênteses antes do prompt do terminal.

Vá para a Etapa 2: Atualize seu código Python para estabelecer um contexto de depuração.

Crie um ambiente virtual Python usando o Poetry

  1. Instale o Poetry, se ainda não o fez.

  2. A partir do seu terminal de código do Visual Studio (View > Terminal) definido para o diretório raiz do seu projeto de código Python existente, instrua poetry a inicializar seu projeto de código Python para Poetry, executando o seguinte comando:

    poetry init

  3. Poesia exibe vários prompts para você completar. Nenhum desses prompts é específico para a extensão Databricks para Visual Studio Code ou Databricks Connect. Para obter informações sobre esses prompts, consulte init.

  4. Depois de concluir os prompts, o Poetry adiciona um pyproject.toml arquivo ao seu projeto Python. Para obter informações sobre o pyproject.toml arquivo, consulte O arquivo pyproject.toml.

  5. Com o terminal do Visual Studio Code ainda definido para o diretório raiz do seu projeto de código Python, instrua poetry a ler o pyproject.toml arquivo, resolver as dependências e instalá-las, criar um poetry.lock arquivo para bloquear as dependências e, finalmente, criar um ambiente virtual. Para tal, execute o seguinte comando:

    poetry install

  6. Instrua o Visual Studio Code para usar o interpretador Python incluído no ambiente virtual para este projeto Python, da seguinte maneira:

    1. Encontre o caminho completo para o interpretador Python que está no ambiente virtual para este projeto Python, executando o seguinte comando a partir do diretório raiz do projeto:

      poetry env info

    2. Copie Virtualenv > Executable o caminho completo exibido na saída do campo, por exemplo, o caminho completo que contém pypoetry/virtualenvs.

    3. Na Paleta de Comandos (Exibir Paleta de Comandos), digite o comando >Python: Select Interpreter> .

    4. Insira o caminho completo para o interpretador Python que você acabou de copiar.

  7. Com o terminal do Visual Studio Code ainda definido para o diretório raiz do seu projeto de código Python, instrua poetry para ativar o ambiente virtual e entrar no shell. Para tal, execute o seguinte comando:

    poetry shell

    Você saberá que seu ambiente virtual está ativado e o shell é inserido quando o nome do ambiente virtual é exibido entre parênteses imediatamente antes do prompt do terminal.

    Para desativar o ambiente virtual e sair do shell a qualquer momento, execute o comando exit.

    Você saberá que saiu do shell quando o nome do ambiente virtual não for mais exibido entre parênteses antes do prompt do terminal.

    Para obter mais informações sobre como criar e gerenciar ambientes virtuais do Poetry, consulte Gerenciando ambientes.

Etapa 2: Atualize seu código Python para estabelecer um contexto de depuração

Para estabelecer um contexto de depuração entre o Databricks Connect e seu cluster, seu código Python deve inicializar a DatabricksSession classe chamando DatabricksSession.builder.getOrCreate().

Observe que você não precisa especificar configurações como o nome da instância do espaço de trabalho, um token de acesso ou o ID e o número da porta do cluster ao inicializar a DatabricksSession classe. O Databricks Connect obtém essas informações dos detalhes de configuração que você já forneceu por meio da extensão Databricks para Visual Studio Code anteriormente neste artigo.

Para obter informações adicionais sobre como inicializar a DatabricksSession classe, consulte os exemplos de código do Databricks Connect.

Importante

Se você usar a extensão Databricks para Visual Studio Code para definir o tipo de autenticação para tokens de acesso pessoal, a extensão definirá uma variável de ambiente relacionada SPARK_REMOTE com configurações de contexto de depuração para uso pelo Databricks Connect. Essas configurações de contexto de depuração incluem o nome da instância do espaço de trabalho relacionado, o token de acesso pessoal e a ID do cluster.

No Databricks Connect, você pode usar a classe ou SparkSession junto com SPARK_REMOTE a DatabricksSession autenticação de token de acesso pessoal para estabelecer de forma rápida e fácil o contexto de depuração programaticamente. Para outros tipos de autenticação do Azure Databricks com suporte, você pode usar apenas a DatabricksSession classe para estabelecer o contexto de depuração.

Para obter mais informações, consulte Configurar o cliente na documentação do Databricks Connect.

Etapa 3: Ativar o Databricks Connect

Com a extensão aberta e a seção Espaço de trabalho configurada para seu projeto de código, faça o seguinte:

  1. Na barra de status do Visual Studio Code, clique no botão vermelho Databricks Connect desabilitado .

  2. Se a seção Cluster ainda não estiver configurada na extensão, a seguinte mensagem será exibida: "Anexe um cluster para usar o Databricks Connect". Clique em Anexar Cluster e selecione um cluster que atenda aos requisitos do Databricks Connect.

  3. Se a seção Cluster estiver configurada, mas o cluster não for compatível com o Databricks Connect, clique no botão vermelho Databricks Connect desabilitado , clique em Anexar Cluster e selecione um cluster compatível.

  4. Se o pacote Databricks Connect (e suas dependências) ainda não estiver instalado, a seguinte mensagem será exibida: "Para depuração interativa e preenchimento automático, você precisa do Databricks Connect. Gostaria de instalá-lo no ambiente <environment-name>." Clique em Install (Instalar).

  5. Na barra de status do Visual Studio Code, o botão Databricks Connect enabled é exibido.

    Se o botão vermelho Databricks Connect desativado ainda aparecer, clique nele e conclua as instruções na tela para que o botão Databricks Connect ativado apareça.

  6. Depois que o botão Databricks Connect ativado for exibido, você estará pronto para usar o Databricks Connect.

Nota

Você não precisa configurar a seção Sync Destination da extensão para que seu projeto de código use o Databricks Connect.

Se você usar o Poetry, poderá sincronizar seus pyproject.toml arquivos e poetry.lock com o pacote Databricks Connect instalado (e suas dependências) executando o seguinte comando. Certifique-se de substituir 13.3.2 pela versão do pacote Databricks Connect que corresponde àquela que foi instalada pela extensão Databricks para Visual Studio Code para seu projeto.

poetry add databricks-connect==13.3.2

Etapa 4: Executar ou depurar seu código Python

Depois de habilitar o Databricks Connect para seu projeto de código, execute ou depure seu arquivo Python ou bloco de anotações da seguinte maneira.

Para executar ou depurar um arquivo Python (.py):

  1. Em seu projeto de código, abra o arquivo Python que você deseja executar ou depurar.

  2. Defina quaisquer pontos de interrupção de depuração dentro do arquivo Python.

  3. Na barra de título do editor de ficheiros, clique na seta pendente junto ao ícone de reprodução (Executar ou Depurar). Em seguida, na lista suspensa, selecione Depurar arquivo Python. Essa opção suporta depuração passo a passo, pontos de interrupção, expressões de observação, pilhas de chamadas e recursos semelhantes. Essa opção usa o Databricks Connect para executar código Python localmente, executar código PySpark no cluster no espaço de trabalho remoto e enviar respostas remotas de volta ao Visual Studio Code para depuração local.

    Nota

    Outras opções, que não suportam depuração, incluem:

    • Execute o arquivo Python para usar o Databricks Connect para executar o arquivo ou bloco de anotações, mas sem suporte a depuração. Essa opção envia o arquivo para o espaço de trabalho remoto, executa o código Python e PySpark do arquivo no cluster remoto no espaço de trabalho e envia a resposta remota para o Terminal de Código do Visual Studio.
    • Carregue e execute o arquivo no Databricks para enviar o arquivo para o espaço de trabalho remoto, execute o código Python e PySpark do arquivo no cluster remoto no espaço de trabalho e envie a resposta remota para o terminal do Visual Studio Code. Essa opção não usa o Databricks Connect.
    • Execute Arquivo como Fluxo de Trabalho no Databricks para enviar o arquivo para o espaço de trabalho remoto, execute o código Python e PySpark do arquivo no cluster associado a um trabalho automatizado do Azure Databricks e envie os resultados para um editor no Visual Studio Code. Essa opção não usa o Databricks Connect.

    Executar arquivo no comando do editor Databricks 0

    A opção Executar arquivo atual na janela interativa, se disponível, tenta executar o arquivo localmente em um editor interativo especial do Visual Studio Code. O Databricks não recomenda essa opção.

Para executar ou depurar um bloco de anotações Python Jupyter (.ipynb):

  1. Em seu projeto de código, abra o bloco de anotações Python Jupyter que você deseja executar ou depurar. Verifique se o arquivo Python está no formato de notebook Jupyter e tem a extensão .ipynb.

    Gorjeta

    Você pode criar um novo bloco de anotações Python Jupyter executando o >comando Create: New Jupyter Notebook de dentro da Paleta de Comandos.

  2. Clique em Executar Todas as Células para executar todas as células sem depuração, em Executar Célula para executar uma célula correspondente individual sem depuração ou em Executar por Linha para executar uma célula individual linha por linha com depuração limitada, com valores variáveis exibidos no painel Jupyter (Exibir > Jupyter Open View>).

    Para depuração completa dentro de uma célula individual, defina pontos de interrupção e clique em Depurar Célula no menu ao lado do botão Executar da célula.

    Depois de clicar em qualquer uma dessas opções, você pode ser solicitado a instalar dependências ausentes do pacote de notebook Python Jupyter. Clique para instalar.

    Para obter mais informações, consulte Jupyter Notebooks no VS Code.