Condividi tramite

Usare dbx con Visual Studio Code

  • Articolo

Importante

Questa documentazione è stata ritirata e potrebbe non essere aggiornata.

Databricks consiglia di usare i bundle di asset di Databricks invece di dbx di Databricks Labs. Vedere Che cosa sono i bundle di asset di Databricks? e Eseguire la migrazione da dbx a bundle.

Per usare Azure Databricks con Visual Studio Code, vedere l'articolo Estensione di Databricks per Visual Studio Code.

Questo articolo descrive un esempio di codice basato su Python che è possibile usare in qualsiasi IDE compatibile con Python. In particolare, questo articolo descrive come usare questo esempio di codice in Visual Studio Code, il quale fornisce le seguenti funzionalità di produttività per sviluppatori:

Questo articolo usa dbx di Databricks Labs insieme a Visual Studio Code per inviare l'esempio di codice a un'area di lavoro remota di Azure Databricks. dbx indica ad Azure Databricks di Panoramica dell'orchestrazione in Databricks di eseguire il codice inviato in un cluster di processi di Azure Databricks in tale area di lavoro.

È possibile usare i provider Git di terze parti più diffusi per il controllo della versione e l'integrazione continua e il recapito continuo o la distribuzione continua (CI/CD) del codice. Per il controllo della versione, questi provider Git includono quanto segue:

Per CI/CD, dbx supporta le seguenti piattaforme CI/CD:

Per illustrare il funzionamento del controllo della versione e di CI/CD, questo articolo descrive come usare Visual Studio Code, dbx e questo esempio di codice, insieme a GitHub e GitHub Actions.

Requisiti di esempio di codice

Per usare questo esempio di codice, è necessario disporre degli elementi seguenti:

  • Un’area di lavoro di Azure Databricks nel tuo account Azure Databricks.
  • Un account GitHub. Creare un account GitHub, se non ne è già disponibile uno.

Inoltre, nel computer di sviluppo è necessario avere quanto segue:

  • Python 3.8 o versioni successive.

    È consigliabile usare una versione di Python corrispondente a quella installata nei cluster di destinazione. Per ottenere la versione di Python installata in un cluster esistente, è possibile usare il terminale Web del cluster per eseguire il comando python --version. Consultare la sezione "Ambiente di sistema" nelle Versioni e compatibilità delle note sulla versione di Databricks Runtime per la versione di Databricks Runtime del cluster obiettivo. In ogni caso, la versione di Python deve essere 3.8 o successiva.

    Per ottenere la versione di Python a cui si fa riferimento nel computer locale, eseguire python --version dal terminale locale. (A seconda della configurazione di Python nel computer locale, in tutto questo articolo potrebbe essere necessario eseguire python3 invece di python.) Vedere anche Selezionare un interprete Python.

  • pip. pip viene installato automaticamente con le versioni più recenti di Python. Per verificare se pip è già installato, eseguire pip --version dal terminale locale. (A seconda della configurazione di Python o di pip nel computer locale, in tutto questo articolo potrebbe essere necessario eseguire pip3 invece di pip.)

  • dbx versione 0.8.0 o successiva. È possibile installare il pacchetto dbx da Python Package Index (PyPI) eseguendo pip install dbx.

    Nota

    Non è necessario installare dbx subito. È possibile installarlo più avanti nella sezione relativa all'installazione dell’esempio di codice.

  • Un metodo per creare ambienti virtuali Python per assicurarsi di usare le versioni corrette di Python e le dipendenze dei pacchetti nei progetti dbx. Questo articolo illustra pipenv.

  • L'interfaccia della riga di comando di Databricks versione 0.18 o successiva, configurata con autenticazione.

    Nota

    Non è necessario installare ora l'interfaccia della riga di comando di Databricks legacy (interfaccia della riga di comando di Databricks versione 0.17). È possibile installarlo più avanti nella sezione relativa all'installazione dell’esempio di codice. Se si vuole installarlo in un secondo momento, è necessario ricordare di configurare l'autenticazione in quel momento.

  • Visual Studio Code.

  • Estensione Python per Visual Studio Code.

  • L'estensione Richieste pull e problemi di GitHub in Visual Studio Code.

  • Git.

Informazioni sull’esempio di codice

L'esempio di codice Python per questo articolo, disponibile nel repository databricks/ide-best-practices in GitHub, esegue le operazioni seguenti:

  1. Ottiene i dati dal repository owid/covid-19-data in GitHub.
  2. Filtra i dati per un codice paese ISO specifico.
  3. Crea una tabella pivot dai dati.
  4. Esegue la pulizia dei dati.
  5. Modularizza la logica del codice in funzioni riutilizzabili.
  6. Esegue l’unit test delle funzioni.
  7. Fornisce dbx configurazioni e impostazioni del progetto per consentire al codice di scrivere i dati in una tabella Delta in un'area di lavoro remota di Azure Databricks.

Configurare l’esempio di codice

Dopo aver soddisfatti i requisiti per questo esempio di codice, completare i passaggi seguenti per iniziare a usare l'esempio di codice.

Nota

Questi passaggi non includono la configurazione di questo esempio di codice per CI/CD. Non è necessario configurare CI/CD per eseguire questo esempio di codice. Se si vuole configurare CI/CD in un secondo momento, vedere Eseguire con GitHub Actions.

Passaggio 1: Creare un ambiente virtuale Python

  1. Creare dal terminale una cartella vuota che contenga un ambiente virtuale per questo esempio di codice. Queste istruzioni usano una cartella padre denominata ide-demo. È possibile assegnare a tale cartella un nome qualsiasi. Se si usa un nome diverso, sostituire il nome in questo articolo. Dopo averla creata, passare alla cartella e quindi avviare Visual Studio Code da tale cartella. Assicurarsi di includere il punto (.) dopo il comando code.

    Per Linux e macOS:

    mkdir ide-demo
cd ide-demo
code .

    Suggerimento

    Se viene visualizzato l'errore command not found: code, vedere Avvio dalla riga di comando nel sito Web di Microsoft.

    Per Windows:

    md ide-demo
cd ide-demo
code .

  2. In Visual Studio Code, sulla barra del menu, scegliere Visualizza > Terminale.

  3. Dalla radice della cartella ide-demo eseguire il comando pipenv con l'opzione seguente, dove <version> è la versione di destinazione di Python già installata in locale (e, idealmente, una versione corrispondente alla versione di Python dei cluster di destinazione), ad esempio 3.8.14.

    pipenv --python <version>

    Prendere nota del valore Virtualenv location nell'output del comando pipenv, perché sarà necessario nel passaggio successivo.

  4. Selezionare l'interprete Python di destinazione e quindi attivare l'ambiente virtuale Python:

    1. Nella barra dei menu fare clic su Visualizza > Riquadro comandi, digitare Python: Select e quindi fare clic su Python: Seleziona interprete.

    2. Selezionare l'interprete Python nel percorso dell'ambiente virtuale Python appena creato. (Questo percorso è elencato come valore Virtualenv location nell'output del comando pipenv.)

    3. Sulla barra dei menu fare clic su Visualizza >riquadro comandi, digitare Terminal: Create e quindi fare clic su Terminale: creare nuovo terminale.

    4. Assicurarsi che il prompt dei comandi indichi che si è nella shell pipenv. Per confermare, dovrebbe essere visualizzato un messaggio simile a (<your-username>) prima del prompt dei comandi. Se non viene visualizzato, eseguire il seguente comando:

      pipenv shell

      Per uscire dalla shell pipenv, eseguire il comando exit e le parentesi scompaiono.

    Per altre informazioni, vedere Usare gli ambienti Python in VS Code nella documentazione di Visual Studio Code.

Passaggio 2: Clonare il codice di esempio da GitHub

  1. In Visual Studio Code aprire la cartella ide-demo (File > Apri cartella), se non è già aperta.
  2. Fare clic su Visualizza > Riquadro comandi, digitare Git: Clone e poi fare clic su Git: Clone.
  3. Per Specificare l'URL del repository o selezionare un'origine repository, digitare https://github.com/databricks/ide-best-practices
  4. Passare alla cartella ide-demo e fare clic su Seleziona percorso repository.

Passaggio 3: Installare le dipendenze dell'esempio di codice

  1. Installare una versione di dbx e dell'interfaccia della riga di comando Databricks versione 0.18 o successiva compatibile con la versione di Python. A tale scopo, in Visual Studio Code dal terminale, dalla cartella ide-demo con una shell pipenv attivata (pipenv shell), eseguire il comando seguente:

    pip install dbx

  2. Verificare che dbx sia installato. A tale scopo, usare il comando seguente:

    dbx --version

    Se viene restituito il numero di versione, dbx viene installato.

    Se il numero di versione è inferiore a 0.8.0, eseguire l'aggiornamento dbx con il comando seguente e quindi controllare di nuovo il numero di versione:

    pip install dbx --upgrade
dbx --version

# Or ...
python -m pip install dbx --upgrade
dbx --version

  3. Quando si installa dbx, viene installata automaticamente anche l'interfaccia della riga di comando di Databricks legacy (versione 0.17). Per verificare che l'interfaccia della riga di comando di Databricks legacy (versione 0.17) sia installata, eseguire il comando seguente:

    databricks --version

    Se viene restituita la versione 0.17 dell'interfaccia della riga di comando di Databricks legacy, significa che l'interfaccia della riga di comando di Databricks legacy è stata installata.

  4. Se non è stata configurata l'interfaccia della riga di comando di Databricks legacy (versione 0.17) con l'autenticazione, è necessario farlo ora. Per verificare che l'autenticazione sia configurata, eseguire il comando di base seguente per ottenere alcune informazioni di riepilogo sull'area di lavoro di Azure Databricks. Assicurarsi di includere la barra (/) dopo il sottocomando ls:

    databricks workspace ls /

    Se viene restituito un elenco di nomi di cartelle a livello radice per l'area di lavoro, l'autenticazione è configurata.

  5. Installare i pacchetti Python da cui dipende questo esempio di codice. A tale scopo, eseguire il comando seguente dalla cartella ide-demo/ide-best-practices:

    pip install -r unit-requirements.txt

  6. Verificare che i pacchetti dipendenti dell'esempio di codice siano installati. A tale scopo, usare il comando seguente:

    pip list

    Se i pacchetti elencati nei file requirements.txt e unit-requirements.txt si trovano in un punto qualsiasi di questo elenco, allora vengono installati i pacchetti dipendenti.

    Nota

    I file elencati in requirements.txt sono per versioni specifiche del pacchetto. Per una migliore compatibilità, è possibile fare riferimento incrociato tra queste versioni e il tipo di nodo del cluster che si vuole usare in un secondo momento nell'area di lavoro di Azure Databricks per l'esecuzione delle distribuzioni. Consultare la sezione "Ambiente di sistema" per la versione di Databricks Runtime del cluster in Versioni e compatibilità delle note sulla versione di Databricks Runtime.

Passaggio 4: Personalizzare l'esempio di codice per l'area di lavoro di Azure Databricks

  1. Personalizzare le impostazioni del progetto del dbx repository. A tale scopo, nel file .dbx/project.json modificare il valore dell'oggetto profile da DEFAULT al nome del profilo corrispondente a quello configurato per l'autenticazione con l'interfaccia della riga di comando di Databricks legacy (versione 0.17). Se non è stato configurato alcun profilo non predefinito, lasciare DEFAULT invariato. Ad esempio:

    {
  "environments": {
    "default": {
      "profile": "DEFAULT",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/covid_analysis",
        "artifact_location": "dbfs:/Shared/dbx/projects/covid_analysis"
      }
    }
  },
  "inplace_jinja_support": false
}

  2. Personalizzare le dbx impostazioni di distribuzione del progetto. A tale scopo, nel file conf/deployment.yml modificare il valore degli oggetti spark_version e node_type_id da 10.4.x-scala2.12 e m6gd.large alla stringa di versione del runtime di Azure Databricks e al tipo di nodo del cluster in cui si vuole usare l'area di lavoro di Azure Databricks per l'esecuzione delle distribuzioni.

    Ad esempio, per specificare Databricks Runtime 10.4 LTS e un tipo di nodo Standard_DS3_v2:

    environments:
  default:
    workflows:
      - name: 'covid_analysis_etl_integ'
        new_cluster:
          spark_version: '10.4.x-scala2.12'
          num_workers: 1
        node_type_id: 'Standard_DS3_v2'
        spark_python_task:
          python_file: 'file://jobs/covid_trends_job.py'
      - name: 'covid_analysis_etl_prod'
        new_cluster:
          spark_version: '10.4.x-scala2.12'
          num_workers: 1
          node_type_id: 'Standard_DS3_v2'
          spark_python_task:
            python_file: 'file://jobs/covid_trends_job.py'
          parameters: ['--prod']
      - name: 'covid_analysis_etl_raw'
        new_cluster:
          spark_version: '10.4.x-scala2.12'
          num_workers: 1
          node_type_id: 'Standard_DS3_v2'
          spark_python_task:
            python_file: 'file://jobs/covid_trends_job_raw.py'

Suggerimento

In questo esempio, ognuna di queste tre definizioni di processo ha lo stesso valore spark_version e node_type_id. È possibile usare valori diversi per definizioni di processo diverse. È anche possibile creare valori condivisi e riutilizzarli tra definizioni di processo, per ridurre gli errori di digitazione e la manutenzione del codice. Vedere l'esempio YAML nella dbx documentazione.

Esplorare l’esempio di codice

Dopo aver configurato l'esempio di codice, usare le informazioni seguenti per scoprire come funzionano i vari file nella cartella ide-demo/ide-best-practices.

Modularizzazione del codice

Codice non-modulato

Il file jobs/covid_trends_job_raw.py è una versione non-modulata della logica del codice. È possibile eseguire questo file da solo.

Codice modularizzato

Il file jobs/covid_trends_job.py è una versione modularizzata della logica del codice. Questo file si basa sul codice condiviso nel file covid_analysis/transforms.py. Il file covid_analysis/__init__.py considera la cartella covide_analysis come pacchetto contenitore.

Test

Unit test

Il file tests/testdata.csv contiene una piccola parte dei dati nel file covid-hospitalizations.csv a scopo di test. Il file tests/transforms_test.py contiene gli unit test per il file covid_analysis/transforms.py.

Strumento di esecuzione dell’unit test

Il file pytest.ini contiene le opzioni di configurazione per l'esecuzione di test con pytest. Vedere pytest.ini e opzioni di configurazione nella documentazione pytest.

Il file .coveragerc contiene opzioni di configurazione per le misurazioni di code coverage Python con coverage.py. Vedere Informazioni di riferimento sulla configurazione nella documentazione coverage.py.

Il file requirements.txt, che è un subset del file unit-requirements.txt eseguito in precedenza con pip, contiene un elenco di pacchetti da cui dipendono anche gli unit test.

Packaging

Il file setup.py fornisce i comandi da eseguire nella console (script della console), ad esempio il comando pip, per la creazione di pacchetti di progetti Python con setuptools. Vedere Punti di ingresso nella documentazione setuptools.

Altri file

In questo esempio di codice sono presenti altri file che non sono stati descritti in precedenza:

  • La cartella .github/workflows contiene tre file, databricks_pull_request_tests.yml, onpush.yml e onrelease.yaml, che rappresentano GitHub Actions, illustrati più avanti nella sezione GitHub Actions .
  • Il file .gitignore contiene un elenco di cartelle e file locali ignorati da Git per il repository.

Eseguire il codice di esempio

È possibile usare dbx nel computer locale per indicare ad Azure Databricks di eseguire l'esempio di codice su richiesta nell'area di lavoro remota, come descritto nella sottosezione successiva. In alternativa, è possibile usare GitHub Actions per fare in modo che GitHub esegua l'esempio di codice ogni volta che si esegue il push delle modifiche al repository GitHub.

Eseguire con dbx

  1. Installare il contenuto della cartella covid_analysis come pacchetto in setuptools modalità di sviluppo Python eseguendo il comando seguente dalla radice del progetto dbx, ad esempio la cartella ide-demo/ide-best-practices. Assicurarsi di includere il punto (.) alla fine di questo comando:

    pip install -e .

    Questo comando crea una cartella covid_analysis.egg-info che contiene informazioni sulla versione compilata dei file covid_analysis/__init__.py e covid_analysis/transforms.py.

  2. Eseguire i test dal comando seguente:

    pytest tests/

    I risultati dei test vengono visualizzati nel terminale. Tutti e quattro i test devono essere visualizzati come superati.

    Suggerimento

    Per altri approcci ai test, inclusi i test per i notebook R e Scala, vedere Unit testing per i notebook.

  3. Facoltativamente, ottenere le metriche di copertura dei test eseguendo il comando seguente:

    coverage run -m pytest tests/

    Nota

    Se viene visualizzato un messaggio che coverage non è possibile trovare, eseguire pip install coverage e riprovare.

    Per visualizzare i risultati della copertura dei test, eseguire il comando seguente:

    coverage report -m

  4. Se tutti e quattro i test vengono superati, inviare il dbx contenuto del progetto all'area di lavoro di Azure Databricks eseguendo il comando seguente:

    dbx deploy --environment=default

    Le informazioni sul progetto e le relative esecuzioni vengono inviate al percorso specificato nell'oggetto workspace_directory nel file .dbx/project.json.

    Il contenuto del progetto viene inviato al percorso specificato nell'oggetto artifact_location nel file .dbx/project.json.

  5. Eseguire la versione di pre-produzione del codice nell'area di lavoro con il comando seguente:

    dbx launch covid_analysis_etl_integ

    Nel terminale viene visualizzato un collegamento ai risultati dell'esecuzione. L'output dovrebbe essere simile al seguente:

    https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345

    Seguire questo collegamento nel Web browser per visualizzare i risultati dell'esecuzione nell'area di lavoro.

  6. Eseguire la versione di produzione del codice nell'area di lavoro con il comando seguente:

    dbx launch covid_analysis_etl_prod

    Nel terminale viene visualizzato un collegamento ai risultati dell'esecuzione. L'output dovrebbe essere simile al seguente:

    https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456

    Seguire questo collegamento nel Web browser per visualizzare i risultati dell'esecuzione nell'area di lavoro.

Eseguire con GitHub Actions

Nella cartella del .github/workflows progetto, i file GitHub Actions onpush.yml e onrelease.yml eseguono le operazioni seguenti:

  • In ogni push di un tag che inizia con v, usa dbx per distribuire il processo covid_analysis_etl_prod.
  • In ogni push che non è di un tag che inizia con v:
    1. Usa pytest per eseguire gli unit test.
    2. Usa dbx per distribuire il file specificato nel processo covid_analysis_etl_integ nell'area di lavoro remota.
    3. Usa dbx per avviare il file già distribuito specificato nel processo covid_analysis_etl_integ nell'area di lavoro remota, tracciando l'esecuzione fino al termine.

Nota

Un file GitHub Actions aggiuntivo, databricks_pull_request_tests.yml, viene fornito come modello per sperimentare, senza influire sui file GitHub Actions onpush.yml e onrelease.yml. È possibile eseguire questo esempio di codice senza il databricks_pull_request_tests.yml file GitHub Actions. Il suo utilizzo non è trattato in questo articolo.

Le sottosezioni seguenti descrivono come configurare ed eseguire i file GitHub Actions onpush.yml e onrelease.yml.

Configurare per usare GitHub Actions

Configurare l'area di lavoro di Azure Databricks seguendo le istruzioni riportate in Entità servizio per CI/CD. Sono incluse le azioni seguenti:

  1. Creare un'entità servizio.
  2. Creare un token di Microsoft Entra ID per l’entità servizio.

Come procedura consigliata per la sicurezza, Databricks consiglia di usare un token di Microsoft Entra ID per un'entità servizio, anziché il token di accesso personale di Databricks per l'utente dell'area di lavoro, in modo da consentire a GitHub di eseguire l'autenticazione con l'area di lavoro di Azure Databricks.

Dopo aver creato l'entità servizio e il relativo token di Microsoft Entra ID, fermarsi e prendere nota del valore del token, che verrà usato nella sezione successiva.

Eseguire GitHub Actions

Passaggio 1: Pubblicare il repository clonato
  1. Nella barra laterale di Visual Studio Code fare clic sull'icona GitHub. Se l'icona non è visibile, abilitare prima l'estensione Richieste pull e problemi di GitHub tramite la visualizzazione Estensioni (Visualizza > Estensioni).
  2. Se il pulsante Accedi è visibile, cliccarlo e seguire le istruzioni visualizzate per accedere all'account GitHub.
  3. Sulla barra dei menu fare clic su Visualizza >Riquadro comandi, digitare Publish to GitHub e quindi fare clic su Pubblica in GitHub.
  4. Selezionare un'opzione per pubblicare il repository clonato nell'account GitHub.
Passaggio 2: Aggiungere segreti crittografati al repository

Nel sito Web di GitHub per il repository pubblicato seguire le istruzioni in Creazione di segreti crittografati per un repository per i seguenti segreti crittografati:

  • Creare un segreto crittografato denominato DATABRICKS_HOST, impostato sul valore dell'URL per area di lavoro, ad esempio https://adb-1234567890123456.7.azuredatabricks.net.
  • Creare un segreto crittografato denominato DATABRICKS_TOKEN, impostato sul valore del token di Microsoft Entra ID per l'entità servizio.
Passaggio 3: Creare e pubblicare un ramo nel repository
  1. In Visual Studio Code, nella visualizzazione Controllo del codice sorgente (Visualizza > controllo del codice sorgente), fare clic sull'icona ... (Visualizzazioni e altre azioni).
  2. Fare clic su Ramo >Crea ramo da.
  3. Immettere un nome per il ramo, ad esempio my-branch.
  4. Selezionare da dove creare il ramo, ad esempio main.
  5. Apportare una modifica secondaria a uno dei file nel repository locale e quindi salvare il file. Ad esempio, apportare una modifica secondaria a un commento di codice nel file tests/transforms_test.py.
  6. Nella visualizzazione Controllo del codice sorgente, fare di nuovo clic sull'icona ... (Visualizzazioni e Altre azioni).
  7. Fare clic su Cambia > Prepara tutte le modifiche.
  8. Fare di nuovo clic sull'icona ... (Visualizzazioni e Altre azioni).
  9. Fare clic su Commit > Commit Staged.
  10. Immettere un messaggio per il commit.
  11. Fare di nuovo clic sull'icona ... (Visualizzazioni e Altre azioni).
  12. Fare clic su Ramo > Pubblica ramo.
Passaggio 4: Creare una richiesta pull e unire
  1. Passare al sito Web GitHub per il repository pubblicato, https://github/<your-GitHub-username>/ide-best-practices.
  2. Nella scheda Richieste pull, accanto a my-branch had recent pushes, fare clic su Confronta e richiesta pull.
  3. Fare clic su Crea richiesta pull.
  4. Nella pagina della richiesta pull attendere che l'icona accanto a CI pipleline/ci-pipeline (push) visualizzi un segno di spunta verde. La visualizzazione dell'icona potrebbe richiedere alcuni minuti. Se è presente una X rossa anziché un segno di spunta verde, fare clic su Dettagli per scoprire perché. Se l'icona o Dettagli non vengono più visualizzati, fare clic su Mostra tutti i controlli.
  5. Se viene visualizzato il segno di spunta verde, unire la richiesta pull nel ramo main facendo clic su Unisci richiesta pull.