Desenvolver um trabalho no Azure Databricks usando Databricks Asset Bundles

Artigo
10/14/2024

Os Databricks Asset Bundles, também conhecidos simplesmente como pacotes, contêm os artefatos para implantação e as configurações dos recursos do Azure Databricks, como trabalhos que serão executados, que podem ser validados, implantados e executados programaticamente. Veja que são pacotes de ativos do Databricks?.

Este artigo descreve como criar um pacote para gerenciar um trabalho de maneira programática. Confira Programar e orquestrar fluxos de trabalho. 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 trabalho para executá-lo. Em seguida, você valida, implanta e executa o trabalho implantado em seu workspace do Azure Databricks.

Dica

Se houver trabalhos que foram criados usando a interface do usuário ou a API de trabalhos do Azure Databricks que você deseja mover para pacotes, é necessário defini-los em arquivos de configuração de 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 ao pacote. Consulte Adicionar uma definição de trabalho existente a um pacote.

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.
O workspace do Databricks remoto deve ter arquivos de espaço de trabalho habilitados. Consulte O que são Arquivos de workspace?.

Criar um pacote usando um modelo de projeto

Primeiro, crie um pacote usando o modelo padrão de Databricks Asset Bundles para Python. Para obter informações sobre modelos de pacote, veja Modelos de Pacote de Ativos do Databricks.

Para criar um pacote do zero, confira 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. Veja as instruções de configuração da autenticação M2M em Autenticação.

Use a CLI do Databricks para iniciar o gerenciamento de token OAuth localmente executando 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>
```
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 visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.
No seu navegador da Web, complete as instruções na tela para iniciar sessão no seu workspace do Azure Databricks.
Para visualizar 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.

Use seu terminal ou prompt de comando para alternar para um diretório em seu computador de desenvolvimento local que conterá o pacote gerado do modelo.
Use a CLI do Databricks para realizar a execução do comando bundle init:
```
databricks bundle init
```
Para Template to use, deixe o valor padrão default-python pressionando Enter.
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.
Para Include a stub (sample) notebook, selecionar yes e pressionar Enter.
Para Include a stub (sample) DLT pipeline, selecionar no e pressionar Enter. Isso instrui a CLI do Databricks a não definir um pipeline de tabelas dinâmicas delta de exemplo em seu pacote.
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 trabalho e especifica as configurações sobre o workspace de destino.
resources/<project-name>_job.yml: esse arquivo especifica as configurações do trabalho, incluindo uma tarefa de notebook padrão.
src/notebook.ipynb: esse arquivo é um notebook de exemplo que, quando executado, apenas inicializa um RDD que contém os números de 1 a 10.

Para personalizar trabalhos, os mapeamentos em uma declaração de trabalho correspondem ao payload de solicitação, expresso em YAML, da operação de criação de trabalho, conforme documentado em POST /api/2.1/jobs/create na referência da API REST.

Dica

Você pode definir, combinar e substituir as configurações de novos clusters de trabalho em pacotes usando as técnicas descritas nas configurações de cluster de substituição nos Pacotes de Ativos do Databricks.

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

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

No diretório raiz, use a CLI do Databricks para executar o comando bundle validate, da seguinte maneira:
```
databricks bundle validate
```
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 workspace remoto do Azure Databricks e criará o trabalho do Azure Databricks em seu workspace.

Na raiz do pacote, use a CLI do Databricks para executar o comando bundle deploy, da seguinte maneira:
```
databricks bundle deploy -t dev
```
Verifique se o notebook local foi implantado: na barra lateral do workspace do Azure Databricks, clique em Workspace.
Clique até chegar na pasta Usuários ><your-username>> .pacote ><project-name>> desenvolvimento > arquivos > src. O notebook deve estar nessa pasta.
Verifique se o trabalho foi criado: na barra lateral do espaço de trabalho do Azure Databricks, clique em Fluxos de trabalho.
Na guia Trabalhos, clique em [desenvolvimento <your-username>] <project-name>_job.
Clique na guia Tarefas. Deve haver uma tarefa: 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 projeto implantado

Nesta etapa, você aciona a execução do trabalho do Azure Databricks em seu workspace usando a linha de comando.

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>_job
```
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. Confira Visualizar e executar um trabalho criado com um Pacote de Ativos do Databricks.
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: limpar

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

No diretório raiz, use a CLI do Databricks para executar o comando bundle destroy, da seguinte maneira:
```
databricks bundle destroy -t dev
```
Confirme a solicitação de exclusão de trabalho: quando solicitado a destruir recursos permanentemente, digite y e pressione Enter.
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.
Se você também quiser excluir o pacote do computador de desenvolvimento, agora poderá excluir o diretório local da Etapa 2.

Adicionar uma definição de trabalho existente a um pacote

Você pode usar um trabalho existente como base para definir um trabalho em um arquivo de configuração de pacote. Para obter uma definição de trabalho existente, recupere-a manualmente usando a interface do usuário ou gere-a programaticamente usando a CLI do Databricks.

Para obter informações sobre a definição de trabalho em pacotes, confira trabalho.

Obter uma definição de trabalho existente usando a interface do usuário

Para obter a representação YAML da definição de trabalho existente na interface do usuário do workspace do Azure Databricks:

Na barra lateral do espaço de trabalho do Azure Databricks, clique em Workflows.
Na guia Trabalhos, clique no link Nome do trabalho.
Ao lado do botão Executar agora, selecione o menu kebab e, em seguida, selecione Alternar para código (YAML).
Adicione ao arquivo databricks.yml do pacote configurável o YAML que você copiou ou crie um arquivo de configuração para seu trabalho no diretório resources do projeto do pacote configurável e faça referência a ele no arquivo databricks.yml. Confira (/dev-tools/bundles/settings.md#resources).
Baixe e adicione à origem do projeto do pacote todos os arquivos e notebooks do Python referenciados no trabalho. Normalmente, os artefatos de pacote estão no diretório src em um pacote.

Dica

É possível exportar um notebook existente de um workspace do Azure Databricks para o formato .ipynb selecionando Arquivo > Exportar > IPython Notebook da interface do usuário de notebook do Azure Databricks.

Depois de adicionar seus notebooks, arquivos Python e outros artefatos ao pacote, verifique se a definição do trabalho faz a referência correta a eles. Por exemplo, para um notebook chamado hello.ipynb no diretório src do pacote:
```
resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
      - task_key: hello-task
        notebook_task:
          notebook_path: ../src/hello.ipynb
```

Gerar uma definição de trabalho existente usando a CLI do Databricks

Para gerar programaticamente a configuração do pacote para um trabalho existente:

Recupere a ID do trabalho existente no painel lateral Detalhes do trabalho para o trabalho na interface do usuário de trabalhos ou use o comando databricks jobs list na CLI do Databricks.
Use o comando bundle generate job na CLI do Databricks, configurando o ID do trabalho:
```
databricks bundle generate job --existing-job-id 6565621249
```
Esse comando cria um arquivo de configuração de pacote para o trabalho na pasta resources do pacote e faz download de todos os artefatos referenciados para a pasta src.

Dica

Quando você usa bundle deployment bind pela primeira vez para associar um recurso em um pacote a outro no workspace, o recurso no workspace é atualizado com base na configuração definida no pacote ao qual ele está associado após o próximo bundle deploy. Para obter informações sobre bundle deployment bind, confira Associar recursos de pacote.

Configurar um trabalho que usa computação sem servidor

Os exemplos a seguir demonstram configurações de pacote para criar um trabalho que usa computação sem servidor.

Para usar a computação sem servidor para executar um trabalho que inclui tarefas de notebook, omita a configuração job_clusters do arquivo de configuração do pacote.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job-serverless:
      name: retrieve-filter-baby-names-job-serverless
      tasks:
        - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./filter-baby-names.py

  targets:
    development:
      workspace:
        host: <workspace-url>

Para usar a computação sem servidor para executar um trabalho que inclui tarefas do Python, inclua a configuração environments.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: serverless-python-tasks

resources:
jobs:
  serverless-python-job:
    name: serverless-job-with-python-tasks

    tasks:
      - task_key: wheel-task-1
        python_wheel_task:
          entry_point: main
          package_name: wheel_package
        environment_key: Default

    environments:
      - environment_key: Default
        spec:
          client: "1"
          dependencies:
            - workflows_authoring_toolkit==0.0.1

targets:
  development:
    workspace:
      host: <workspace-url>

Confira Executar seu trabalho do Azure Databricks com computação sem servidor para fluxos de trabalho.

Compartilhar via