Gerir aplicações Databricks usando Pacotes de Automação Declarativa

Os aplicativos Databricks permitem criar dados seguros e aplicativos de IA na plataforma Databricks que você pode compartilhar facilmente com os usuários. Pode gerir as implementações das suas aplicações usando Declarative Automation Bundles. Para mais informações sobre aplicações e bundles, consulte Databricks Apps e O que são Declarative Automation Bundles?.

Este artigo guia-o como desenvolver localmente uma aplicação Databricks e depois configurar um bundle para gerir as implementações da aplicação no workspace Databricks usando Declarative Automation Bundles.

databricks bundle init https://github.com/databricks/bundle-examples --template-dir contrib/templates/streamlit-app

Requerimentos

• Seu espaço de trabalho Databricks e ambiente de desenvolvimento local devem atender aos requisitos para aplicativos Databricks. Consulte Configurar seu espaço de trabalho e ambiente de desenvolvimento do Databricks Apps.
• Databricks CLI versão 0.250.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.

Criar um aplicativo localmente

Primeiro, crie um aplicativo Databricks. As aplicações são desenvolvidas em Python utilizando frameworks populares, como o Dash ou o Gradio. Podes construir uma aplicação Databricks localmente do zero, criar uma no espaço de trabalho Databricks e depois sincronizar os ficheiros para a tua máquina local, ou obter uma aplicação de exemplo Databricks no GitHub.

• Para criar um aplicativo do zero:

  1. Siga um tutorial de início rápido para uma estrutura:

     • Traço
     • Flask
     • Gradio
     • Brilhante
     • Streamlit

  2. Adicione um ficheiro app.yaml à raiz do seu projeto para definir como executar a sua aplicação principal de Python. Por exemplo:

     Para um aplicativo Streamlit:

     command: ['streamlit', 'run', 'app.py']
     

     Ou para uma aplicação Dash:

     command: ['python', 'app.py']
     

• Para criar um aplicativo no espaço de trabalho e sincronizá-lo localmente:

  1. Siga os passos em Comece com as Aplicações Databricks para criar uma aplicação na interface.

  2. Crie um diretório local para a aplicação e acesse-o:

     mkdir hello-world-app
     cd hello-world-app
     

  3. Sincronize os arquivos do aplicativo localmente. Você pode copiar o databricks workspace export-dir comando da página de instalação do aplicativo na interface do usuário do espaço de trabalho e executá-lo na linha de comando. Por exemplo:

     databricks workspace export-dir /Workspace/Users/someone@example.com/databricks_apps/hello-world_2025_05_09-17_43/hello-world-app .
     

     Isso baixa os arquivos do aplicativo no diretório do espaço de trabalho para o hello-world-app diretório em sua máquina local.

• Para obter uma aplicação de exemplo Databricks no GitHub:

  1. Clone o repositório GitHub de modelos de aplicações do Databricks :

     git clone https://github.com/databricks/app-templates
     

  2. Escolha um dos aplicativos de exemplo como um projeto de aplicativo simples.

Adicionar um aplicativo existente a um pacote existente

Se você tiver um aplicativo Databricks em seu espaço de trabalho e tiver um pacote existente ao qual deseja adicionar o aplicativo, poderá usar o databricks bundle generate app comando. Este comando gera um arquivo de configuração para o aplicativo e baixa todos os arquivos de código-fonte para o aplicativo, além de adicioná-los ao seu pacote. Por exemplo:

databricks bundle generate app --existing-app-name hello-world-app

Depois de gerar a configuração do aplicativo em seu pacote, use o databricks bundle bind comando para manter o aplicativo no espaço de trabalho e o pacote sincronizado.

Para obter mais informações sobre databricks bundle generate e databricks bundle bind, consulte bundle grupo de comandos.

Desenvolver e depurar o aplicativo localmente

Em seguida, continue desenvolvendo seu aplicativo localmente. Inicie e depure o aplicativo usando o databricks apps run-local comando. Este comando inicia um proxy de aplicativo que é usado para solicitações de proxy para o próprio aplicativo e injeta cabeçalhos necessários relacionados ao aplicativo Databricks.

1. Para instalar todas as dependências, preparar o ambiente virtual e iniciar a aplicação e o depurador, use o comando run-local com as opções --prepare-environment e --debug.

   databricks apps run-local --prepare-environment --debug
   

   Este comando é usado uv para preparar o ambiente virtual e o depurador é baseado em debugpy.

2. Navegue até http://localhost:8001 para visualizar a sua aplicação.

3. Defina pontos de interrupção para depurar a sua aplicação. No Visual Studio Code, instala o depurador Python, depois seleciona Run>Start Debugging e depois Remote Attach.

   O proxy começa na porta 5678, mas você pode configurá-lo usando a --port opção.

Implemente a aplicação no espaço de trabalho

Quando estiver pronto para implantar seu aplicativo no espaço de trabalho, adicione a configuração do pacote que cria o aplicativo e, em seguida, implante o pacote.

1. Crie um arquivo databricks.yml na raiz do seu projeto de aplicativo. A CLI do Databricks reconhece uma pasta com um databricks.yml arquivo em sua raiz como um pacote, o que habilita os comandos de pacote do databricks.

2. Copie e cole o seguinte YAML no arquivo databricks.yml, substituindo os valores de espaço de trabalho e nome de usuário pelos seus próprios.

   bundle:
     name: hello_world_bundle
   
   resources:
     apps:
       hello_world_app:
         name: 'hello-world-app'
         source_code_path: . # This assumes the app source code is at the root of the project.
         description: 'A Databricks app'
   
   targets:
     dev:
       mode: development
       default: true
       workspace:
         host: https://myworkspace.cloud.databricks.com
     prod:
       mode: production
       workspace:
         host: https://myworkspace.cloud.databricks.com
         root_path: /Workspace/Users/someone@example.com/.bundle/${bundle.name}/${bundle.target}
       permissions:
         - user_name: someone@example.com
           level: CAN_MANAGE
   

3. Valide e implante o pacote. Por padrão, isto cria a aplicação e o pacote dev no destino do espaço de trabalho.

   databricks bundle validate
   databricks bundle deploy
   

4. Lançar um bundle não coloca automaticamente a aplicação no ambiente de execução. Para implementar a aplicação, use ou a interface (da página da aplicação no espaço de trabalho Databricks) ou a CLI Databricks (databricks apps deploy). Consulte Implantar um aplicativo Databricks.

5. Use o bundle summary comando para obter informações sobre a aplicação implementada:

   databricks bundle summary
   

   Name: hello_world_bundle
   Target: dev
   Workspace:
     Host: https://myworkspace.cloud.databricks.com
     User: someone@example.com
     Path: /Workspace/Users/someone@example.com/.bundle/hello_world_bundle/dev
   Resources:
     Apps:
       hello_world_app:
         Name: hello-world-app
         URL:  https://myworkspace.cloud.databricks.com/apps/hello-world-app?o=8498204313176880
   

Desenvolver, testar, iterar

Continue a fazer alterações no seu aplicativo localmente e, em seguida, reimplante o pacote para atualizar o aplicativo no espaço de trabalho. Durante os testes, pode querer configurar permissões de utilização para a aplicação para outros utilizadores no seu espaço de trabalho Azure Databricks, o que pode fazer ao especificando permissões:

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'
      permissions:
        - level: CAN_USE
          group_name: users

Para iniciar o aplicativo no espaço de trabalho, execute o aplicativo no pacote especificando a chave de recurso para o aplicativo no comando:

databricks bundle run hello_world_app

Implantar na produção

A Databricks recomenda a utilização de um principal de serviço para autenticação em produção. Quando estiver pronto para disponibilizar a aplicação em produção, atualize a configuração do pacote para usar um principal de serviço e depois implemente o pacote para o seu espaço de trabalho de produção. Para informações sobre princípios de serviço, consulte Princípios de serviço para CI/CD.

Modificar o bundle para usar um principal de serviço

Antes de implementar para produção, configure uma concessão no bundle que conceda permissão a um serviço principal. Pode configurar a autorização quando a aplicação for criada ou quando o pacote for executado.

Para conceder permissão ao principal de serviço quando a aplicação é criada na implementação do bundle, modifique o bundle databricks.yml para definir uma concessão para a app. Utilize uma substituição de bundle para atribuir o principal de serviço:

bundle:
  name: hello_world_bundle

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'

  schemas:
    my_schema:
      name: my_schema
      grants:
        # highlight-next-line
        - principal: '${resources.apps.hello_world_app.service_principal_client_id}'
          privileges:
            - CREATE_TABLE
      catalog_name: main

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://myworkspace.cloud.databricks.com
  prod:
    mode: production
    workspace:
      host: https://myworkspace.cloud.databricks.com
      root_path: /Workspace/Users/someone@example.com/.bundle/${bundle.name}/${bundle.target}
    permissions:
      - user_name: someone@example.com
        level: CAN_MANAGE

Alternativamente, defina um trabalho no bundle que configura uma concessão quando o bundle é executado:

1. Adicione um caderno chamado grant_notebook.ipynb com o seguinte conteúdo numa célula. Substitui <schema-name> por um nome de utilizador de administrador.

   app_service_principal = dbutils.widgets.get("app_service_principal")
   spark.sql(f"GRANT ALL PRIVILEGES ON SCHEMA <schema-name> TO `{app_service_principal}`")
   

2. Defina uma tarefa nos bundles databricks.yml para executar um caderno que conceda permissão ao principal do serviço. Utilize substituições de feixes para atribuir o valor principal do serviço:

   bundle:
     name: hello_world_bundle
   
   resources:
     apps:
       hello_world_app:
         name: 'hello-world-app'
         source_code_path: . # This assumes the app source code is at the root of the project.
         description: 'A Databricks app'
   
     jobs:
       grant_job:
         name: 'grant-job'
         parameters:
           - name: app_service_principal
             # highlight-next-line
             default: '${resources.apps.hello_world_app.service_principal_client_id}'
         tasks:
           - task_key: setup_grants
             notebook_task:
               notebook_path: ./grant_notebook.ipynb
   
   targets:
     dev:
       mode: development
       default: true
       workspace:
         host: https://myworkspace.cloud.databricks.com
     prod:
       mode: production
       workspace:
         host: https://myworkspace.cloud.databricks.com
         root_path: /Workspace/Users/someone@example.com/.bundle/${bundle.name}/${bundle.target}
       permissions:
         - user_name: someone@example.com
           level: CAN_MANAGE
   

Implementar o pacote atualizado

Agora implementa o bundle no espaço de trabalho de produção e executa a aplicação:

databricks bundle deploy -t prod
databricks bundle run grant_job -t prod # (Optional) Run this if the grant is configured with a job
databricks bundle run hello_world_app -t prod

Recursos adicionais

• Databricks CLI
• bundle grupo de comando
• Referência de configuração
• Introdução aos aplicativos Databricks