Pular para o conteúdo principal
Última atualização em

Desenvolva um pipeline com pacotes de automação declarativa.

Os Declarative Automation Bundles (anteriormente conhecidos como Databricks Asset Bundles) permitem validar, implantar e executar programaticamente recursos do Databricks, como Lakeflow Pipelines. Consulte O que são Declarative Automation Bundles?.

Esta página descreve como criar um pacote para gerenciar programaticamente um pipeline. See Spark Declarative Pipelines. O pacote é criado usando a CLI do Databricks pipelines init comando, que define um pipeline ETL e um Job para executá-lo. Você então valida, implanta e executa o pipeline implantado no seu Workspace Databricks em compute serverless.

dica

Se você já possui pipelines criados usando a interface de usuário ou API Databricks e deseja migrá-los para bundles, você deve defini-los nos arquivos de configuração do bundle. A Databricks recomenda que você primeiro crie um pacote seguindo os passos abaixo e, em seguida, adicione a configuração e outras fontes ao pacote. Consulte Recuperar uma definição de pipeline existente usando a interface do usuário.

Requisitos​

  • Databricks CLI versão 0.283.0 ou acima. Para verificar a versão instalada do Databricks CLI, execute o comando databricks -v. Para instalar a CLI do Databricks, consulte Instalar ou atualizar a CLI do Databricks.
  • O uv é necessário para executar testes e instalar as dependências deste projeto a partir de uma IDE.
  • O site workspace remoto deve ter os arquivos workspace ativados. Consulte O que são arquivos workspace?
  • Um catálogo existente para tabelas em pipeline. Consulte Criar catálogos.

(Opcional) Instale um módulo Python para dar suporte ao desenvolvimento do pipeline local​

A Databricks fornece um módulo Python para auxiliar o desenvolvimento local do código dos Lakeflow pipelines, fornecendo verificação de sintaxe, preenchimento automático e verificação de tipo de dados enquanto você escreve código em sua IDE.

O módulo Python para desenvolvimento local está disponível no PyPi. Para instalar o módulo, consulte o stub do Python para DLT.

Etapa 1: configurar a autenticação​

Primeiro, configure a autenticação entre a CLI Databricks em sua máquina de desenvolvimento e seu workspace Databricks . Esta página pressupõe que você queira usar a autenticação OAuth de usuário para máquina (U2M) e um perfil de configuração Databricks correspondente chamado DEFAULT para autenticação.

nota

A autenticação U2M é adequada para testar essas etapas em tempo real. Para fluxo de trabalho totalmente automatizado, o site Databricks recomenda que o senhor use a autenticação máquina a máquina (M2M) OAuth. Consulte as instruções de configuração da autenticação M2M em Autorize o acesso da entidade de serviço a Databricks com OAuth.

  1. Use o comando Databricks CLI para iniciar o gerenciamento de tokens OAuth localmente, executando o seguinte comando para cada destino workspace.

    No comando a seguir, substitua <workspace-url> pelo Databricks workspace URL da instância, por https://dbc-a1b2345c-d6e7.cloud.databricks.com exemplo,.

    Bash
    databricks auth login --host <workspace-url>

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

    Para obter uma lista de todos os perfis existentes, em um terminal separado ou prompt de comando, use o Databricks CLI para executar o comando databricks auth profiles. Para view 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 log in no workspace do Databricks.

  4. Para view o valor atual dos tokens OAuth de um perfil e o carimbo de data/hora da próxima expiração dos tokens, 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 você tiver vários perfis com o mesmo valor --host, talvez seja necessário especificar as opções --host e -p juntas para ajudar a CLI do Databricks a encontrar as informações de token OAuth correspondentes corretas.

Etapa 2: criar o pacote​

Inicialize um pacote com um pipeline:

  1. Use o terminal ou o prompt do comando para alternar para um diretório em seu computador de desenvolvimento local que conterá o pacote gerado pelo padrão.

  2. Use o endereço Databricks CLI para executar o comando pipelines init:

    Bash
    databricks pipelines init

  3. Para Unique name for this project, deixe o valor default de my_pipeline_project ou digite um valor diferente e pressione Enter. Isso determina o nome do diretório raiz desse pacote. Esse diretório raiz é criado dentro do seu diretório de trabalho atual.

  4. Para Initial catalog, insira o nome de um catálogo existente do Unity Catalog.

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

  6. Para Initial language for this project, selecione python.

Etapa 3: explore o pacote​

Para view os arquivos gerados pelo padrão, acesse o diretório raiz do seu pacote recém-criado. A seguinte estrutura é criada por default:

my_pipeline_project
├── databricks.yml
├── pyproject.toml
├── README.md
├── resources
│   ├── my_pipeline_project_etl.pipeline.yml
│   └── sample_job.job.yml
└── src
    └── my_pipeline_project_etl
        ├── explorations
        │   └── sample_exploration.ipynb
        ├── README.md
        └── transformations
            ├── sample_trips_my_pipeline_project.py
            └── sample_zones_my_pipeline_project.py

Os arquivos de particular interesse incluem os seguintes:

  • databricks.ymlEste 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 as configurações para o espaço de trabalho de destino.

  • resources/sample_job.job.yml e resources/<project-name>_etl_pipeline.yml: Esses arquivos definem o Job que contém uma tarefa refresh pipeline e as configurações do pipeline. Para obter informações sobre configurações pipeline , consulte pipeline.

  • src/Esta pasta contém os arquivos de origem, explorações e transformações do pipeline de exemplo.

dica

Se você adicionar testes, use pytest para executá-los localmente:

Bash
uv run pytest
  • README.md: Este arquivo contém informações adicionais sobre como começar e usar este pacote padrão.

o passo 4: Validar a configuração do pacote​

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

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

    Bash
    databricks bundle validate

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

o passo 5: implantar o pipeline no workspaceremoto​

Em seguida, implante o pacote no seu workspace remoto Databricks e verifique o pipeline no seu workspace.

  1. A partir da raiz do pacote, use um comando da CLI do Databricks deploy :

    Bash
    databricks bundle deploy --target dev

    Ou:

    Bash
    databricks pipelines deploy --target dev
nota

O padrão default inclui um Job que executa o pipeline todos os dias, mas isso é pausa para o modo de implantação de destino dev . Consulte os modos de implantação dos Declarative Automation Bundles.

  1. Confirme se o pacote foi implantado:

    1. Na barra lateral do seu workspace Databricks , clique em espaço de trabalho .
    2. Clique na pasta Users > <your-username> > .bundle e encontre seu projeto de pacote.

  2. Verifique se o pipeline foi criado:

    1. Na barra lateral do site Databricks workspace, clique em Jobs & pipeline .
    2. Opcionalmente, selecione os filtros pipeline e Owned by me .
    3. Clique em [dev <your-username>] <project-name>_etl .

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

o passo 6: execução do pipelineimplantado​

Agora, inicie a execução do pipeline em seu workspace a partir da linha de comando.

  1. A partir do diretório raiz, use o comando Databricks CLI pipelines run . Se houver apenas um pipeline no projeto, não é necessário especificar um nome pipeline .

    Bash
    databricks pipelines run my_pipeline_project_etl --target dev

  2. Copie o valor de Update URL que aparece no terminal e cole-o no navegador da Web para abrir o site Databricks workspace.

  3. No seu workspace Databricks , após a conclusão bem-sucedida da execução pipeline , clique na visualização materializada para ver os detalhes de cada view.

Se fizer alguma alteração no pacote após essa etapa, repita as etapas de 4 a 6 para verificar se a configuração do pacote ainda é válida, reimplante o projeto e execute o projeto reimplantado.

o passo 7: História de saída e logsde eventos​

As informações fornecidas pelos comandos pipelines history e pipelines logs podem ajudar a diagnosticar falhas.

Para recuperar a execução anterior do pipeline:

Bash
databricks pipelines history my_pipeline_project_etl
Output
Updates Summary for pipeline my_pipeline_project_etl:
Update ID: a62293ec-8a63-43b7-8629-b218d56dac7c
   State: COMPLETED
   Cause: API_CALL
   Creation Time: 2026-01-29T23:16:14Z
   Full Refresh: false
   Validate Only: false

Para gerar a saída (em JSON) dos eventos da atualização mais recente do pipeline:

Bash
databricks pipelines logs my_pipeline_project_etl

Use jq para filtrar os resultados. Consulte Filtrar saída JSON com jq.

o passo 8: Limpar​

Neste passo, você exclui o pacote implantado e o pipeline do seu workspace.

  1. A partir do diretório raiz, use a CLI Databricks para executar o comando pipelines destroy :

    Bash
    databricks pipelines destroy --target dev

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

  3. Se você também quiser excluir o pacote do seu computador de desenvolvimento, agora pode excluir o diretório local do projeto.

Nesta página