Condividi tramite

Creare un bundle manualmente

  • Articolo

In questa esercitazione viene creato un bundle di asset di Databricks da zero. Questo semplice bundle è costituito da due notebook e dalla definizione di un processo di Azure Databricks per eseguire questi notebook. Si può poi convalidare, distribuire ed eseguire il processo nell'area di lavoro di Azure Databricks. Questi passaggi automatizzano l’avvio rapido intitolato Crare il primo flusso di lavoro con un processo di Azure Databricks.

Requisiti

Passaggio 1: Creazione del bundle

Un bundle contiene gli artefatti da distribuire e le impostazioni per le risorse da eseguire.

  1. Creare o identificare una directory vuota nel computer di sviluppo.
  2. Passare alla directory vuota nel terminale o aprirla nell'IDE.

Suggerimento

È anche possibile usare una directory contenente un repository clonato da un provider Git. In questo modo è possibile gestire il bundle con il controllo della versione esterna e collaborare più facilmente nel progetto con altri sviluppatori e professionisti IT.

Se si sceglie di clonare un repository per questa demo, Databricks consiglia che il repository sia vuoto o che contenga solo file di base, ad esempio README e .gitignore. In caso contrario, tutti i file pre-esistenti nel repository potrebbero essere sincronizzati inutilmente con l'area di lavoro di Azure Databricks.

Passaggio 2: Aggiunta di notebook al progetto

In questo passaggio si aggiungono due notebook al progetto. Il primo notebook ottiene un elenco dei nomi più usati per i bambini a partire dal 2007, proveniente dalle origini dati pubbliche del Dipartimento di Stato di New York. Vedere Baby Names: Trending by Name: Beginning 2007 nel sito Web del dipartimento. Il primo notebook salva quindi questi dati nel volume del catalogo Unity di Azure Databricks denominato my-volume in uno schema denominato default in un catalogo denominato main. Il secondo notebook esegue una query sui dati salvati e visualizza i conteggi aggregati dei nomi dei bambini in base al nome e al sesso per il 2014.

  1. Dalla radice della directory creare il primo notebook, un file denominato retrieve-baby-names.py.

  2. Aggiungere il codice seguente al file retrieve-baby-names.py:

    # Databricks notebook source
import requests

response = requests.get('http://health.data.ny.gov/api/views/jxy9-yhdk/rows.csv')
csvfile = response.content.decode('utf-8')
dbutils.fs.put("/Volumes/main/default/my-volume/babynames.csv", csvfile, True)

  3. Creare nella stessa directory il secondo notebook, un file denominato filter-baby-names.py.

  4. Aggiungere il codice seguente al file filter-baby-names.py:

    # Databricks notebook source
babynames = spark.read.format("csv").option("header", "true").option("inferSchema", "true").load("/Volumes/main/default/my-volume/babynames.csv")
babynames.createOrReplaceTempView("babynames_table")
years = spark.sql("select distinct(Year) from babynames_table").toPandas()['Year'].tolist()
years.sort()
dbutils.widgets.dropdown("year", "2014", [str(x) for x in years])
display(babynames.filter(babynames.Year == dbutils.widgets.get("year")))

Passaggio 3: Aggiungere un file di schema di configurazione bundle al progetto

Se si usa un IDE come Visual Studio Code, PyCharm Professional o IntelliJ IDEA Ultimate che fornisce supporto per file YAML e file di schema JSON, è possibile usare l'IDE non solo per creare il file di configurazione del bundle, ma per controllare la sintassi e la formattazione del file di configurazione bundle del progetto. Mentre il file di configurazione del bundle creato più avanti nel passaggio 5 è basato su YAML, il file dello schema di configurazione del bundle in questo passaggio è basato su JSON.

Visual Studio Code

  1. Aggiungere il supporto del server di linguaggio YAML a Visual Studio Code, ad esempio installando l'estensione YAML da Visual Studio Code Marketplace.

  2. Generare il file di schema JSON di configurazione del bundle di asset di Databricks usando l'interfaccia della riga di comando di Databricks per eseguire il comando bundle schema e reindirizzare l'output a un file JSON. Ad esempio, generare un file denominato bundle_config_schema.json nella directory corrente, come indicato di seguito:

    databricks bundle schema > bundle_config_schema.json

  3. Nel passaggio 5 si aggiungerà il commento seguente all'inizio del file di configurazione del bundle, che associa il file di configurazione del bundle al file di schema JSON specificato:

    # yaml-language-server: $schema=bundle_config_schema.json

    Nota

    Nel commento precedente, se il file di schema JSON di configurazione del bundle di asset di Databricks si trova in un percorso diverso, sostituire bundle_config_schema.json con il percorso completo del file di schema.

PyCharm Professional

  1. Generare il file di schema JSON di configurazione del bundle di asset di Databricks usando l'interfaccia della riga di comando di Databricks per eseguire il comando bundle schema e reindirizzare l'output a un file JSON. Ad esempio, generare un file denominato bundle_config_schema.json nella directory corrente, come indicato di seguito:

    databricks bundle schema > bundle_config_schema.json

  2. Configurare PyCharm per riconoscere il file di schema JSON di configurazione del bundle e quindi completare il mapping dello schema JSON seguendo le istruzioni riportate in Configurare uno schema JSON personalizzato.

  3. Nel passaggio 5 usare PyCharm per creare o aprire un file di configurazione del bundle. Per convenzione, questo file è denominato databricks.yml.

IntelliJ IDEA Ultimate

  1. Generare il file di schema JSON di configurazione del bundle di asset di Databricks usando l'interfaccia della riga di comando di Databricks per eseguire il comando bundle schema e reindirizzare l'output a un file JSON. Ad esempio, generare un file denominato bundle_config_schema.json nella directory corrente, come indicato di seguito:

    databricks bundle schema > bundle_config_schema.json

  2. Configurare IntelliJ IDEA per riconoscere il file di schema JSON di configurazione del bundle e poi completare il mapping dello schema JSON seguendo le istruzioni riportate in Configurare uno schema JSON personalizzato.

  3. Nel passaggio 5 usare IntelliJ IDEA per creare o aprire un file di configurazione del bundle. Per convenzione, questo file è denominato databricks.yml.

Passaggio 4: 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 l'interfaccia della riga di comando di Databricks per avviare la gestione dei token OAuth in locale eseguendo il comando seguente per ogni area di lavoro di destinazione.

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

    databricks auth login --host <workspace-url>

  2. L'interfaccia della riga di comando di Databricks 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 l'interfaccia della riga di comando di Databricks 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 all'interfaccia della riga di comando di Databricks di trovare le informazioni corrette corrispondenti sul token OAuth.

Passaggio 5: Aggiungere un file di configurazione bundle al progetto

In questo passaggio si definisce come distribuire ed eseguire i due notebook. Per questa demo si vuole usare un processo di Azure Databricks per eseguire il primo notebook e poi il secondo. Poiché il primo notebook salva i dati e il secondo notebook esegue query sui dati salvati, si vuole che il primo notebook venga completato prima dell'avvio del secondo. Questi obiettivi vengono modellati in un file di configurazione bundle nel progetto.

  1. Dalla radice della directory creare il file di configurazione bundle, un file denominato databricks.yml.
  2. Aggiungere il codice seguente al file databricks.yml, sostituendo <workspace-url> con l'URL per area di lavoro, ad esempio https://adb-1234567890123456.7.azuredatabricks.net. Questo URL deve corrispondere a quello nel file .databrickscfg:

Suggerimento

La prima riga, a partire da # yaml-language-server, è necessaria solo se l'IDE lo supporta. Per informazioni dettagliate, vedere Passaggio 3.

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

resources:
  jobs:
    retrieve-filter-baby-names-job:
      name: retrieve-filter-baby-names-job
      job_clusters:
        - job_cluster_key: common-cluster
          new_cluster:
            spark_version: 12.2.x-scala2.12
            node_type_id: Standard_DS3_v2
            num_workers: 1
      tasks:
        - task_key: retrieve-baby-names-task
          job_cluster_key: common-cluster
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          job_cluster_key: common-cluster
          notebook_task:
            notebook_path: ./filter-baby-names.py

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

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 6: convalidare il file di configurazione del bundle del progetto

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

  1. 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 7: Distribuire il progetto locale nell'area di lavoro remota

In questo passaggio si distribuiscono i due notebook locali nell'area di lavoro remota di Azure Databricks e si crea il processo di Azure Databricks nell'area di lavoro.

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

    databricks bundle deploy -t development

  2. Controllare se i due notebook locali sono stati distribuiti: 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 > baby-names > development > files. I due notebook dovrebbero 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. Nella scheda Processi fare clic su retrieve-filter-baby-names-job.

  6. Fare clic sulla scheda Attività, dove dovrebbero essere presenti due attività: retrieve-baby-names-task e filter-baby-names-task.

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

Passaggio 8: eseguire il progetto distribuito

In questo passaggio si esegue il processo di Azure Databricks nell’area di lavoro.

  1. Usare l'interfaccia della riga di comando di Databricks per eseguire il comando bundle run, come indicato di seguito:

    databricks bundle run -t development retrieve-filter-baby-names-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.

  3. Nell'area di lavoro di Azure Databricks, dopo il completamento delle due attività e la visualizzazione delle barre del titolo verdi, fare clic sull'attività filter-baby-names-task per visualizzare i risultati della query.

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

Passaggio 9: Pulizia

In questo passaggio si eliminano dall'area di lavoro i due notebook distribuiti e il processo.

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

    databricks bundle destroy

  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 dei notebook: quando viene richiesto di eliminare definitivamente la cartella distribuita in precedenza e tutti i relativi file, digitare y e premere Enter.

L'esecuzione del comando bundle destroy elimina solo il processo distribuito e la cartella contenente i due notebook distribuiti. Questo comando non elimina alcun effetto collaterale, ad esempio il file babynames.csv creato dal primo notebook. Per eliminare il file babybnames.csv, eseguire le operazioni seguenti:

  1. Nella barra laterale dell'area di lavoro di Azure Databricks fare clic su Catalogo.
  2. Fare clic su Sfoglia DBFS.
  3. Fare clic sulla cartella FileStore.
  4. Fare clic sulla freccia a discesa accanto a babynames.csv e fare clic su Elimina.
  5. Se si vuole eliminare anche il bundle dal computer di sviluppo, è ora possibile eliminare la directory locale dal passaggio 1.