Desenvolva pipelines declarativos do Lakeflow Spark com pacotes de ativos Databricks

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

Esta página descreve como criar um pacote para gerenciar programaticamente um pipeline. Veja Lakeflow Spark Declarative Pipelines. O pacote é criado usando o modelo de pacote padrão Databricks Asset Bundles para Python, que define um pipeline ETL e um trabalho para executá-lo. Em seguida, você valida, implanta e executa o pipeline implantado em seu espaço de trabalho do Azure Databricks.

Requisitos

• Databricks CLI versão 0.276.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.
• uv é necessário para executar testes e instalar dependências para este projeto a partir de um IDE.
• 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?.
• Um catálogo existente para tabelas em processamento. Ver Criar catálogos.

(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 Spark 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 DLT.

Etapa 1: configurar a autenticação

Primeiro, configure a autenticação entre a CLI do Databricks em sua máquina de desenvolvimento e seu espaço de trabalho do Azure Databricks. Esta página 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.

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.

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 job that runs a notebook, selecione no e pressione Enter. (O caderno de exemplo associado a esta opção não tem código de pipeline.)

6. Para Include an ETL pipeline, deixe o valor padrão de yes pressionando Enter. Isso adiciona um código de pipeline de exemplo e uma definição de pipeline.

7. Para Include a stub (sample) Python package, selecione no e pressione Enter.

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.

9. Para Default catalog for any tables created by this project [hive_metastore], insira o nome de um catálogo Unity Catalog existente.

10. Para Use a personal schema for each user working on this project., selecione yes.

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 referências aos arquivos do pacote, define variáveis de catálogo e esquema e especifica configurações para espaços de trabalho de destino.
• resources/sample_job.yml e resources/<project-name>_etl_pipeline.yml: Esses arquivos definem o trabalho que contém uma tarefa de atualização do pipeline e as configurações do pipeline. Para obter informações sobre configurações de pipeline, consulte pipeline.
• src/: Esta pasta contém os arquivos de origem, explorações e transformações do pipeline de exemplo.
• tests/ e fixtures/: Essas pastas contêm testes unitários de exemplo para o pipeline e configurações para conjuntos de dados.
• README.md: Este arquivo contém informações adicionais sobre como começar e usar este modelo de pacote.

Etapa 4: Validar a configuração do pacote

Agora verifique se a configuração do pacote é válida.

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

   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.

Etapa 5: Implantar o pacote no espaço de trabalho remoto

Em seguida, implante o pacote em seu espaço de trabalho remoto do Azure Databricks e verifique o pipeline em seu espaço de trabalho.

1. Na raiz do pacote, use a CLI do Databricks para executar o comando bundle deploy:

   databricks bundle deploy --target dev
   

   Nota

   O modelo padrão inclui um trabalho que executa o pipeline todos os dias, mas isso é pausado para o modo de implantação de destino dev . Consulte Modos de implantação do Databricks Asset Bundle.

2. Confirme se o pacote foi implantado:

   1. Na barra lateral do seu espaço de trabalho do Azure Databricks, clique em Espaço de trabalho.
   2. Clique na pasta Usuários ><your-username>>.bundle e localize seu projeto de pacote.

3. 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>_etl.

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 pipeline de dados implantado

Agora acione uma execução do pipeline em seu espaço de trabalho a partir da linha de comando.

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

   databricks bundle run --target dev <project-name>_etl
   

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. Em seu espaço de trabalho do Azure Databricks, depois que a execução do pipeline for concluída com êxito, clique nas exibições materializadas para ver os detalhes de cada exibição.

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.

Etapa 7: Executar testes

Finalmente, use pytest para executar testes localmente:

uv run pytest

Passo 8: Limpar

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

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

   databricks bundle destroy --target dev
   

2. Quando solicitado a destruir permanentemente os recursos, o pipeline e as tabelas e exibições gerenciadas pelo pipeline, digite y e pressione Enter.

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