Desenvolver um trabalho com pacotes de ativos do Databricks

Os Pacotes de Ativos do Databricks, também conhecidos simplesmente como pacotes, contêm os artefatos que você deseja implantar e as configurações para recursos do Azure Databricks, como trabalhos que você deseja executar, e permitem validar, implantar e executá-los programaticamente. Veja que são pacotes de ativos do Databricks?.

Esta página descreve como criar um pacote para gerenciar programaticamente um trabalho. Consulte Trabalhos do Lakeflow. O pacote é criado usando o modelo de pacote padrão de Pacotes de Ativos do Databricks para Python, que consiste em um notebook e na definição de um trabalho para executá-lo. Em seguida, você valida, implanta e executa o trabalho implantado em seu workspace do Azure Databricks.

Para criar um pacote do zero, confira Criar um pacote manualmente.

Requisitos

• CLI do Databricks 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 workspace remoto do Databricks deve ter arquivos de workspace habilitados. Consulte O que são Arquivos de workspace?.
• 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 seu computador de desenvolvimento e seu workspace do Azure Databricks. Esta página pressupõe que você deseja usar a autenticação U2M (usuário para máquina) do 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 local de tokens OAuth utilizando o comando a seguir para cada espaço de trabalho de destino.

   No comando a seguir, substitua <workspace-url> pela URL de cada 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 ver 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: inicializar o pacote

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

1. Use seu terminal ou prompt de comando para alternar para um diretório no seu computador de desenvolvimento local que conterá o pacote gerado do 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 job that runs a notebook, selecionar yes e pressionar Enter.

6. Para Include an ETL pipeline, selecionar no e pressionar Enter.

7. Para Include a stub (sample) Python package, selecionar no e pressionar Enter.

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

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

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

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 referências aos arquivos do pacote, define variáveis de catálogo e esquema e especifica as configurações para workspaces de destino.
• resources/sample_job.job.yml: este arquivo especifica as configurações do trabalho, incluindo uma tarefa de notebook padrão. Para obter informações sobre configurações de trabalho, consulte o trabalho.
• src/: esta pasta contém os arquivos de origem do trabalho.
• src/sample_notebook.ipynb: Este notebook 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, então a validação foi bem-sucedida. Se algum erro for retornado, corrija-os e repita essa etapa.

Etapa 5: Implantar o pacote no workspace remoto

Em seguida, implante o job no espaço de trabalho remoto do Azure Databricks e verifique o job no 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 notebook foi implantado:

   1. Na barra lateral do workspace do Azure Databricks, clique em Workspace.
   2. Clique na pasta Users ><your-username>> .bundle ><project-name>> dev > files > src. O notebook deve estar nessa pasta.

3. Verifique se o trabalho foi criado:

   1. Na barra lateral do workspace do Azure Databricks, clique em Jobs & Pipelines.
   2. Opcionalmente, selecione os filtros Trabalhos e Propriedade minha .
   3. Clique em [dev <your-username>] sample_job.
   4. Clique na guia Tarefas . Deve haver um notebook_task.

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

Agora inicie uma execução da tarefa em seu workspace a partir da linha de comando.

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 em seu terminal e cole esse valor em seu navegador da Web para abrir seu workspace do Azure Databricks. Veja Exibir e executar um trabalho criado com pacotes de ativos do Databricks

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

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: Executar testes

Por fim, use pytest para executar testes localmente:

uv run pytest

Etapa 8: Limpar

Nesta etapa, você exclui o notebook implantado e o trabalho do workspace.

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 workspace, digite y e pressione Enter.

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