Desenvolver um trabalho em Databricks usando Databricks ativo Bundles

Databricks ativo Bundles, também conhecidos simplesmente como bundles, contêm os artefatos que o senhor deseja implantar e as configurações de Databricks recurso, como o Job, que deseja executar, e permitem que o senhor os valide, implante e execute de forma programática. Veja o que são Databricks ativo Bundles?

Este artigo descreve como criar um pacote para gerenciar programaticamente um trabalho. Veja programar e orquestrar fluxo de trabalho. O pacote é criado usando o Databricks ativo Bundles default bundle padrão para Python, que consiste em um Notebook emparelhado com a definição de um Job para executá-lo. Em seguida, o senhor valida, implanta e executa o Job implantado em seu site Databricks workspace.

Dica

Se o senhor tiver trabalhos existentes que foram criados usando a interface de usuário Databricks Jobs ou API que deseja mover para pacotes, deverá defini-los nos arquivos de configuração de um pacote. Databricks recomenda que o senhor crie primeiro um pacote usando os passos abaixo e, em seguida, valide se o pacote funciona. Em seguida, o senhor pode adicionar outras definições de trabalho, Notebook e outras fontes ao pacote. Consulte Adicionar uma definição de trabalho existente a um pacote.

Requisitos

Databricks CLI versão 0.218.0 ou acima. Para verificar a versão instalada do Databricks CLI, execute o comando databricks -v. Para instalar a CLI da Databricks, consulte Instalar ou atualizar a CLI da Databricks.
O site remoto Databricks workspace deve ter os arquivos workspace ativados. Consulte O que são arquivos de espaço de trabalho?

Criar um pacote usando um padrão de projeto

Primeiro, crie um pacote usando o Databricks ativo Bundles default Python padrão. Para obter mais informações sobre o padrão bundle, consulte Databricks ativo Bundle project padrão.

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

o passo 1: Configurar a autenticação

Neste passo, o senhor configura a autenticação entre o Databricks CLI em sua máquina de desenvolvimento e o Databricks workspace. Este artigo pressupõe que o senhor deseja usar a autenticação OAuth user-to-machine (U2M) e um perfil de configuração Databricks correspondente denominado DEFAULT para autenticação.

Observação

A autenticação U2M é adequada para experimentar esses passos em tempo real. Para fluxo de trabalho totalmente automatizado, o site Databricks recomenda que o senhor use a autenticação máquina a máquina (M2M) OAuth. Consulte as instruções de configuração da autenticação M2M em Autenticação.

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

No comando a seguir, substitua <workspace-url> pelo URL da instância do seu workspace do Databricks, por exemplo https://1234567890123456.7.gcp.databricks.com.
```
databricks auth login --host <workspace-url>
```
O site Databricks CLI solicita que o senhor salve as informações inseridas como um Databricks perfil de configuração. Pressione Enter para aceitar o nome de perfil sugerido ou insira o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome é substituído pelas informações que o senhor inseriu. O senhor pode usar perfis para alternar rapidamente o contexto de autenticação em vários espaços de trabalho.

Para obter uma lista de todos os 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 log in no workspace do Databricks.
Para visualizar o valor atual do token OAuth de um perfil e o registro de data e 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 juntas para ajudar a CLI do Databricks a encontrar as informações de token OAuth correspondentes corretas.

o passo 2: Inicializar o pacote

Inicialize um pacote usando o padrão default Python bundle project.

Use o terminal ou o prompt do comando para alternar para um diretório em seu computador de desenvolvimento local que conterá o pacote gerado pelo padrão.
Use o endereço Databricks CLI para executar o comando bundle init:
```
databricks bundle init
```
Para Template to use, deixe o valor default de default-python pressionando Enter.
Para Unique name for this project, deixe o valor default de my_project ou digite um valor diferente e pressione Enter. Isso determina o nome do diretório raiz desse pacote. Esse diretório raiz é criado em 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 de amostra do Delta Live Tables em seu pacote.
Para Include a stub (sample) Python package, selecione no e pressione Enter. Isso instrui a CLI da Databricks a não adicionar arquivos de amostra do pacote Python wheel ou instruções de compilação relacionadas ao seu pacote.

o passo 3: Explore o pacote

Para acessar view os arquivos gerados pelo padrão, vá para o diretório raiz do pacote recém-criado. Os arquivos de interesse particular incluem o seguinte:

databricks.yml: Esse arquivo especifica o nome programático do pacote, inclui uma referência à definição do trabalho e especifica as configurações sobre o destino workspace.
resources/<project-name>_job.yml: Esse arquivo especifica as configurações do trabalho, incluindo uma tarefa do default Notebook.
src/notebook.ipynb: Esse arquivo é um exemplo de Notebook que, quando executado, simplesmente inicializa um RDD que contém os números de 1 a 10.

Para personalizar o trabalho, os mapeamentos em uma declaração de trabalho correspondem à carga útil da solicitação, expressa no formato YAML, das operações de criação de trabalho, conforme documentado em POST /api/2.1/Job/create na referência REST API .

Dica

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

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

Neste passo, o senhor verifica se a configuração do pacote é válida.

No diretório raiz, use o endereço Databricks CLI para executar o comando bundle validate, como segue:
```
databricks bundle validate
```
Se um resumo da configuração do pacote for retornado, a validação foi bem-sucedida. Se algum erro for retornado, corrija os erros e repita este passo.

Se o senhor fizer alguma alteração no pacote após esse passo, deverá repetir esse passo para verificar se a configuração do pacote ainda é válida.

o passo 5: implantado o projeto local no remoto workspace

Neste passo, o senhor implantou o Notebook local em seu Databricks workspace remoto e criou o Databricks Job em seu workspace.

Na raiz do pacote, use o endereço Databricks CLI para executar o comando bundle deploy da seguinte forma:
```
databricks bundle deploy -t dev
```
Verifique se o Notebook local foi implantado: Na barra lateral do workspace do Databricks, clique em workspace.
Clique na pasta Users > <your-username> > .bundle > <project-name> > dev > files > src. O Notebook deve estar nessa pasta.
Verifique se o Job foi criado: Na barra lateral do workspace do Databricks, clique em fluxo de trabalho.
No site Jobs tab, clique em [dev <your-username>] <project-name>_job.
Clique na tarefa tab. Deve haver uma tarefa: Notebook.

Se o senhor fizer alguma alteração no pacote após esse passo, deverá repetir os passos 4-5 para verificar se a configuração do pacote ainda é válida e, em seguida, reimplantar o projeto.

o passo 6: execução do projeto implantado

Neste passo, o senhor aciona a execução do Databricks Job em seu workspace a partir da linha de comando.

No diretório raiz, use o endereço Databricks CLI para executar o comando bundle run, como segue, substituindo <project-name> pelo nome do projeto do passo 2:
```
databricks bundle run -t dev <project-name>_job
```
Copie o valor de Run URL que aparece no terminal e cole-o no navegador da Web para abrir o site Databricks workspace. Ver, visualizar e executar um Job criado com um Databricks ativo Bundle
Em seu site Databricks workspace, depois que a tarefa do trabalho for concluída com êxito e mostrar uma barra de título verde, clique na tarefa do trabalho para ver os resultados.

Se o senhor fizer alguma alteração no pacote após esse passo, deverá repetir os passos 4 a 6 para verificar se a configuração do pacote ainda é válida, reimplantar o projeto e executar o projeto reimplantado.

o passo 7: Limpeza

Neste passo, o senhor exclui o Notebook implantado e o Job do seu site workspace.

No diretório raiz, use o endereço Databricks CLI para executar o comando bundle destroy, como segue:
```
databricks bundle destroy -t dev
```
Confirme a solicitação de exclusão do trabalho: Quando solicitado a destruir permanentemente o recurso, 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 o senhor também quiser excluir o pacote da máquina de desenvolvimento, poderá excluir o diretório local do passo 2.

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

O senhor pode usar um Job existente como base para definir um Job em um arquivo de configuração de pacote. Para obter uma definição de trabalho existente, o senhor pode recuperá-la manualmente usando a interface do usuário ou pode gerá-la programaticamente usando o site Databricks CLI.

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

Obter uma definição de trabalho existente usando a UI

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

Na barra lateral do site Databricks workspace , clique em fluxo de trabalho.
No site Jobs tab, clique no link Job's Name (Nome do trabalho).
Ao lado do botão Executar agora, clique no botão e, em seguida, clique em Alternar para código (YAML).
Adicione o YAML que o senhor copiou ao arquivo databricks.yml do pacote ou crie um arquivo de configuração para o Job no diretório resources do projeto do pacote e faça referência a ele no arquivo databricks.yml. Consulte (/dev-tools/bundles/settings.md#recurso).
Faça o download e adicione todos os arquivos Python e o Notebook referenciados no trabalho existente à fonte do projeto do pacote. Normalmente, os artefatos do pacote estão no diretório src em um pacote.

Dica

O senhor pode exportar um Notebook existente de um Databricks workspace para o formato .ipynb clicando em File > Export > IPython Notebook na interface do usuário do Databricks Notebook.

Depois de adicionar o Notebook, os arquivos Python e outros artefatos ao pacote, certifique-se de que a definição do trabalho os referencie adequadamente. Por exemplo, para um Notebook chamado hello.ipynb que está 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 o site Databricks CLI

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

Obtenha o ID do trabalho existente no painel lateral de detalhesJob do trabalho na interface do usuário de trabalhos ou use o comando Databricks CLI databricks jobs list.
executar o bundle generate job Databricks CLI comando, definindo 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 downloads todos os artefatos referenciados na pasta src.

Dica

Se o senhor usar bundle deployment bind pela primeira vez para vincular um recurso em um pacote a um recurso no site workspace, o recurso no site workspace será atualizado com base na configuração definida no pacote ao qual está vinculado após o próximo bundle deploy. Para obter informações sobre bundle deployment bind, consulte Bind bundle recurso.