Gestire le app databricks usando i bundle di asset di Databricks

Databricks Apps consente di creare applicazioni di dati e intelligenza artificiale sicure nella piattaforma Databricks che è possibile condividere facilmente con gli utenti. È possibile gestire le distribuzioni delle app usando i bundle di asset di Databricks. Per altre informazioni sulle app e sui bundle, vedere Databricks Apps e What are Databricks Asset Bundles?.

Questo articolo illustra come sviluppare un'app Databricks in locale e quindi configurare un bundle per gestire le distribuzioni dell'app nell'area di lavoro Databricks usando i bundle di asset di Databricks.

Suggerimento

Per inizializzare un bundle di esempio con un'app Streamlit, usare il modello di bundle streamlit-app con il bundle init comando :

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

Requisiti

• L'area di lavoro databricks e l'ambiente di sviluppo locale devono soddisfare i requisiti per le app databricks. Vedere Configurare l'area di lavoro e l'ambiente di sviluppo di Databricks Apps.
• Interfaccia della riga di comando di Databricks versione 0.250.0 o versione successiva. Per controllare la versione installata dell'interfaccia della riga di comando di Databricks, eseguire il comando databricks -v. Per installare o aggiornare Databricks CLI, consultare Installare o aggiornare il Databricks CLI.

Creare un'app in locale

Creare prima di tutto un'app Databricks. Le app vengono sviluppate in Python usando framework diffusi, ad esempio Dash o Gradio. È possibile creare un'app Databricks in locale da zero, crearne una nell'area di lavoro Databricks e quindi sincronizzare i file nel computer locale oppure ottenere un'app di esempio Databricks da GitHub.

• Per creare un'app da zero:

  1. Segui un tutorial introduttivo per un framework:

     • Trattino
     • Beuta
     • Gradio
     • Lucido
     • Streamlit

  2. Aggiungere un app.yaml file alla radice del progetto per definire come eseguire l'app Python principale. Per esempio:

     Per un'app Streamlit:

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

     Oppure per un'applicazione Dash:

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

• Per creare un'app nell'area di lavoro e sincronizzarla in locale:

  1. Seguire la procedura descritta in Introduzione ad App Databricks per creare un'app nell'interfaccia utente.

  2. Creare una directory locale per l'app e cd inserirla:

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

  3. Sincronizzare i file dell'app in locale. È possibile copiare il databricks workspace export-dir comando dalla pagina di installazione dell'app nell'interfaccia utente dell'area di lavoro ed eseguirlo nella riga di comando. Per esempio:

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

     I file dell'app vengono scaricati dalla directory dell'area di lavoro alla directory hello-world-app sul computer locale.

• Per ottenere un'app di esempio databricks da GitHub:

  1. Clonare il repository GitHub dei modelli di app di Databricks:

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

  2. Scegliere una delle app di esempio come progetto di app semplice.

Aggiungere un'app esistente a un bundle esistente

Se si dispone di un'app Databricks nell'area di lavoro e si dispone di un bundle esistente a cui si vuole aggiungere l'app, è possibile usare il databricks bundle generate app comando . Questo comando genera un file di configurazione per l'app e scarica tutti i file di codice sorgente per l'app e li aggiunge al bundle. Per esempio:

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

Dopo aver generato la configurazione dell'app nel bundle, usare il databricks bundle bind comando per mantenere sincronizzata l'app nell'area di lavoro e il bundle.

Per altre informazioni su databricks bundle generate e databricks bundle bind, vedere bundle gruppo di comandi.

Sviluppare ed eseguire il debug dell'app in locale

Continuare quindi a sviluppare l'app in locale. Avviare ed eseguire il debug dell'app usando il databricks apps run-local comando . Questo comando avvia un proxy dell'app che viene utilizzato per inoltrare le richieste all'app stessa e inietta le intestazioni necessarie relative all'app Databricks.

1. Per installare tutte le dipendenze, preparare l'ambiente virtuale e avviare l'app e il debugger, usare il run-local comando con le --prepare-environment opzioni e --debug :

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

   Questo comando usa uv per preparare l'ambiente virtuale e il debugger è basato su debugpy.

2. Passare a http://localhost:8001 per visualizzare l'app.

3. Impostare punti di interruzione per eseguire il debug dell'app. In Visual Studio Code, installare il debugger Python, quindi selezionare Esegui>Avvia debug e quindi Connessione remota.

   Il proxy viene avviato sulla porta 5678, ma è possibile configurarlo usando l'opzione --port .

Distribuire l'app nell'area di lavoro

Quando si è pronti per distribuire l'app nell'area di lavoro, aggiungere la configurazione del bundle che crea l'app e quindi distribuire il bundle.

1. Creare un file databricks.yml nella radice del progetto dell'app. L'interfaccia della riga di comando di Databricks riconosce una cartella con un databricks.yml file nella radice come bundle, che abilita i comandi bundle di Databricks.

2. Copia e incolla il seguente YAML nel file databricks.yml, sostituendo i segnaposto dell'area di lavoro e del nome utente con i tuoi propri.

   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. Convalidare, quindi distribuire il bundle. Per impostazione predefinita, viene creata l'app e il dev bundle nella destinazione nell'area di lavoro.

   databricks bundle validate
   databricks bundle deploy
   

4. La distribuzione di un bundle non implementa automaticamente l'app sulle risorse di calcolo. Per distribuire l'app, usare l'interfaccia utente (dalla pagina dell'app nell'area di lavoro Databricks) o l'interfaccia della riga di comando di Databricks (databricks apps deploy). Vedere Distribuire un'app Databricks.

5. Usare il bundle summary comando per recuperare informazioni sull'app distribuita:

   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
   

Sviluppare, testare, eseguire l'iterazione

Continuare a apportare modifiche all'app in locale, quindi ridistribuire il bundle per aggiornare l'app nell'area di lavoro. Durante i test, è possibile configurare le autorizzazioni di utilizzo per l'app per altri utenti nell'area di lavoro di Azure Databricks, che è possibile eseguire specificando le autorizzazioni:

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

Per avviare l'app nell'area di lavoro, eseguire l'app nel bundle specificando la chiave di risorsa per l'app nel comando :

databricks bundle run hello_world_app

Distribuzione nell'ambiente di produzione

Databricks consiglia di usare un principale del servizio per l'autenticazione nell'ambiente di produzione. Quando si è pronti per rendere disponibile l'app nell'ambiente di produzione, aggiornare la configurazione del bundle per usare un'entità servizio, quindi distribuire il bundle nell'area di lavoro di produzione di destinazione. Per informazioni sui principali del servizio, vedere Principali del servizio per CI/CD.

Modificare il bundle per usare un principale del servizio

Prima di eseguire la distribuzione nell'ambiente di produzione, configurare una concessione nel bundle che concede l'autorizzazione a un'entità servizio. È possibile configurare la concessione quando viene creata l'app o quando viene eseguito il bundle.

Per concedere all'entità servizio l'autorizzazione necessaria quando l'app viene creata durante la distribuzione del bundle, modificare il bundle databricks.yml per definire una concessione per l'app. Utilizzare una sostituzione del pacchetto per assegnare il principale del servizio:

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

In alternativa, definire un processo nel bundle che configura una concessione quando viene eseguito il bundle:

1. Aggiungere un notebook denominato grant_notebook.ipynb con il contenuto seguente in una cella. Sostituire <schema-name> con un nome utente amministratore.

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

2. Definire un lavoro nel bundle databricks.yml per eseguire un notebook che concede l'autorizzazione al service principal. Usare le sostituzioni bundle per assegnare il valore dell'entità servizio:

   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
   

Distribuire il bundle aggiornato

Distribuire ora il bundle nell'area di lavoro di produzione ed eseguire l'app:

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

Risorse aggiuntive

• Che cos'è l'interfaccia della riga di comando di Databricks?
• bundle gruppo di comandi
• Informazioni di riferimento sulla configurazione
• Introduzione alle app databricks