Desenvolva pipelines Delta Live Tables com pacotes de ativos Databricks

Artigo
10/05/2024

Os Pacotes de Ativos Databricks, também conhecidos simplesmente como pacotes, permitem validar, implantar e executar recursos do Azure Databricks programaticamente, como pipelines Delta Live Tables. Consulte O que são Databricks Asset Bundles?.

Este artigo descreve como criar um pacote para gerenciar programaticamente um pipeline. Consulte O que é Delta Live Tables?. 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 pipeline e trabalho para executá-lo. Em seguida, você valida, implanta e executa o pipeline implantado em seu espaço de trabalho do Azure Databricks.

Gorjeta

Se você tiver pipelines existentes que foram criados usando a interface do usuário ou a API do Azure Databricks 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, blocos de anotações e outras fontes adicionais ao pacote. Consulte Adicionar uma definição de pipeline 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 deve ter arquivos de espaço de trabalho habilitados. Consulte O que são arquivos de espaço de trabalho?.

(Opcional) Instalar um módulo Python para suportar o desenvolvimento de pipeline local

O Databricks fornece um módulo Python para ajudar no desenvolvimento local do código de pipeline Delta Live Tables, fornecendo verificação de sintaxe, preenchimento automático e verificação de tipo de dados enquanto você escreve código no IDE.

O módulo Python para desenvolvimento local está disponível no PyPi. Para instalar o módulo, consulte Python stub for Delta Live Tables.

Criar um pacote usando um modelo de projeto

Crie o pacote usando o modelo de pacote padrão do Azure Databricks para Python. Este modelo consiste em um bloco de anotações que define um pipeline Delta Live Tables, que filtra dados do conjunto de dados original. 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: Criar 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 dentro do seu diretório de trabalho atual.
Para Include a stub (sample) notebook, selecione no e pressione Enter. Isso instrui a CLI do Databricks a não adicionar um bloco de anotações de exemplo neste momento, pois o bloco de anotações de exemplo associado a essa opção não tem nenhum código Delta Live Tables.
Para Include a stub (sample) DLT pipeline, deixe o valor padrão de yes pressionando Enter. Isso instrui a CLI do Databricks a adicionar um bloco de anotações de exemplo que tenha o código Delta Live Tables.
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 pipeline e especifica configurações sobre o espaço de trabalho de destino.
resources/<project-name>_job.yml e resources/<project-name>_pipeline.yml: Esses arquivos definem o trabalho que contém uma tarefa de atualização do pipeline e as configurações do pipeline.
src/dlt_pipeline.ipynb: Este arquivo é um bloco de anotações que, quando executado, executa o pipeline.

Para personalizar pipelines, os mapeamentos dentro de uma declaração de pipeline correspondem à carga útil de solicitação da operação de criação de pipeline, conforme definido em POST /api/2.0/pipelines na referência da API REST, expressa no formato YAML.

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 pipeline Delta Live Tables 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 pipeline foi criado: na barra lateral do seu espaço de trabalho do Azure Databricks, clique em Delta Live Tables.
Na guia Delta Live Tables, clique em [dev <your-username>] <project-name>_pipeline.

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 pipeline Delta Live Tables 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>_pipeline
```
Copie o valor que aparece em seu terminal e cole esse valor em seu navegador da Web para abrir seu espaço de Update URL trabalho do Azure Databricks.
Em seu espaço de trabalho do Azure Databricks, depois que o pipeline for concluído com êxito, clique no modo de exibição taxi_raw e no modo filtered_taxis materializado para ver os detalhes.

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 pipeline do 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 do pipeline: 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 pipeline existente a um pacote

Você pode usar uma definição de pipeline Delta Live Tables existente como base para definir um novo pipeline em um arquivo de configuração de pacote. Para obter uma definição de pipeline existente, você pode recuperá-la manualmente usando a interface do usuário ou gerá-la programaticamente usando a CLI do Databricks.

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

Para obter a representação YAML de uma definição de pipeline 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 Delta Live Tables, clique no link Nome do pipeline.
Ao lado do botão Desenvolvimento , clique no kebab e, em seguida, clique em Exibir configurações YAML.
Copie o YAML da definição de pipeline na caixa de diálogo YAML de configurações de pipeline para a área de transferência local clicando no ícone de cópia.
Adicione o YAML que você copiou para o arquivo do databricks.yml seu pacote ou crie um arquivo de configuração para seu pipeline na pasta do seu projeto de pacote e faça referência a resources ele a partir do seu databricks.yml arquivo. Consulte os recursos.
Transfira e adicione quaisquer ficheiros Python e blocos de notas referenciados à origem 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 pipeline 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:
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      libraries:
        - notebook:
            path: ../src/hello.ipynb
```

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

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

Recupere a ID do pipeline existente no painel lateral Detalhes do pipeline para o pipeline na interface do usuário ou use o comando Databricks CLI databricks pipelines list-pipelines .
Execute o bundle generate pipeline comando Databricks CLI, definindo a ID do pipeline:
```
databricks bundle generate pipeline --existing-pipeline-id 6565621249
```
Este comando cria um arquivo de configuração de pacote para o pipeline 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.

Partilhar via