Compartilhar via

Desenvolver pipelines declarativos do Lakeflow com pacotes de ativos do Databricks

Os Pacotes de Ativos do Databricks, também conhecidos simplesmente como pacotes, permitem que você valide, implante e execute programaticamente recursos do Azure Databricks, como o Lakeflow Declarative Pipelines. Veja o que são pacotes de ativos do Databricks?.

Este artigo descreve como criar um pacote para gerenciar um pipeline de maneira programática. Consulte Pipelines Declarativos do Lakeflow. O pacote é criado usando o modelo padrão de Databricks Asset Bundles para Python, que consiste em um notebook 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 workspace do Azure Databricks.

Dica

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, você deverá defini-los nos arquivos de configuração de um pacote. O Databricks recomenda que primeiro você crie um pacote seguindo as etapas abaixo e valide se o pacote funciona. Em seguida, você pode adicionar definições de trabalho, notebooks e outras fontes extras ao pacote. Veja Recuperar uma definição de pipeline existente usando a interface do usuário.

Requisitos

(Opcional) Instalar um módulo Python para dar suporte ao desenvolvimento de pipeline local

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

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

Criar um pacote usando um modelo de projeto

Crie o pacote usando o modelo de pacote padrão do Azure Databricks para Python. Esse modelo consiste em um notebook que define um pipeline ETL (usando Pipelines Declarativos do Lakeflow), que filtra os dados do conjunto de dados original. Para obter mais informações sobre modelos de pacote, consulte os modelos de projeto do Pacote de Ativos do Databricks.

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 workspace do Azure Databricks. Esse artigo pressupõe que você deseja usar a autenticação U2M (usuário para computador) do OAuth e um perfil de configuração correspondente do Azure Databricks chamado DEFAULT para autenticação.

Observação

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

  1. Use o CLI do Databricks para iniciar o gerenciamento de tokens OAuth executando localmente o comando a seguir para cada workspace de destino.

    No comando a seguir, substitua <workspace-url> pela URL por workspace 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 será substituído pelas informações inseridas. Você pode usar perfis para alternar rapidamente seu contexto de autenticação em vários workspaces.

    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 exibir as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

  3. No seu navegador da Web, complete as instruções na tela para iniciar sessão no seu workspace 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 você tiver vários perfis com o mesmo valor --host, talvez seja necessário especificar as opções --host e -p em conjunto para ajudar a CLI do Databricks a encontrar as informações de token OAuth correspondentes corretas.

Etapa 2: criar o pacote

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

  1. Use seu terminal ou prompt de comando para navegar até um diretório no seu equipamento de desenvolvimento local contendo o conjunto gerado pelo modelo.

  2. Use a CLI do Databricks para realizar a execução do comando bundle init:

    databricks bundle init

  3. Para Template to use, deixe o valor padrão 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 esse pacote. Esse diretório raiz é criado no diretório de trabalho atual.

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

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

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

Etapa 3: explorar o pacote

Para visualizar os arquivos gerados pelo modelo, alterne para o diretório raiz do pacote recém-criado. Os arquivos de interesse específico incluem o seguinte:

  • databricks.yml: este arquivo especifica o nome programático do pacote, inclui uma referência à definição do pipeline e especifica as configurações sobre o workspace 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 de pipeline e as configurações do pipeline.
  • src/dlt_pipeline.ipynb: arquivo que é um notebook que, quando executado, executa o pipeline.

Para personalizar pipelines, os mapeamentos em uma declaração de pipeline correspondem ao payload 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, expressos em formato YAML.

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

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

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

    databricks bundle validate

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

Se você fizer quaisquer alterações em seu pacote após essa etapa, deverá repetir essa etapa para verificar se a configuração do pacote ainda é válida.

Etapa 5: implantar o projeto local no workspace remoto

Nesta etapa, você implantará o notebook local no seu workspace remoto do Azure Databricks e criará o pipeline nele.

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

    databricks bundle deploy -t dev

  2. Verifique se o notebook local foi implantado: na barra lateral do workspace do Azure Databricks, clique em Workspace.

  3. Clique na pasta Usuários ><your-username>> .pacote ><project-name>> desenvolvimento > arquivos > src. O notebook deve estar nessa pasta.

  4. Verifique se o pipeline foi criado:

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

Se você fizer todas as alterações em seu pacote após esta etapa, deverá repetir 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, você inicia uma execução do pipeline em sua área de trabalho na linha de comando.

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

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

  2. Copie o valor de Update URL que aparece em seu terminal e cole esse valor em seu navegador da Web para abrir seu workspace do Azure Databricks.

  3. No workspace do Azure Databricks, depois que o pipeline for concluído com sucesso, clique na exibição taxi_raw e na exibição materializada filtered_taxis para ver os detalhes.

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

Etapa 7: limpar

Nesta etapa, você exclui o notebook implantado e o pipeline de sua área de trabalho.

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

    databricks bundle destroy -t dev

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

  3. Confirme a solicitação de exclusão do notebook: 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 do computador de desenvolvimento, agora poderá excluir o diretório local da Etapa 2.