Condividi tramite

Sviluppare un processo in Azure Databricks usando i bundle di asset di Databricks

  • Articolo

I bundle di asset di Databricks, detti semplicemente bundle, contengono gli artefatti da distribuire e le impostazioni per le risorse di Azure Databricks, ad esempio i processi da eseguire, e consentono di convalidarli, distribuirli ed eseguirli a livello di codice. Consultare Che cosa sono i Databricks Asset Bundle?.

Questo articolo descrive come creare un bundle per gestire un processo in modo programmatico. Si veda Pianificare e orchestrare i flussi di lavoro. Il bundle viene creato usando il modello predefinito di Databricks Asset Bundles per Python, costituito da un notebook associato alla definizione di un processo per eseguirlo. Convalidare, distribuire ed eseguire il processo distribuito nell'area di lavoro di Azure Databricks.

Suggerimento

Se sono presenti processi creati usando l'interfaccia utente o l'API di Processi di Azure Databricks da spostare in bundle, è necessario definirli nei file di configurazione di un bundle. Databricks consiglia di creare prima un bundle usando la procedura seguente e quindi verificare se il bundle funziona. È poi possibile aggiungere al bundle altre definizioni di processo, notebook e altre origini. Vedere Aggiungere a un bundle una definizione di processo esistente.

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 di Databricks deve avere abilitati i file dell'area di lavoro. Si veda Che cosa sono i file di area di lavoro?.

Crea un bundle usando un modello di progetto

Per prima cosa, creare un bundle usando il modello Python predefinito dei bundle di asset di Databricks. 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.

Nota

L'autenticazione U2M è appropriata per provare questi passaggi in tempo reale. Per i flussi di lavoro completamente automatizzati, Databricks consiglia di usare invece l'autenticazione OAuth da computer a computer (M2M). Vedere le istruzioni di configurazione dell'autenticazione M2M.

  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: Inizializzare il 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 nella directory di lavoro corrente.

  5. Per Include a stub (sample) notebook, selezionare yes e premere Enter.

  6. Per Include a stub (sample) DLT pipeline, selezionare no e premere Enter. Ciò indica all'interfaccia della riga di comando di Databricks di non definire nel bundle una pipeline di tabelle Delta Live di esempio.

  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 del processo e specifica le impostazioni relative all'area di lavoro di destinazione.
  • resources/<project-name>_job.yml: questo file specifica le impostazioni del processo, inclusa un'attività notebook predefinita.
  • src/notebook.ipynb: questo file è un notebook di esempio che, quando viene eseguito, inizializza semplicemente un RDD che contiene i numeri da 1 a 10.

Per la personalizzazione dei processi, i mapping in una dichiarazione di processo corrispondono al payload della richiesta, espresso in formato YAML, dell'operazione di creazione del processo, come documentato in POST /api/2.1/jobs/create nel riferimento all'API REST.

Suggerimento

È possibile definire, combinare ed eseguire l'override delle impostazioni per i nuovi cluster di processi nei bundle usando le tecniche descritte in Eseguire l’override delle impostazioni dei cluster nei bundle di asset di Databricks.

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 il processo di Azure Databricks 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 il processo è stato creato: nella barra laterale dell'area di lavoro di Azure Databricks fare clic su Flussi di lavoro.

  5. Sulla scheda Processi fare clic su [dev <your-username>] <project-name>_job.

  6. Fare clic sulla scheda Attività, dove dovrebbe essere presente un'attività: notebook_task.

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 l’esecuzione del processo di Azure Databricks 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>_job

  2. Copiare il valore di Run URL visualizzato nel terminale e incollare questo valore nel Web browser per aprire l'area di lavoro di Azure Databricks. Consultare Visualizzare ed eseguire un processo creato con un bundle di asset di Databricks

  3. Nell'area di lavoro di Azure Databricks, dopo che l'attività del processo è stata completata correttamente e viene visualizzata una barra del titolo verde, fare clic sull'attività di processo per visualizzare i risultati.

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 il processo.

  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 del processo: 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 processo esistente

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

Per informazioni sulla definizione del processo nei bundle, vedere processo.

Ottenere una definizione di processo esistente usando l'interfaccia utente

Per ottenere la rappresentazione YAML di una definizione di processo 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 Processi fare clic sul link delNomedel processo.

  3. Accanto al pulsante Esegui ora fare clic sul kebab e quindi su Passa al codice (YAML).

  4. Aggiungere il file YAML copiato nel file databricks.yml del bundle oppure creare un file di configurazione per il processo nella directory resources del progetto bundle e farvi riferimento dal file databricks.yml. Si veda (/dev-tools/bundles/settings.md#resources).

  5. Scaricare e aggiungere tutti i notebook e i file Python a cui viene fatto riferimento nel processo esistente 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 del processo faccia riferimento correttamente. Ad esempio, per un notebook denominato hello.ipynb che si trova nella directory src del bundle:

    resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
      - task_key: hello-task
        notebook_task:
          notebook_path: ../src/hello.ipynb

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

Per generare in modo programmatico la configurazione del bundle per un processo esistente:

  1. Recuperare l'ID del processo esistente dal pannello laterale Dettagli del processo per il processo nell'interfaccia utente processi oppure usare il comando dell'interfaccia della riga di comando databricks jobs list di Databricks.

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

    databricks bundle generate job --existing-job-id 6565621249

    Questo comando crea un file di configurazione bundle per il processo nella cartella resources del bundle e scarica tutti gli artefatti referenziati 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.

Configurare un processo che usa l'ambiente di calcolo serverless

Gli esempi seguenti illustrano le configurazioni bundle per creare un processo che usa il calcolo serverless.

Per usare il calcolo serverless per eseguire un processo che include le attività del notebook, omettere la configurazione job_clusters dal file di configurazione del bundle.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job-serverless:
      name: retrieve-filter-baby-names-job-serverless
      tasks:
        - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./filter-baby-names.py

  targets:
    development:
      workspace:
        host: <workspace-url>

Per usare il calcolo serverless per eseguire un processo che include attività Python, includere la configurazione environments.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: serverless-python-tasks

resources:
jobs:
  serverless-python-job:
    name: serverless-job-with-python-tasks

    tasks:
      - task_key: wheel-task-1
        python_wheel_task:
          entry_point: main
          package_name: wheel_package
        environment_key: Default

    environments:
      - environment_key: Default
        spec:
          client: "1"
          dependencies:
            - workflows_authoring_toolkit==0.0.1

targets:
  development:
    workspace:
      host: <workspace-url>

Vedere Eseguire il processo di Azure Databricks con calcolo serverless per i flussi di lavoro.