Distribuire un'app Databricks

Dopo aver creato e sviluppato l'app Azure Databricks, distribuirla per renderla accessibile nell'area di lavoro Azure Databricks. La distribuzione compila l'app, installa le dipendenze e la esegue usando la configurazione definita nei file di progetto. È possibile distribuire app usando l'interfaccia utente di Azure Databricks o l'interfaccia della riga di comando di Databricks.

Logica di distribuzione

Databricks Apps supporta la distribuzione di applicazioni che usano Python, Node.jso una combinazione di entrambi. Ciò consente architetture flessibili, ad esempio un front-end Node.js con un back-end Python.

Durante la distribuzione, il processo di compilazione verifica la presenza di un package.json file nella radice della directory dell'app per determinare se viene usato Node.js. Se presente, include passaggi di compilazione specifici del Nodo insieme ai passaggi Python. La logica di distribuzione segue questo modello:

Se package.json è presente:

1. Eseguire npm install
2. Installare Python dipendenze:
   • Se requirements.txt esiste, eseguire pip install -r requirements.txt
   • Se requirements.txt non esiste e sia pyproject.toml che uv.lock esistono, eseguire uv sync per installare le dipendenze
3. Eseguire npm run build (se un build script è definito in package.json)
4. Eseguire il comando specificato in app.yamlo npm run start se non è specificato alcun comando

Se package.json non è presente:

1. Installare Python dipendenze:
   • Se requirements.txt esiste, eseguire pip install -r requirements.txt
   • Se requirements.txt non esiste e sia pyproject.toml che uv.lock esistono, eseguire uv sync per installare le dipendenze
2. Eseguire il comando specificato in app.yamlo python <my-app>.py se non è specificato alcun comando

Preparare la distribuzione

Prima di distribuire l'app, verificare che il progetto includa i componenti necessari:

• Script principale : file del punto di ingresso, ad esempio app.py o app.js.
• File facoltativo app.yaml : se l'app richiede un comando personalizzato o variabili di ambiente, includere un app.yaml file per configurare l'esecuzione. Vedere Configurare l'esecuzione dell'app Databricks con app.yaml.
• Dipendenze : assicurarsi che tutte le dipendenze siano disponibili. Vedere Gestire le dipendenze per un'app Databricks.
• Segreti o valori di ambiente : se si usa la env sezione in app.yaml, verificare che i segreti o le origini esterne di riferimento siano configurati e accessibili correttamente. Vedere Aggiungere risorse a un'app Databricks.

Inoltre, assicurarsi che l'entità servizio dell'app abbia accesso alla cartella del codice sorgente.

Scegliere un'origine di distribuzione

È possibile distribuire app Databricks dalle origini seguenti:

• Cartella dell'area di lavoro : caricare i file dell'app in una cartella dell'area di lavoro e distribuirli da questa posizione. Questo è il metodo di distribuzione standard. Vedi Eseguire il deployment da una cartella dell'area di lavoro.
• Repository Git : configurare un repository Git per un'app e distribuirlo direttamente senza caricare i file nell'area di lavoro. L'app legge il codice dal riferimento Git configurato (ramo, tag o commit) ogni volta che si distribuisce. Vedere Distribuire da un repository Git.

È possibile passare dall'area di lavoro alle origini Git per la stessa app in qualsiasi momento. Vedi Aggiornare o ridistribuire l'app.

Distribuire l'app

Le sezioni seguenti descrivono come eseguire la distribuzione da una cartella dell'area di lavoro o direttamente da un repository Git.

Eseguire la distribuzione da una cartella dell'area di lavoro

Interfaccia utente di Databricks

Per distribuire un'app dall'interfaccia utente di Azure Databricks:

1. Caricare i file dell'app nell'area di lavoro Azure Databricks. Per istruzioni, vedere Importare un file.
2. Nell'area di lavoro di Databricks, fare clic sull'icona Quindi, fare clic sullo switcher dell'app e selezionare Databricks Apps.
3. Selezionare l'app nella colonna Nome .
4. Fare clic su Distribuisci e selezionare la cartella nell'area di lavoro in cui sono stati caricati i file dell'app.
5. Fare clic su Seleziona, quindi su Distribuisci.

Interfaccia a riga di comando di Databricks

Per distribuire un'app usando l'interfaccia della riga di comando:

1. Aprire un terminale e passare alla directory che contiene i file dell'app.

2. Carica i file dell'app nell'area di lavoro di Azure Databricks usando il comando sync. Sostituire il percorso con il percorso dell'area di lavoro in cui si vogliono caricare i file.

   databricks sync --watch . /Workspace/Users/my-email@org.com/my-app
   

   Il --watch flag mantiene il processo di sincronizzazione in esecuzione e carica automaticamente le modifiche quando si modificano i file in locale. Per escludere file o directory specifici dalla sincronizzazione, aggiungerli a un .gitignore file nella directory dell'app locale. I file comuni da escludere sono node_modules/, .env, __pycache__/, .DS_Storee qualsiasi file di dati di grandi dimensioni o artefatti di compilazione.

3. Verificare il caricamento visualizzando i file nell'area di lavoro. Fare clic sull' nel selettore app >Analytics and AI, quindi fare clic su Workspace e passare alla directory creata per l'app.

4. Distribuire l'app eseguendo il comando seguente. Sostituire il nome dell'app e il percorso del codice sorgente con i valori.

   databricks apps deploy my-app-name \
      --source-code-path /Workspace/Users/my-email@org.com/my-app
   

   L'interfaccia della riga di comando visualizza lo stato di avanzamento della distribuzione e conferma quando l'app è in esecuzione.

Eseguire la distribuzione da un repository Git

Per distribuire un'app da un repository Git, aggiungere il repository a livello di app e quindi specificare il riferimento Git quando viene distribuito. Il repository Git deve contenere i file dell'app, incluse app.yaml le dipendenze e il punto di ingresso. Tutti i principali provider Git sono supportati, tra cui GitHub, GitLab e Bitbucket. È anche possibile distribuire app basate su Git usando l'interfaccia utente, l'interfaccia della riga di comando, l'API o i bundle di automazione dichiarativa.

Interfaccia utente di Databricks

Per configurare e distribuire un'app da Git:

1. Caricare i file dell'app in un repository Git.
2. Nell'area di lavoro di Databricks, fare clic sull'icona Quindi, fare clic sullo switcher dell'app e selezionare Databricks Apps.
3. Selezionare un'app esistente da modificare oppure fare clic su + Crea app e quindi su Crea un'app personalizzata. Vedere Creare un'app Databricks personalizzata.
4. Nel passaggio Configura Git immettere l'URL del repository Git (ad esempio, https://github.com/org/repo) e selezionare un provider Git.
5. Per una nuova app, immettere il riferimento Git (ramo, tag o commit) e, per i repository GitHub, abilitare facoltativamente Auto deploy on push events. Vedere Abilitare le distribuzioni Git automatiche.
6. Fare clic su Crea app o Salva per tornare alla pagina di panoramica dell'app.
7. Per i repository privati, l'entità del servizio dell'app deve avere una credenziale Git configurata. Nella pagina di panoramica dell'app fare clic su Configura credenziali Git. Per aggiungere credenziali Git, è necessario disporre CAN MANAGE delle autorizzazioni per l'app. I repository pubblici non richiedono credenziali Git. Per istruzioni per ogni provider, vedere Connettere il provider Git a Databricks.

Distribuire quindi l'app:

1. Nella pagina di panoramica dell'app fare clic su Distribuisci.
2. Seleziona da Git.
3. Per Riferimento Git, immettere il nome del ramo, il tag o il commit SHA (ad esempio, main, v1.0.0o un hash di commit).
4. Per Tipo riferimento specificare il tipo di riferimento, ad esempio un ramo, un tag o un commit.
5. (Facoltativo) Per Percorso del codice sorgente immettere un percorso di una directory specifica all'interno del repository. L'app considera tale directory come directory di primo livello e non può accedere ai file al di fuori di esso. Se non si specifica un percorso, Databricks usa la radice del repository.
6. (Facoltativo) Per eseguire automaticamente la distribuzione in ogni commit nel ramo, abilitare Distribuzione automatica negli eventi push. È necessario impostare un branch da monitorare. Facoltativamente, è possibile includere un percorso del codice sorgente per impostare un percorso diverso dalla radice del repository. Vedere Abilitare le distribuzioni Git automatiche.
7. Fare clic su Distribuisci.

Interfaccia a riga di comando di Databricks

Per distribuire un'app da Git usando l'interfaccia della riga di comando:

1. Caricare i file dell'app in un repository Git.

2. Configurare il repository Git nell'app quando si crea l'app o aggiungerla a un'app esistente. I provider supportati includono gitHub, gitHubEnterprisegitLab, gitLabEnterpriseEdition, bitbucketCloud, bitbucketServer, , azureDevOpsServicese awsCodeCommit.

   Per creare una nuova app con un repository Git configurato, usare il comando create :

   databricks apps create my-app \
      --json '{"git_repository": {"url": "https://github.com/org/repo", "provider": "gitHub"}}'
   

   Per aggiungere o aggiornare un repository Git in un'app esistente, usare il comando create-update :

   databricks apps create-update my-app \
      --json '{"update_mask": "git_repository", "git_repository": {"url": "https://github.com/org/repo", "provider": "gitHub"}}'
   

3. Per i repository privati, configurare una credenziale Git per il principale del servizio dell'app. Per aggiungere credenziali Git, è necessario disporre CAN MANAGE delle autorizzazioni per l'app. I repository pubblici non richiedono credenziali Git.

   Per aggiungere una credenziale Git al principale del servizio dell'app usando il CLI, eseguire:

   databricks git-credentials create --json '{
     "git_provider": "gitHub",
     "git_email": "your-email@example.com",
     "personal_access_token": "YOUR_TOKEN",
     "principal_id": YOUR_SP_ID,
     "name": "GitHub credentials for SP"
   }'
   

   Sostituire YOUR_SP_ID con l'ID entità servizio dell'app. Per istruzioni su come ottenere un token di accesso personale per ogni provider, vedere Connettere il provider Git a Databricks.

4. Distribuire l'app specificando il riferimento Git. È possibile specificare un branch, tag o commit (tra loro mutuamente esclusivi). Facoltativamente, includere source_code_path per la distribuzione da una sottodirectory all'interno del repository.

   databricks apps deploy my-app \
      --json '{"git_source": {"branch": "main"}}'
   

   Per distribuire un tag o un commit specifici:

   databricks apps deploy my-app \
      --json '{"git_source": {"tag": "v1.0.0"}}'
   

   databricks apps deploy my-app \
      --json '{"git_source": {"commit": "abc123def456"}}'
   

   Per eseguire la distribuzione da una sottodirectory all'interno del repository:

   databricks apps deploy my-app \
      --json '{"git_source": {"branch": "main", "source_code_path": "apps/my-app"}}'
   

   L'interfaccia della riga di comando visualizza lo stato di avanzamento della distribuzione e conferma quando l'app è in esecuzione.

Per i riferimenti a branch o tag, Azure Databricks distribuisce il commit più recente dal ramo o tag in questione. Per i riferimenti SHA del commit, Azure Databricks distribuisce sempre quel commit specifico. Se la credenziale Git dell'entità servizio non è valida o è scaduta, la distribuzione non riesce.

Abilitare le distribuzioni Git automatiche

Quando si abilitano le distribuzioni automatiche, Azure Databricks crea un webhook nel repository GitHub e ridistribuisce l'app ogni volta che il ramo configurato riceve un nuovo commit. L'app distribuita rimane sincronizzata con il repository senza alcuna procedura manuale. I repository sono limitati a 20 webhook (250 per GitHub Enterprise).

Le distribuzioni automatiche richiedono la configurazione seguente:

• L'app Azure Databricks GitHub deve essere installata nel repository.
• Il repository deve essere privato. Databricks non supporta le distribuzioni automatiche dai repository pubblici.
• L'entità servizio dell'applicazione deve disporre di una credenziale Git con accesso al repository. Consulta Connetti il provider Git a Databricks.

Per abilitare le distribuzioni automatiche, configurare GitHub come provider Git e abilitare Auto deploy on push events.To enable automatic deployments, configure GitHub as the Git provider and enable Auto deploy on push events. È possibile eseguire questa operazione in una delle posizioni seguenti:

• Passaggio Configura Git della procedura guidata Crea app personalizzata. Vedere Creare un'app Databricks personalizzata.
• Badge di distribuzione automatica in un'app esistente o riconfigurando le impostazioni dell'app. Seguire la procedura descritta in Distribuire da un repository Git.

Il riferimento Git deve essere un nome di ramo. I tag non sono compatibili con le distribuzioni automatiche.

Per disabilitare le distribuzioni automatiche, fare clic sul badge Distribuzione automatica in un'app esistente e disabilitare La distribuzione automatica negli eventi push. È anche possibile riconfigurare le impostazioni in Impostazioni app.

Imponi distribuzioni esclusivamente tramite Git

Gli amministratori dell'area di lavoro possono richiedere la distribuzione di tutte le app in un'area di lavoro dai repository Git. Passare a Impostazioni>App di sviluppo> e attivare Consenti solo le distribuzioni di app da Git. Questa opzione è disattivata per impostazione predefinita.

Quando si applicano le distribuzioni Git:

• Gli utenti devono configurare un repository Git prima di creare un'app.
• Gli utenti possono eseguire la distribuzione solo da Git, non dalle cartelle dell'area di lavoro.
• Databricks disabilita i modelli di app nell'area di lavoro.
• Gli utenti non possono rimuovere un repository Git dalle app che ne hanno una.
• Le app esistenti continuano a essere eseguite, ma gli utenti non possono distribuirli o avviarli di nuovo, a meno che l'app non disponga di un repository Git.

Comportamento post-distribuzione

Al termine della distribuzione, Azure Databricks avvia l'applicazione in base a command definito nel file app.yaml o, in assenza di ciò, esegue python app.py. La pagina di panoramica dell'app mostra lo stato corrente e fornisce l'accesso ai log, alla cronologia della distribuzione e alle informazioni sull'ambiente.

Per visualizzare l'output dell'app distribuita, fare clic sul collegamento dell'app.

Passare alla scheda Log per il debug e il monitoraggio del runtime. Vedere Registrazione e monitoraggio per le app di Databricks.

Aggiornare o ridistribuire l'app

Ridistribuire l'app dopo aver apportato modifiche al codice sorgente o alla configurazione. La ridistribuzione applica gli aggiornamenti più recenti senza ricreare l'app. È possibile ridistribuire da l'area di lavoro o dal repository Git in qualsiasi momento.

Ridistribuire da una cartella dell'area di lavoro

Per ridistribuire da una cartella dell'area di lavoro:

1. Aggiornare i file dell'app nella cartella dell'area di lavoro.
2. Selezionare l'app e fare clic su Distribuisci.
3. Se il percorso del codice sorgente è stato modificato o si passa da un'origine Git, fare clic sulla freccia accanto a Distribuisci e selezionare Distribuisci usando un'origine diversa.

Ridistribuire da un repository Git

Per ridistribuire da un repository Git:

1. Inviare le modifiche al repository Git.
2. Nell'area di lavoro Azure Databricks selezionare l'app e fare clic su Deploy. Se il riferimento Git è stato modificato o si passa da un'origine dell'area di lavoro, fare clic sulla freccia accanto a Distribuisci e selezionare Distribuisci usando un'origine diversa.

Per aggiornare il repository Git usando l'interfaccia della riga di comando o l'API, usare il comando create-update . La rimozione del repository Git dall'app impone la distribuzione dall'area di lavoro.

Risolvere i problemi di distribuzione

Se l'app non riesce a distribuire o non viene eseguita come previsto, provare la procedura di risoluzione dei problemi seguente:

• Controllare i log per i messaggi di errore o l'output di runtime.
• Convalidare app.yaml la sintassi e le impostazioni.
• Verificare che i segreti e le variabili di ambiente nella env sezione vengano risolti correttamente.
• Verificare che tutte le dipendenze necessarie siano incluse o installate.
• Se l'area di lavoro utilizza collegamento privato o criteri di rete in uscita con restrizioni, verificare che i domini richiesti siano autorizzati. Le voci mancanti della lista di autorizzazione per l'uscita sono una causa comune dei fallimenti di distribuzione negli ambienti collegamento privato. Consultare Distribuire app negli ambienti collegamento privato.

Per le distribuzioni di repository Git:

• Per i repository privati, verificare che il principale del servizio dell'app disponga di credenziali Git configurate.
• Verificare che l'URL del repository Git sia corretto e che il riferimento Git (ramo, tag o commit) esista nel repository.
• Se un amministratore dell'area di lavoro applica distribuzioni solo Git, non è possibile distribuire o avviare un'app a meno che non disponga di un repository Git configurato.
• Se si esegue la distribuzione dall'interfaccia della riga di comando (CLI), dall'API o dai bundle di automazione dichiarativa, creare l'applicazione prima, quindi aggiungere le credenziali Git all'entità servizio dell'applicazione.

Passaggi successivi

• Registrazione e monitoraggio per le app Databricks
• Configurare le autorizzazioni per un'app Databricks
• Configurare l'esecuzione dell'app Databricks con app.yaml