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 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 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, che fornisce le funzionalità di produttività per sviluppatori seguenti:

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. dbxindica ad Azure Databricks di introduzione ai flussi di lavoro di Azure 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 piattaforme CI/CD seguenti:

Per illustrare il funzionamento del controllo della versione e CI/CD, questo articolo descrive come usare Visual Studio Code, dbxe 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 nell'account Azure Databricks. Creare un'area di lavoro se non ne è già disponibile una.
  • Un account GitHub. Creare un account GitHub, se non ne è già disponibile uno.

Inoltre, nel computer di sviluppo locale è necessario disporre degli elementi seguenti:

  • Python versione 3.8 o successiva.

    È 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 python --version comando . Vedere anche la sezione "Ambiente di sistema" nelle versioni delle note sulla versione di Databricks Runtime e sulla compatibilità per la versione di Databricks Runtime per i cluster di destinazione. 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, potrebbe essere necessario eseguire python3 invece di python tutto questo articolo. 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 pip del computer locale, potrebbe essere necessario eseguire pip3 invece di pip tutto questo articolo.

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

    Nota

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

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

  • L'interfaccia della riga di comando di Databricks versione 0.18 o successiva, configurata con l'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 di 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.

  • Estensione Richieste pull e problemi di GitHub per 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 sui dati.
  5. Modularizza la logica del codice in funzioni riutilizzabili.
  6. 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. Dal terminale creare una cartella vuota per contenere un ambiente virtuale per questo esempio di codice. Queste istruzioni usano una cartella padre denominata ide-demo. È possibile assegnare a questa cartella qualsiasi nome desiderato. Se si usa un nome diverso, sostituire il nome in questo articolo. Dopo aver creato la cartella, passare alla cartella e quindi avviare Visual Studio Code da tale cartella. Assicurarsi di includere il punto (.) dopo il code comando.

    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 Microsoft.

    Per Windows:

    md ide-demo
cd ide-demo
code .

  2. Nella barra dei menu di Visual Studio Code fare clic su Visualizza > terminale.

  3. Dalla radice della ide-demo cartella eseguire il pipenv comando 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 Virtualenv location valore nell'output del pipenv comando, 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: Selecte quindi fare clic su Python: Seleziona interprete.>

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

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

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

      pipenv shell

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

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

Passaggio 2: Clonare l'esempio di codice da GitHub

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

Passaggio 3: Installare le dipendenze dell'esempio di codice

  1. Installare una versione dell'interfaccia della riga di comando di dbx Databricks versione 0.18 o successiva compatibile con la versione di Python. A tale scopo, in Visual Studio Code dal terminale, dalla ide-demo cartella con una pipenv shell 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 alla 0.8.0, eseguire l'aggiornamento dbx eseguendo 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 (interfaccia della riga di comando di Databricks versione 0.17). Per verificare che l'interfaccia della riga di comando di Databricks legacy (interfaccia della riga di comando di Databricks 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, viene installata l'interfaccia della riga di comando di Databricks legacy.

  4. Se non è stata configurata l'interfaccia della riga di comando di Databricks legacy (interfaccia della riga di comando di Databricks 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 ls sottocomando:

    databricks workspace ls /

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

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

    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 requirements.txt file e unit-requirements.txt si trovano in un punto qualsiasi di questo elenco, 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 a queste versioni con il tipo di nodo del cluster che si vuole usare nell'area di lavoro di Azure Databricks per l'esecuzione delle distribuzioni in un secondo momento. Vedere 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 .dbx/project.json file 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 (interfaccia della riga di comando di Databricks 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": "/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 conf/deployment.yml file modificare il valore degli spark_version oggetti 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 Standard_DS3_v2 tipo di nodo:

    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 spark_version valore 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 informazioni sul funzionamento dei vari file nella ide-demo/ide-best-practices cartella.

Modularizzazione del codice

Codice nonmodulato

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

Codice modularizzato

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

Test in corso

Unit test

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

Strumento di esecuzione unit test

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

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

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

Packaging

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

Altri file

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

  • La .github/workflows cartella contiene tre file, databricks_pull_request_tests.yml, onpush.ymle onrelease.yaml, che rappresentano GitHub Actions, illustrati più avanti nella sezione GitHub Actions .
  • Il .gitignore file 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 nell'area di lavoro remota su richiesta, 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 covid_analysis cartella come pacchetto in modalità di sviluppo Python setuptoolseseguendo il comando seguente dalla radice del dbx progetto, ad esempio la ide-demo/ide-best-practices cartella . Assicurarsi di includere il punto (.) alla fine di questo comando:

    pip install -e .

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

  2. Eseguire i test eseguendo il 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 per i test eseguendo il comando seguente:

    coverage run -m pytest tests/

    Nota

    Se viene visualizzato un messaggio che coverage non è possibile trovare, eseguire pip install coveragee 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 .dbx/project.json file.

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

  5. Eseguire la versione di pre-produzione del codice nell'area di lavoro eseguendo 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 eseguendo 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 onpush.yml file e onrelease.yml GitHub Actions eseguono le operazioni seguenti:

  • In ogni push in un tag che inizia con v, usa dbx per distribuire il covid_analysis_etl_prod processo.
  • In ogni push che non si trova in un tag che inizia con v:
    1. pytest Usa per eseguire gli unit test.
    2. dbx Usa per distribuire il file specificato nel processo nell'area covid_analysis_etl_integ di lavoro remota.
    3. dbx Usa per avviare il file già distribuito specificato nel processo nell'area covid_analysis_etl_integ 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 onpush.yml file e onrelease.yml su GitHub Actions. È possibile eseguire questo esempio di codice senza il databricks_pull_request_tests.yml file GitHub Actions. L'utilizzo non è trattato in questo articolo.

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

Configurare per l'uso di 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 ID Microsoft Entra per l'entità servizio.

Come procedura consigliata per la sicurezza, Databricks consiglia di usare un token ID Microsoft Entra per un'entità servizio, anziché il token di accesso personale di Databricks per l'utente dell'area di lavoro, per 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 ID Microsoft Entra, arrestare e prendere nota del valore del token ID Microsoft Entra, 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, fare clic su di esso e seguire le istruzioni visualizzate per accedere all'account GitHub.
  3. Sulla barra dei menu fare clic su Visualizza riquadro comandi, digitare Publish to GitHube 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 GitHub per il repository pubblicato seguire le istruzioni in Creazione di segreti crittografati per un repository per i segreti crittografati seguenti:

  • 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 ID Microsoft Entra 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 Crea > ramo da.
  3. Immettere un nome per il ramo, ad esempio my-branch.
  4. Selezionare il ramo da cui 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 tests/transforms_test.py file.
  6. Nella visualizzazione Controllo del codice sorgente fare di nuovo clic sull'icona ... (Visualizzazioni e Altre azioni).
  7. Fare clic su Cambia > fase tutte le modifiche.
  8. Fare di nuovo clic sull'icona ... (Visualizzazioni e Altre azioni).
  9. Fare clic su Commit Commit Staged (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 Branch Publish Branch .Click Branch Publish Branch>.
Passaggio 4: Creare una richiesta pull e unisci
  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 sono stati inseriti push recenti, 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 i 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 main ramo facendo clic su Unisci richiesta pull.