Gerenciar aplicativos Databricks usando Databricks Asset Bundles

Os aplicativos Databricks permitem criar dados seguros e aplicativos de IA na plataforma Databricks que você pode compartilhar facilmente com os usuários. Você pode gerenciar implantações de seus aplicativos usando o Databricks Asset Bundles. Para obter mais informações sobre aplicativos e pacotes, consulte Aplicativos Databricks e O que são pacotes de ativos Databricks?.

Este artigo orienta você no desenvolvimento de um aplicativo Databricks localmente e, em seguida, na configuração de um pacote para gerenciar implantações do aplicativo no espaço de trabalho Databricks usando Databricks Asset Bundles.

Sugestão

Para inicializar um pacote de exemplo com um aplicativo Streamlit, use o modelo de pacote streamlit-app com o bundle init comando:

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. Os aplicativos são desenvolvidos em Python usando estruturas populares, como Dash ou Gradio. Você pode criar um aplicativo Databricks localmente do zero, criar um no espaço de trabalho Databricks e, em seguida, sincronizar os arquivos com sua máquina local ou obter um aplicativo de exemplo Databricks do 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 app.yaml arquivo à raiz do seu projeto para definir como executar seu aplicativo Python principal. 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 um aplicativo de exemplo Databricks do GitHub:

  1. Clone os modelos de aplicativo Databricks repositório GitHub:

     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, instale o depurador Python e, em seguida, selecione Executar>Iniciar Depuração e, em seguida, Anexar Remotamente.

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

• O que é a CLI do Databricks?
• bundle grupo de comando
• Referência de configuração
• Introdução aos aplicativos Databricks