Pular para o conteúdo principal
Última atualização em

Gerenciar Databricks aplicativos usando Databricks ativo Bundles

Databricks O Apps permite criar dados seguros e aplicativos AI na plataforma Databricks que podem ser facilmente compartilhados com os usuários. O senhor pode gerenciar implementações de seus aplicativos usando Databricks ativo Bundles. Para obter mais informações sobre aplicativos e pacotes, consulte Databricks Apps e What are Databricks ativo Bundles?

Este artigo orienta o senhor no desenvolvimento de um aplicativo Databricks localmente e, em seguida, na configuração de um pacote para gerenciar implantações do aplicativo no Databricks workspace usando Databricks ativo Bundles.

dica

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

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

Requisitos​

Crie um aplicativo localmente​

Primeiro, crie um aplicativo Databricks. Os aplicativos são desenvolvidos em Python usando estruturas populares, como Dash ou Gradio. O senhor pode criar um aplicativo Databricks localmente a partir do zero, criar um no site Databricks workspace e sincronizar os arquivos com seu computador local ou obter um aplicativo de amostra Databricks em GitHub.

  • Para criar um aplicativo do zero:

    1. Siga um rápido começar tutorial para obter uma estrutura:

    2. Adicione um arquivo app.yaml à raiz do seu projeto para definir como executar o aplicativo principal Python. Por exemplo:

      Para um aplicativo Streamlit:

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

      Ou para um aplicativo Dash:

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

  • Para criar um aplicativo no site workspace e sincronizá-lo localmente:

    1. Siga os passos em Primeiros passos com Databricks Apps para criar um aplicativo na interface do usuário.

    2. Crie um diretório local para o aplicativo e cd nele:

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

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

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

      Isso downloads os arquivos do aplicativo no diretório workspace para o diretório hello-world-app em seu computador local.

  • Para obter um aplicativo de amostra do Databricks no GitHub:

    1. Clone o Databricks repositório padrão do GitHub aplicativo:

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

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

Adicionar um aplicativo existente a um pacote existente​

Se você tiver um aplicativo Databricks em seu workspace e tiver um pacote existente ao qual deseja adicionar o aplicativo, poderá usar o comando databricks bundle generate app. Esse comando gera um arquivo de configuração para o aplicativo e downloads todos os arquivos de código-fonte do aplicativo e os adiciona ao seu pacote. Por exemplo:

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

Depois de gerar a configuração do aplicativo no pacote, use o comando databricks bundle bind para manter o aplicativo no workspace e no pacote em sincronia.

Para obter mais informações sobre databricks bundle generate e databricks bundle bind, consulte bundle comando group.

Desenvolva e depure o aplicativo localmente​

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

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

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

    Esse comando usa o site uv para preparar o ambiente virtual e o depurador é baseado no site debugpy.

  2. Navegue até http://localhost:8001 para view seu aplicativo.

  3. Defina pontos de interrupção para depurar seu aplicativo. No Visual Studio Code, instale o depurador Python, selecione execução > começar depuração e, em seguida, Remote Attach .

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

implantar o aplicativo no workspace​

Quando o senhor estiver pronto para implantar seu aplicativo no site workspace, 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. O Databricks CLI reconhece uma pasta com um arquivo databricks.yml em sua raiz como um pacote, o que permite o comando databricks bundle.

  2. Copie e cole o YAML a seguir no arquivo databricks.yml, substituindo os valores de workspace e de nome de usuário por seus próprios valores:

    YAML
    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. Em default, isso cria o aplicativo e o pacote no destino dev em workspace.

    Bash
    databricks bundle validate
    databricks bundle deploy

  4. Implantar um pacote não implanta automaticamente o aplicativo para compute. Para implantar o aplicativo, use a interface do usuário (na página do aplicativo no workspace Databricks ) ou a CLI Databricks (databricks apps deploy). Consulte implantado um aplicativo Databricks.

  5. Utilize o comando bundle summary para recuperar informações sobre o aplicativo implantado:

    Bash
    databricks bundle summary
    Output
    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 em seu aplicativo localmente e, em seguida, reimplante o pacote para atualizar o aplicativo no site workspace. Para começar o aplicativo no site workspace, execute o aplicativo no pacote especificando o recurso key para o aplicativo no comando:

Bash
databricks bundle run hello_world_app

implantar para produção​

A Databricks recomenda o uso de uma entidade de serviço para autenticação em produção. Quando estiver pronto para disponibilizar o aplicativo em produção, atualize a configuração do seu pacote para usar uma entidade de serviço e, em seguida, implante o pacote no seu workspace de produção de destino. Para informações sobre entidade de serviço, consulte entidade de serviço para CI/CD.

Modifique o pacote para usar uma entidade de serviço.​

Antes de implantar em produção, configure uma concessão no pacote que dê permissão a uma entidade de serviço. Você pode configurar a concessão quando o aplicativo for criado ou quando o pacote for executado.

Para conceder permissão à entidade de serviço quando o aplicativo é criado no pacote implantado, modifique o databricks.yml do pacote para definir uma concessão para o aplicativo. Utilize uma substituição de pacote para atribuir a entidade de serviço:

YAML
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:
        - 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 uma tarefa no pacote que configure uma concessão quando o pacote estiver em execução:

  1. Adicione um Notebook chamado grant_notebook.ipynb com o seguinte conteúdo em uma célula. Substitua <schema-name> por um nome de usuário de administrador.

    Python
    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 um Job no databricks.yml do bundle para executar um Notebook que conceda permissão à entidade de serviço. Use substituições de pacotes para atribuir o valor da entidade de serviço:

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

implantou o pacote atualizado​

Agora, implante o pacote no workspace de produção e execute o aplicativo:

Bash
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

Recurso adicional​