Sviluppare pipeline di Delta Live Table con bundle di asset di Databricks

I Databricks Asset Bundle, conosciuti anche semplicemente come bundle, consentono di convalidare, distribuire ed eseguire risorse di Azure Databricks a livello di codice, ad esempio pipeline di tabelle Delta Live. Consultare Che cosa sono i Databricks Asset Bundle?.

Questo articolo descrive come creare un bundle per gestire una pipeline in modo programmatico. Che cos'è Delta Live Tables?. Il bundle viene creato usando il modello predefinito di Databricks Asset Bundles per Python, costituito da un notebook associato alla definizione di una pipeline e di un processo per eseguirlo. Convalidare, distribuire ed eseguire la pipeline distribuita nell'area di lavoro di Azure Databricks.

Requisiti

• Interfaccia della riga di comando di Databricks versione 0.218.0 o successiva. Per controllare la versione installata dell'interfaccia della riga di comando di Databricks, eseguire il comando databricks -v. Per installare Databricks CLI non è installato, consultare Installare o aggiornare il Databricks CLI.
• L'area di lavoro remota deve avere abilitati i file dell'area di lavoro. Si veda Che cosa sono i file di area di lavoro?.

(Facoltativo) Installare un modulo Python per supportare lo sviluppo di pipeline locali

Databricks fornisce un modulo Python per facilitare lo sviluppo locale del codice della pipeline di Delta Live Table fornendo il controllo della sintassi, il completamento automatico e il controllo del tipo di dati durante la scrittura del codice nell'IDE.

Il modulo Python per lo sviluppo locale è disponibile in PyPi. Per installare il modulo, si veda Stub Python per Delta Live Table.

Crea un bundle usando un modello di progetto

Creare il bundle usando il modello di bundle predefinito di Azure Databricks per Python. Questo modello è costituito da un notebook che definisce una pipeline Delta Live Table, che filtra i dati dal set di dati originale. Per ulteriori informazioni sui modelli di bundle, si veda Modelli di progetto bundle di asset di Databricks.

Per creare un bundle da zero, vedere Creare manualmente un bundle.

Passaggio 1: Configurare l'autenticazione

In questo passaggio viene configurata l'autenticazione tra l'interfaccia della riga di comando di Databricks nel computer di sviluppo e l'area di lavoro di Azure Databricks. Questo articolo presuppone che si voglia usare l'autenticazione OAuth da utente a computer (U2M) e un profilo di configurazione di Azure Databricks corrispondente denominato DEFAULT per l'autenticazione.

1. Usare il Databricks CLI per avviare la gestione dei token OAuth in locale eseguendo il seguente comando per ogni area di lavoro di destinazione.

   Nel seguente comando, sostituire <workspace-url> con l’URL per l'area di lavoro di Azure Databricks, per esempio https://adb-1234567890123456.7.azuredatabricks.net.

   databricks auth login --host <workspace-url>
   

2. Il Databricks CLI richiede di salvare le informazioni immesse come profilo di configurazione di Azure Databricks. Premere Enter per accettare il nome del profilo suggerito oppure immettere il nome di un profilo nuovo o esistente. Qualsiasi profilo esistente con lo stesso nome viene sovrascritto con le informazioni immesse. È possibile usare i profili per cambiare rapidamente il contesto di autenticazione tra più aree di lavoro.

   Per ottenere un elenco di tutti i profili esistenti, in un terminale o un prompt dei comandi separato, usare il Databricks CLI per eseguire il comando databricks auth profiles. Per visualizzare le impostazioni esistenti di un profilo specifico, eseguire il comando databricks auth env --profile <profile-name>.

3. Nel Web browser completare le istruzioni visualizzate per accedere all'area di lavoro di Azure Databricks.

4. Per visualizzare il valore corrente del token OAuth di un profilo e il timestamp di scadenza imminente del token, eseguire uno dei comandi seguenti:

   • databricks auth token --host <workspace-url>
   • databricks auth token -p <profile-name>
   • databricks auth token --host <workspace-url> -p <profile-name>

   Se si dispone di più profili con lo stesso valore --host, potrebbe essere necessario specificare insieme le opzioni --host e -p per consentire al Databricks CLI di trovare le informazioni corrette corrispondenti sul token OAuth.

Passaggio 2: Creazione del bundle

Inizializzare un bundle usando il modello di progetto bundle Python predefinito.

1. Usare il terminale o il prompt dei comandi per passare a una directory nel computer di sviluppo locale che conterrà il bundle generato dal modello.

2. Usare l'interfaccia della riga di comando di Databricks per eseguire il comando bundle init:

   databricks bundle init
   

3. Per Template to use, lasciare il valore predefinito di default-python premendo Enter.

4. Per Unique name for this project, lasciare il valore predefinito di my_project o digitare un valore diverso e quindi premere Enter. Questo determina il nome della directory radice per questo bundle. Questa directory radice viene creata all’interno della directory di lavoro corrente.

5. Per Include a stub (sample) notebook, selezionare no e premere Enter. Ciò indica all'interfaccia della riga di comando di Databricks di non aggiungere un notebook modello a questo punto, perché il notebook modello associato a tale opzione non include codice Delta Live Table.

6. Per Include a stub (sample) DLT pipeline, lasciare il valore predefinito di yes premendo Enter. In questo modo viene indicato all'interfaccia della riga di comando di Databricks di aggiungere un notebook modello con codice Delta Live Table.

7. Per Include a stub (sample) Python package, selezionare no e premere Enter. In questo modo viene indicato all'interfaccia della riga di comando di Databricks di non aggiungere file di pacchetto Python di esempio o istruzioni di compilazione correlate al bundle.

Passaggio 3: Esplorare il bundle

Per visualizzare i file generati dal modello, passare alla directory radice del bundle appena creato. I file seguenti sono di particolare interesse:

• databricks.yml: questo file specifica il nome programmatico del bundle, include un riferimento alla definizione della pipeline e specifica le impostazioni relative all'area di lavoro di destinazione.
• resources/<project-name>_job.yml e resources/<project-name>_pipeline.yml: questi file definiscono il processo che contiene un'attività di aggiornamento della pipeline e le impostazioni della pipeline.
• src/dlt_pipeline.ipynb: questo file è un notebook che, quando viene lanciato, esegue la pipeline.

Per la personalizzazione delle pipeline, i mapping all’interno di una dichiarazione di pipeline corrispondono al payload della richiesta, , dell'operazione di creazione della pipeline, come definito in POST /api/2.0/pipelines nel riferimento all'API REST espresso in formato YAML.

Passaggio 4: convalidare il file di configurazione del bundle del progetto

In questo passaggio si verifica se la configurazione del bundle è valida.

1. Dalla directory radice usare l'interfaccia della riga di comando di Databricks per eseguire il comando bundle validate, come indicato di seguito:

   databricks bundle validate
   

2. Se viene restituito un riepilogo della configurazione del bundle, la convalida ha avuto esito positivo. Se vengono restituiti errori, correggerli e ripetere questo passaggio.

Se si apportano modifiche al bundle dopo questo passaggio, è necessario ripetere questo passaggio per verificare se la configurazione del bundle è ancora valida.

Passaggio 5: Distribuire il progetto locale nell'area di lavoro remota

In questo passaggio si distribuisce il notebook locale nell'area di lavoro di Azure Databricks remota e si crea la pipeline di Delta Live Table all'interno dell'area di lavoro.

1. Dalla radice del bundle usare l'interfaccia della riga di comando di Databricks per eseguire il comando bundle deploy, come indicato di seguito:

   databricks bundle deploy -t dev
   

2. Controllare se il notebook locale è stato distribuito: nella barra laterale dell'area di lavoro di Azure Databricks fare clic su Area di lavoro.

3. Fare clic nella cartella Users ><your-username>> .bundle ><project-name>> dev > files > src. Il notebook dovrebbe trovarsi in questa cartella.

4. Controllare se la pipeline è stato creata: nella barra laterale dell'area di lavoro di Azure Databricks fare clic su Delta Live Table.

5. Nella scheda Delta Live Table fare clic su [dev <your-username>] <project-name>_pipeline.

Se si apportano modifiche al bundle dopo questo passaggio, è necessario ripetere i passaggi 4 e 5 per verificare se la configurazione del bundle è ancora valida e quindi ridistribuire il progetto.

Passaggio 6: eseguire il progetto distribuito

In questo passaggio si attiva un'esecuzione della pipeline Delta Live Table nell'area di lavoro dalla riga di comando.

1. Dalla directory radice usare l'interfaccia della riga di comando di Databricks per eseguire il comando bundle run, come indicato di seguito, sostituendo <project-name> con il nome del progetto nel passaggio 2:

   databricks bundle run -t dev <project-name>_pipeline
   

2. Copiare il valore di Update URL visualizzato nel terminale e incollare questo valore nel Web browser per aprire l'area di lavoro di Azure Databricks.

3. Nell'area di lavoro di Azure Databricks , al termine della pipeline, fare clic sulla visualizzazione taxi_raw e sulla vista materializzata filtered_taxis per visualizzare i dettagli.

Se si apportano modifiche al bundle dopo questo passaggio, è necessario ripetere i passaggi da 4 a 6 per verificare se la configurazione del bundle è ancora valida, ridistribuire il progetto ed eseguire il progetto ridistribuito.

Passaggio 7: Pulizia

In questo passaggio si elimina dall'area di lavoro il notebook distribuito e la pipeline.

1. Dalla directory radice usare l'interfaccia della riga di comando di Databricks per eseguire il comando bundle destroy, come indicato di seguito:

   databricks bundle destroy -t dev
   

2. Confermare la richiesta di eliminazione della pipeline: quando viene richiesto di eliminare definitivamente le risorse, digitare y e premere Enter.

3. Confermare la richiesta di eliminazione del notebook: quando viene richiesto di eliminare definitivamente la cartella distribuita in precedenza e tutti i relativi file, digitare y e premere Enter.

4. Se si vuole eliminare anche il bundle dal computer di sviluppo, è ora possibile eliminare la directory locale dal passaggio 2.

Aggiungere a un bundle una definizione di pipeline esistente

È possibile usare una definizione di pipeline Delta Live Table esistente come base per definire una nuova pipeline in un file di configurazione del bundle. Per ottenere una definizione di pipeline esistente, è possibile recuperarla manualmente usando l'interfaccia utente oppure generarla in modo programmatico usando l'interfaccia della riga di comando di Databricks.

Ottenere una definizione di pipeline esistente usando l'interfaccia utente

Per ottenere la rappresentazione YAML di una definizione di pipeline esistente dall'interfaccia utente dell'area di lavoro di Azure Databricks:

1. Nella barra laterale dell'area di lavoro di Azure Databricks fare clic su Flussi di lavoro.

2. Nella scheda Delta Live Table fare clic sul collegamento Nome della pipeline.

3. Accanto al pulsante Sviluppo fare clic sul kebab e quindi su Visualizza impostazioni YAML.

4. Copiare il file YAML della definizione della pipeline nella finestra di dialogo YAML delle impostazioni della pipeline negli Appunti locali facendo clic sull'icona di copia.

5. Aggiungere il file YAML copiato nel file databricks.yml del bundle oppure creare un file di configurazione per la pipeline nella cartella resources del progetto bundle e farvi riferimento dal file databricks.yml. Vedere le risorse.

6. Scaricare e aggiungere quindi tutti i notebook e i file Python a cui viene fatto riferimento all'origine del progetto del bundle. In genere, gli artefatti bundle si trovano nella directory src in un bundle.

   Suggerimento

   È possibile esportare un notebook esistente da un'area di lavoro di Azure Databricks nel formato .ipynb facendo clic su File > Export > IPython Notebook dall'interfaccia utente del notebook di Azure Databricks.

   Dopo aver aggiunto i notebook, i file Python e altri artefatti al bundle, assicurarsi che la definizione della pipeline faccia riferimento correttamente. Ad esempio, per un notebook denominato hello.ipynb che si trova nella directory src/ del bundle:

   resources:
     pipelines:
       hello-pipeline:
         name: hello-pipeline
         libraries:
           - notebook:
               path: ../src/hello.ipynb
   

Generare una definizione di pipeline esistente usando l'interfaccia della riga di comando di Databricks

Per generare in modo programmatico la configurazione del bundle per una pipeline esistente:

1. Recuperare l'ID della pipeline esistente dal pannello laterale Dettagli della pipeline per la pipeline nell'interfaccia utente oppure usare il comando dell'interfaccia della riga di comando databricks pipelines list-pipelines di Databricks.

2. Eseguire il comando bundle generate pipeline dell'interfaccia della riga di comando di Databricks, impostando l'ID della pipeline:

   databricks bundle generate pipeline --existing-pipeline-id 6565621249
   

   Questo comando crea un file di configurazione bundle per la pipeline nella cartella resources del bundle e scarica tutti gli artefatti a cui si fa riferimento nella cartella src.

   Suggerimento

   Se si usa bundle deployment bind per associare una risorsa in un bundle a una delle aree di lavoro, allora la risorsa nell’area di lavoro viene aggiornata in base alla configurazione definita nel bundle a cui è associato dopo la successiva bundle deploy. Per informazioni su bundle deployment bind, vedere Associare le risorse del bundle.