Partilhar via

Desenvolva pipelines descritivos do Lakeflow utilizando pacotes de recursos do Databricks.

Os Databricks Asset Bundles, também conhecidos simplesmente como bundles, permitem validar, implantar e executar recursos do Azure Databricks programaticamente, como Lakeflow Declarative Pipelines. Consulte O que são Databricks Asset Bundles?.

Este artigo descreve como criar um pacote para gerenciar programaticamente um pipeline. Consulte Lakeflow Declarative Pipelines. O pacote é criado usando o modelo de pacote padrão Databricks Asset Bundles para Python, que consiste em um bloco de anotações emparelhado com a definição de um pipeline e trabalho para executá-lo. Em seguida, você valida, implanta e executa o pipeline implantado em seu espaço de trabalho do Azure Databricks.

Gorjeta

Se você tiver pipelines existentes que foram criados usando a interface do usuário ou a API do Azure Databricks que deseja mover para pacotes, deverá defini-los nos arquivos de configuração de um pacote. O Databricks recomenda que você primeiro crie um pacote usando as etapas abaixo e, em seguida, valide se o pacote funciona. Em seguida, você pode adicionar definições, blocos de anotações e outras fontes adicionais ao pacote. Consulte Recuperar uma definição de pipeline existente usando a interface do usuário.

Requisitos

  • Databricks CLI versão 0.218.0 ou superior. Para verificar a versão instalada da CLI do Databricks, execute o comando databricks -v. Para instalar a CLI do Databricks, consulte Instalar ou atualizar a CLI do Databricks.
  • O espaço de trabalho remoto deve ter arquivos de espaço de trabalho ativados. Consulte O que são arquivos de espaço de trabalho?.

(Opcional) Instalar um módulo Python para suportar o desenvolvimento de pipeline local

O Databricks fornece um módulo Python para ajudar no desenvolvimento local do código Lakeflow Declarative Pipelines, fornecendo verificação de sintaxe, preenchimento automático e verificação de tipo de dados enquanto você escreve código no IDE.

O módulo Python para desenvolvimento local está disponível no PyPi. Para instalar o módulo, consulte Python stub for Lakeflow Declarative Pipelines.

Criar um pacote usando um modelo de projeto

Crie o pacote usando o modelo de pacote padrão do Azure Databricks para Python. Este modelo consiste em um bloco de anotações que define um pipeline ETL (usando Lakeflow Declarative Pipelines), que filtra dados do conjunto de dados original. Para obter mais informações sobre modelos de pacote, consulte Modelos de projeto do Databricks Asset Bundle.

Se você quiser criar um pacote do zero, consulte Criar um pacote manualmente.

Etapa 1: configurar a autenticação

Nesta etapa, você configura a autenticação entre a CLI do Databricks em sua máquina de desenvolvimento e seu espaço de trabalho do Azure Databricks. Este artigo pressupõe que você deseja usar a autenticação de usuário para máquina (U2M) OAuth e um perfil de configuração do Azure Databricks correspondente nomeado DEFAULT para autenticação.

Nota

A autenticação U2M é apropriada para experimentar essas etapas em tempo real. Para fluxos de trabalho totalmente automatizados, a Databricks recomenda que utilize a autenticação OAuth máquina-a-máquina (M2M). Consulte as instruções de configuração de autenticação M2M em Autorizar acesso não assistido aos recursos do Azure Databricks com uma entidade de serviço usando OAuth.

  1. Use a CLI do Databricks para iniciar o gerenciamento de token OAuth localmente executando o seguinte comando para cada espaço de trabalho de destino.

    No comando a seguir, substitua <workspace-url> pela URL por espaço de trabalho do Azure Databricks, por exemplo https://adb-1234567890123456.7.azuredatabricks.net.

    databricks auth login --host <workspace-url>

  2. A CLI do Databricks solicita que você salve as informações inseridas como um perfil de configuração do Azure Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou digite o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome é substituído pelas informações que você inseriu. Você pode usar perfis para alternar rapidamente seu contexto de autenticação em vários espaços de trabalho.

    Para obter uma lista de quaisquer perfis existentes, em um terminal ou prompt de comando separado, use a CLI do Databricks para executar o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

  3. No navegador da Web, conclua as instruções na tela para fazer logon no espaço de trabalho do Azure Databricks.

  4. Para exibir o valor atual do token OAuth de um perfil e o carimbo de data/hora de expiração do token, execute um dos seguintes comandos:

    • databricks auth token --host <workspace-url>
    • databricks auth token -p <profile-name>
    • databricks auth token --host <workspace-url> -p <profile-name>

    Se tiver vários perfis com o mesmo --host valor, talvez seja necessário especificar --host e -p em conjunto para ajudar a CLI do Databricks a encontrar a informação correta do token OAuth.

Etapa 2: Criar o pacote

Inicialize um pacote usando o modelo de projeto de pacote Python padrão.

Nota

O modelo default-python requer que uv esteja instalado. Consulte Instalação do uv.

  1. Utilize o terminal para aceder a um diretório na máquina de desenvolvimento local que irá conter o pacote gerado pelo modelo.

  2. Use a CLI do Databricks para executar o bundle init comando:

    databricks bundle init

  3. Para Template to use, deixe o valor padrão de default-python pressionando Enter.

  4. Para Unique name for this project, deixe o valor padrão de my_project, ou digite um valor diferente e pressione Enter. Isso determina o nome do diretório raiz para este pacote. Este diretório raiz é criado dentro do seu diretório de trabalho atual.

  5. Para Include a stub (sample) notebook, selecione no e pressione Enter. Isso instrui a CLI do Databricks a não adicionar um bloco de anotações de exemplo neste momento, pois o bloco de anotações de exemplo associado a essa opção não tem nenhum código Lakeflow Declarative Pipelines.

  6. Para Include a stub (sample) Delta Live Tables pipeline, deixe o valor padrão de yes pressionando Enter. Isso instrui a CLI do Databricks a adicionar um bloco de anotações de exemplo que tenha o código Lakeflow Declarative Pipelines.

  7. Para Include a stub (sample) Python package, selecione no e pressione Enter. Isso instrui a CLI do Databricks a não adicionar arquivos de pacote de exemplo do Python (wheel) ou instruções de compilação relacionadas ao seu conjunto.

  8. Para Use serverless, selecione yes e pressione Enter. Isso instrui a CLI do Databricks a configurar seu pacote para ser executado em computação sem servidor.

Passo 3: Explore o pacote

Para exibir os arquivos que o modelo gerou, alterne para o diretório raiz do pacote recém-criado. Os ficheiros de particular interesse incluem o seguinte:

  • databricks.yml: Este arquivo especifica o nome programático do pacote, inclui uma referência à definição de pipeline e especifica configurações sobre o espaço de trabalho de destino.
  • resources/<project-name>_job.yml e resources/<project-name>_pipeline.yml: Esses arquivos definem o trabalho que contém uma tarefa de atualização do pipeline e as configurações do pipeline.
  • src/dlt_pipeline.ipynb: Este arquivo é um bloco de anotações que, quando executado, executa o pipeline.

Para personalizar pipelines, os mapeamentos dentro de uma declaração de pipeline correspondem à carga útil de solicitação da operação de criação de pipeline, conforme definido em POST /api/2.0/pipelines na referência da API REST, expressa no formato YAML.

Etapa 4: Validar o arquivo de configuração do pacote do projeto

Nesta etapa, você verifica se a configuração do pacote é válida.

  1. No diretório raiz, use a CLI do Databricks para executar o bundle validate comando, da seguinte maneira:

    databricks bundle validate

  2. Se um resumo da configuração do pacote for retornado, a validação será bem-sucedida. Se algum erro for retornado, corrija-os e repita esta etapa.

Se você fizer alguma alteração no pacote após esta etapa, repita esta etapa para verificar se a configuração do pacote ainda é válida.

Etapa 5: Implantar o projeto local no espaço de trabalho remoto

Nesta etapa, você implanta o bloco de anotações local em seu espaço de trabalho remoto do Azure Databricks e cria o pipeline em seu espaço de trabalho.

  1. Na raiz do pacote, utilize a CLI do Databricks para executar o comando bundle deploy da seguinte maneira:

    databricks bundle deploy -t dev

  2. Verifique se o bloco de anotações local foi implantado: na barra lateral do espaço de trabalho do Azure Databricks, clique em Espaço de trabalho.

  3. Aceda à pasta Users ><your-username>> .bundle ><project-name>> dev > files > src. O bloco de notas deve estar nesta pasta.

  4. Verifique se a sua linha de processamento foi criada:

    1. Na barra lateral do espaço de trabalho do Azure Databricks, clique em Trabalhos & Pipelines.
    2. Opcionalmente, selecione os filtros Pipelines e Owned by me .
    3. Clique em [dev <your-username>] <project-name>_pipeline.

Se você fizer alterações no pacote após esta etapa, repita as etapas 4 a 5 para verificar se a configuração do pacote ainda é válida e, em seguida, reimplantar o projeto.

Etapa 6: Executar o projeto implantado

Nesta etapa, desencadeias uma execução do pipeline na tua área de trabalho a partir da linha de comando.

  1. No diretório raiz, use a CLI do Databricks para executar o bundle run comando, da seguinte forma, substituindo <project-name> pelo nome do seu projeto da Etapa 2:

    databricks bundle run -t dev <project-name>_pipeline

  2. Copie o valor de Update URL que aparece no seu terminal e cole-o no seu navegador para abrir o seu espaço de trabalho do Azure Databricks.

  3. No seu espaço de trabalho do Azure Databricks, depois de o pipeline ser concluído com êxito, clique na vista taxi_raw e na vista materializada filtered_taxis para ver os detalhes.

Se você fizer alterações no pacote após esta etapa, repita as etapas 4 a 6 para verificar se a configuração do pacote ainda é válida, reimplantar o projeto e executar o projeto reimplantado.

Passo 7: Limpar

Nesta etapa, você exclui o notebook implantado e o pipeline do espaço de trabalho.

  1. No diretório raiz, use a CLI do Databricks para executar o bundle destroy comando, da seguinte maneira:

    databricks bundle destroy -t dev

  2. Confirme a solicitação de exclusão do pipeline: Quando solicitado a destruir recursos permanentemente, digite y e pressione Enter.

  3. Confirme a solicitação de exclusão do bloco de anotações: Quando solicitado a destruir permanentemente a pasta implantada anteriormente e todos os seus arquivos, digite y e pressione Enter.

  4. Se você também quiser excluir o pacote da sua máquina de desenvolvimento, agora você pode excluir o diretório local da Etapa 2.