Desenvolver um trabalho no Azure Databricks usando Databricks Asset Bundles

Artigo
12/01/2024

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?.

Este artigo descreve como criar um pacote para gerenciar programaticamente um trabalho. Consulte Programar e orquestrar fluxos de trabalho. O pacote é criado usando o modelo de pacote padrão Databricks Asset Bundles para Python, que consiste em um bloco de anotações emparelhado com 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.

Gorjeta

Se você tiver trabalhos existentes que foram criados usando a interface do usuário ou a API do Azure Databricks Jobs que deseja mover para pacotes, deverá defini-los nos arquivos de configuração de um pacote. O Databricks recomenda que você primeiro crie um pacote usando as etapas abaixo e, em seguida, valide se o pacote funciona. Em seguida, você pode adicionar definições de trabalho, blocos de anotações e outras fontes adicionais ao pacote. Consulte Adicionar uma definição de tarefa existente a um pacote.

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

Criar um pacote usando um modelo de projeto

Primeiro, crie um pacote usando o modelo Python padrão do Databricks Asset Bundles. Para obter mais informações sobre modelos de pacote, consulte Modelos de projeto do Databricks Asset Bundle.

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 espaço de trabalho do Azure Databricks. Este artigo 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.

Nota

A autenticação U2M é apropriada para experimentar essas etapas em tempo real. Para fluxos de trabalho totalmente automatizados, o Databricks recomenda que você use a autenticação OAuth máquina-a-máquina (M2M). Consulte 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 seguinte comando para cada espaço de trabalho de destino.

No comando a seguir, substitua <workspace-url> pela URL do Azure Databricks por espaço de trabalho, por exemplohttps://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 é 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>.
No navegador da Web, conclua as instruções na tela para fazer logon no espaço de trabalho do Azure Databricks.
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 --host valor, talvez seja necessário especificar as --host opções e -p juntas 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.

Use seu terminal ou prompt de comando para alternar para um diretório em sua máquina de desenvolvimento local que conterá o pacote gerado pelo modelo.
Use a CLI do Databricks para executar o bundle init comando:
```
databricks bundle init
```
Para Template to use, deixe o valor padrão de 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 este pacote. Este diretório raiz é criado no seu diretório de trabalho atual.
Para Include a stub (sample) notebook, selecione yes e pressione Enter.
Para Include a stub (sample) DLT pipeline, selecione no e pressione Enter. Isso instrui a CLI do Databricks a não definir um pipeline Delta Live Tables de exemplo em seu pacote.
Para Include a stub (sample) Python package, selecione no e pressione Enter. Isso instrui a CLI do Databricks a não adicionar arquivos de pacote de roda Python de exemplo ou instruções de compilação relacionadas ao seu pacote.

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 uma referência à definição de tarefa e especifica configurações sobre o espaço de trabalho de destino.
resources/<project-name>_job.yml: Este arquivo especifica as configurações do trabalho, incluindo uma tarefa padrão do bloco de anotações.
src/notebook.ipynb: Este arquivo é um bloco de anotações de exemplo que, quando executado, simplesmente 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 à carga útil da solicitação, expressa no formato YAML, da operação create job, conforme documentado em POST /api/2.1/jobs/create na referência da API REST.

Gorjeta

Você pode definir, combinar e substituir as configurações de novos clusters de trabalho em pacotes usando as técnicas descritas em Substituir configurações de cluster em Databricks Asset Bundles.

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

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

No diretório raiz, use a CLI do Databricks para executar o bundle validate comando, da seguinte maneira:
```
databricks bundle validate
```
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.

Se você fizer alguma alteração no pacote após esta etapa, repita esta etapa para verificar se a configuração do pacote ainda é válida.

Etapa 5: Implantar o projeto local no espaço de trabalho remoto

Nesta etapa, você implanta o bloco de anotações local em seu espaço de trabalho remoto do Azure Databricks e cria o trabalho do Azure Databricks em seu espaço de trabalho.

Na raiz do pacote, use a CLI do Databricks para executar o bundle deploy comando da seguinte maneira:
```
databricks bundle deploy -t dev
```
Verifique se o bloco de anotações local foi implantado: na barra lateral do espaço de trabalho do Azure Databricks, clique em Espaço de trabalho.
Clique na pasta Users ><your-username>> .bundle><project-name>> dev > files > src. O bloco de notas deve estar nesta pasta.
Verifique se o trabalho foi criado: na barra lateral do seu espaço de trabalho do Azure Databricks, clique em Fluxos de trabalho.
Na guia Trabalhos, clique em [dev <your-username>] <project-name>_job.
Clique na guia Tarefas . Deve haver uma tarefa: 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 projeto implantado

Nesta etapa, você aciona uma execução do trabalho do Azure Databricks em seu espaço de trabalho a partir da linha de comando.

No diretório raiz, use a CLI do Databricks para executar o bundle run comando, da seguinte forma, substituindo <project-name> pelo nome do seu projeto da Etapa 2:
```
databricks bundle run -t dev <project-name>_job
```
Copie o valor que aparece em seu terminal e cole esse valor em seu navegador da Web para abrir seu espaço de Run URL trabalho do Azure Databricks. Consulte Exibir e executar um trabalho criado com um Databricks Asset Bundle
No seu espaço de trabalho 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 de trabalho 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.

Passo 7: Limpar

Nesta etapa, você exclui o bloco de anotações implantado e o trabalho do seu espaço de trabalho.

No diretório raiz, use a CLI do Databricks para executar o bundle destroy comando, 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 bloco de anotações: 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 da sua máquina de desenvolvimento, agora você pode excluir o diretório local da Etapa 2.

Adicionar uma definição de tarefa 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 tarefa existente, você pode recuperá-la manualmente usando a interface do usuário ou gerá-la programaticamente usando a CLI do Databricks.

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

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

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

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

Gorjeta

Você pode exportar um bloco de anotações existente de um espaço de trabalho do Azure Databricks para o .ipynb formato clicando em Arquivo > Exportar > Bloco de Anotações IPython na interface do usuário do bloco de anotações do Azure Databricks.

Depois de adicionar seus blocos de anotações, arquivos Python e outros artefatos ao pacote, certifique-se de que sua definição de trabalho faça referência a eles corretamente. Por exemplo, para um bloco de anotações nomeado hello.ipynb que está no src diretório 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 tarefa 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 na interface do usuário Trabalhos ou use o comando Databricks CLI.databricks jobs list
Execute o bundle generate jobcomando Databricks CLI, definindo a ID do trabalho:
```
databricks bundle generate job --existing-job-id 6565621249
```
Este comando cria um arquivo de configuração de pacote para o trabalho na pasta do resources pacote e baixa todos os artefatos referenciados para a src pasta.

Gorjeta

Se você usar bundle deployment bind pela primeira vez para vincular um recurso em um pacote a um no espaço de trabalho, o recurso no espaço de trabalho será atualizado com base na configuração definida no pacote ao qual ele está vinculado após o próximo bundle deploy. Para obter informações sobre bundle deployment bindo , consulte Vincular recursos do 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 inclua tarefas do bloco de anotações, omita a job_clusters configuração 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 Python, inclua a environments configuração.

# 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>

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

Partilhar via