Desenvolva um trabalho com o Databricks Asset Bundles

Os Pacotes de Ativos do Databricks, também conhecidos simplesmente como pacotes, contêm os artefatos que você deseja implantar e as configurações dos recursos do Azure Databricks, como trabalhos que você deseja executar, e permitem validá-los, implantá-los e executá-los programaticamente. Consulte O que são Databricks Asset Bundles?.

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

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

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.
• uv é necessário para executar testes e instalar dependências para este projeto a partir de um IDE.
• O espaço de trabalho Databricks remoto deve ter os arquivos de espaço de trabalho configurados. Consulte O que são arquivos de espaço de trabalho?.
• Um catálogo existente. Para criar um catálogo, consulte Criar catálogos.

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 pela URL por espaço de trabalho do Azure Databricks , por exemplo .

   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, poderá ser necessário especificar juntas as opções --host e -p para ajudar a CLI do Databricks a encontrar as informações corretas do token OAuth.

Etapa 2: Inicializar 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 no seu diretório de trabalho atual.

5. Para Include a job that runs a notebook, selecione yes e pressione Enter.

6. Para Include an ETL pipeline, selecione no e pressione Enter.

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.job.yml: Este arquivo especifica as configurações do trabalho, incluindo uma tarefa padrão do bloco de anotações. Para obter informações sobre configurações de trabalho, consulte trabalho.
• src/: Esta pasta contém os arquivos de origem do trabalho.
• src/sample_notebook.ipynb: Este bloco de notas lê uma tabela de exemplo.
• tests/: Esta pasta contém exemplos de testes de unidade.
• 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 trabalho em seu espaço de trabalho remoto do Azure Databricks e verifique o trabalho 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
   

2. Confirme se o bloco de anotações 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 Users ><your-username>>.bundle><project-name>> dev > files > src. O bloco de notas deve estar nesta pasta.

3. Verifique se o trabalho foi criado:

   1. Na barra lateral do espaço de trabalho do Azure Databricks, clique em Trabalhos & Pipelines.
   2. Opcionalmente, selecione os filtros Trabalhos e Propriedade de mim .
   3. Clique em [dev <your-username>] sample_job.
   4. Clique na guia Tarefas . Deve haver uma notebook_task.

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 trabalho implantado

Agora, inicie uma execução da tarefa no seu espaço de trabalho pela linha de comandos.

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

   databricks bundle run --target dev sample_job
   

2. Copie o valor de Run URL que aparece no seu terminal e cole esse valor no seu navegador web para abrir o seu espaço de trabalho do Azure Databricks. Consulte Exibir e executar um trabalho criado com o Databricks Asset Bundles

3. No seu espaço de trabalho do Azure Databricks, depois que a tarefa for concluída com êxito e mostrar uma barra de título verde, clique na tarefa para ver os resultados.

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 bloco de anotações implantado e o trabalho 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 excluir permanentemente todos os arquivos e diretórios do espaço de trabalho, 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.