Använda dbx med Visual Studio Code

Den här artikeln beskriver ett Python-baserat kodexempel som du kan arbeta med i valfri Python-kompatibel IDE. Mer specifikt beskriver den här artikeln hur du arbetar med det här kodexemplet i Visual Studio Code, som innehåller följande produktivitetsfunktioner för utvecklare:

• Kod har slutförts
• Lintning
• Test
• Felsöka kodobjekt som inte kräver en realtidsanslutning till fjärranslutna Azure Databricks-resurser.

Den här artikeln använder dbx by Databricks Labs tillsammans med Visual Studio Code för att skicka kodexemplet till en fjärransluten Azure Databricks-arbetsyta. dbx instruerar Azure Databricks att Översikt över orkestrering på Databricks att köra den skickade koden på ett Azure Databricks-jobbkluster på den arbetsytan.

Du kan använda populära Git-leverantörer från tredje part för versionskontroll och kontinuerlig integrering och kontinuerlig leverans eller kontinuerlig distribution (CI/CD) av koden. För versionskontroll omfattar dessa Git-leverantörer följande:

• GitHub
• Bitbucket
• GitLab
• Azure DevOps (inte tillgängligt i Azure Kina-regioner)
• AWS CodeCommit
• GitHub AE

För CI/CD dbx stöder följande CI/CD-plattformar:

• GitHub Actions
• Azure Pipelines
• GitLab CI/CD

För att visa hur versionskontroll och CI/CD kan fungera beskriver den här artikeln hur du använder Visual Studio Code, dbxoch det här kodexemplet, tillsammans med GitHub och GitHub Actions.

Krav för kodexempel

Om du vill använda det här kodexemplet måste du ha följande:

• En Azure Databricks-arbetsyta i ditt Azure Databricks-konto.
• Ett GitHub-konto. Skapa ett GitHub-konto om du inte redan har ett.

På din lokala utvecklingsdator måste du dessutom ha följande:

• Python version 3.8 eller senare.

  Du bör använda en version av Python som matchar den som är installerad på dina målkluster. Om du vill hämta den version av Python som är installerad i ett befintligt kluster kan du använda klustrets webbterminal för att köra python --version kommandot. Se även avsnittet "Systemmiljö" i versionsanteckningarna för Databricks Runtime och kompatibilitet för Databricks Runtime-versionen för dina målkluster. I vilket fall som helst måste versionen av Python vara 3.8 eller senare.

  Om du vill hämta den version av Python som för närvarande refereras till på den lokala datorn kör python --version du från den lokala terminalen. (Beroende på hur du konfigurerar Python på din lokala dator kan du behöva köra python3 i stället för python i den här artikeln.) Se även Välj en Python-tolk.

• pip. pip installeras automatiskt med nyare versioner av Python. Om du vill kontrollera om pip det redan är installerat kör du pip --version från den lokala terminalen. (Beroende på hur du konfigurerar Python eller pip på din lokala dator kan du behöva köra pip3 i stället för pip i den här artikeln.)

• dbx version 0.8.0 eller senare. Du kan installera dbx paketet från Python Package Index (PyPI) genom att köra pip install dbx.

  Kommentar

  Du behöver inte installera dbx nu. Du kan installera det senare i avsnittet för konfiguration av kodexempel.

• En metod för att skapa virtuella Python-miljöer för att säkerställa att du använder rätt versioner av Python och paketberoenden i dina dbx projekt. Den här artikeln beskriver pipenv.

• Databricks CLI version 0.18 eller senare, konfigurerad med autentisering.

  Kommentar

  Du behöver inte installera det äldre Databricks CLI (Databricks CLI version 0.17) nu. Du kan installera det senare i avsnittet för konfiguration av kodexempel. Om du vill installera den senare måste du komma ihåg att konfigurera autentisering vid den tidpunkten i stället.

• Visual Studio Code.

• Python-tillägget för Visual Studio Code.

• GitHub Pull Requests and Issues-tillägget för Visual Studio Code.

• Git.

Om kodexemplet

Python-kodexemplet för den här artikeln, som finns i lagringsplatsen databricks/ide-best-practices i GitHub, gör följande:

1. Hämtar data från lagringsplatsen owid/covid-19-data i GitHub.
2. Filtrerar data för en specifik ISO-landskod.
3. Skapar en pivottabell från data.
4. Utför datarensning på data.
5. Modulariserar kodlogik till återanvändbara funktioner.
6. Enheten testar funktionerna.
7. Tillhandahåller dbx projektkonfigurationer och inställningar för att aktivera koden för att skriva data till en Delta-tabell på en fjärransluten Azure Databricks-arbetsyta.

Konfigurera kodexemplet

När du har kraven för det här kodexemplet slutför du följande steg för att börja använda kodexemplet.

Steg 1: Skapa en virtuell Python-miljö

1. Från terminalen skapar du en tom mapp som ska innehålla en virtuell miljö för det här kodexemplet. De här anvisningarna använder en överordnad mapp med namnet ide-demo. Du kan ge den här mappen valfritt namn. Om du använder ett annat namn ersätter du namnet i den här artikeln. När du har skapat mappen växlar du till den och startar sedan Visual Studio Code från den mappen. Se till att inkludera punkten (.) efter code kommandot.

   För Linux och macOS:

   mkdir ide-demo
   cd ide-demo
   code .
   

   Dricks

   Om du får felet command not found: codeläser du Starta från kommandoraden på Microsofts webbplats.

   För Windows:

   md ide-demo
   cd ide-demo
   code .
   

2. I Visual Studio Code går du till menyraden och klickar på Visa > terminal.

3. Från mappens ide-demo rot kör pipenv du kommandot med följande alternativ, där <version> är målversionen av Python som du redan har installerat lokalt (och helst en version som matchar dina målklusters version av Python), till exempel 3.8.14.

   pipenv --python <version>
   

   Anteckna värdet Virtualenv location i kommandots pipenv utdata, eftersom du behöver det i nästa steg.

4. Välj Python-måltolkaren och aktivera sedan den virtuella Python-miljön:

   1. På menyraden klickar du på Visa > kommandopalett, skriver Python: Selectoch klickar sedan på Python: Välj tolk.

   2. Välj Python-tolken i sökvägen till den virtuella Python-miljö som du nyss skapade. (Den här sökvägen visas som Virtualenv location värdet i kommandots pipenv utdata.)

   3. På menyraden klickar du på Visa > kommandopalett, skriver Terminal: Createoch klickar sedan på Terminal: Skapa ny terminal.

   4. Kontrollera att kommandotolken anger att du är i pipenv gränssnittet. För att bekräfta bör du se något som liknar (<your-username>) före kommandotolken. Om du inte ser det kör du följande kommando:

      pipenv shell
      

      Om du vill avsluta pipenv gränssnittet kör du kommandot exitoch parenteserna försvinner.

   Mer information finns i Använda Python-miljöer i VS Code i Visual Studio Code-dokumentationen.

Steg 2: Klona kodexemplet från GitHub

1. Öppna mappen (ide-demo>) i Visual Studio Code om den inte redan är öppen.
2. Klicka på Visa > kommandopalett, skriv Git: Cloneoch klicka sedan på Git: Klona.
3. Ange en lagringsplatskälla för Ange lagringsplats-URL eller välj en lagringsplatskällahttps://github.com/databricks/ide-best-practices
4. Bläddra till mappen ide-demo och klicka på Välj lagringsplats.

Steg 3: Installera kodexemplets beroenden

1. Installera en version av dbx och Databricks CLI version 0.18 eller senare som är kompatibel med din version av Python. För att göra detta kör du följande kommando i Visual Studio Code från terminalen från din ide-demo mapp med ett pipenv gränssnitt aktiverat (pipenv shell):

   pip install dbx
   

2. Bekräfta att är dbx installerat. Gör detta genom att köra följande kommando:

   dbx --version
   

   Om versionsnumret returneras dbx installeras.

   Om versionsnumret är lägre än 0.8.0 uppgraderar dbx du genom att köra följande kommando och kontrollerar sedan versionsnumret igen:

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

3. När du installerar dbxinstalleras även äldre Databricks CLI (Databricks CLI version 0.17) automatiskt. Kontrollera att det äldre Databricks CLI (Databricks CLI version 0.17) är installerat genom att köra följande kommando:

   databricks --version
   

   Om Databricks CLI version 0.17 returneras installeras det äldre Databricks CLI.

4. Om du inte har konfigurerat äldre Databricks CLI (Databricks CLI version 0.17) med autentisering måste du göra det nu. Bekräfta att autentiseringen har konfigurerats genom att köra följande grundläggande kommando för att hämta sammanfattningsinformation om din Azure Databricks-arbetsyta. Se till att inkludera snedstrecket (/) efter ls underkommandot:

   databricks workspace ls /
   

   Om en lista över mappnamn på rotnivå för arbetsytan returneras konfigureras autentisering.

5. Installera De Python-paket som det här kodexemplet är beroende av. Det gör du genom att köra följande kommando från ide-demo/ide-best-practices mappen:

   pip install -r unit-requirements.txt
   

6. Bekräfta att kodexemplets beroende paket är installerade. Gör detta genom att köra följande kommando:

   pip list
   

   Om de paket som visas i requirements.txt filerna och unit-requirements.txt finns någonstans i den här listan installeras de beroende paketen.

   Kommentar

   Filerna som anges i requirements.txt är för specifika paketversioner. För bättre kompatibilitet kan du korsreferensera dessa versioner med den klusternodtyp som du vill att din Azure Databricks-arbetsyta ska använda för att köra distributioner senare. Se avsnittet "Systemmiljö" för ditt klusters Databricks Runtime-version i Databricks Runtime versionsanteckningar och kompatibilitet.

Steg 4: Anpassa kodexemplet för din Azure Databricks-arbetsyta

1. Anpassa lagringsplatsens dbx projektinställningar. För att göra detta ändrar du värdet .dbx/project.json för objektet från profileDEFAULT till namnet på profilen som matchar det som du har konfigurerat för autentisering med äldre Databricks CLI (Databricks CLI version 0.17). Om du inte har konfigurerat någon profil som inte är standard lämnar DEFAULT du som den är. Till exempel:

   {
     "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. dbx Anpassa projektets distributionsinställningar. För att göra detta i conf/deployment.yml filen ändrar du värdet för objekten spark_version och node_type_id från 10.4.x-scala2.12 och m6gd.large till versionssträngen för Azure Databricks-körningen och klusternodtypen som du vill att din Azure Databricks-arbetsyta ska använda för att köra distributioner på.

   Om du till exempel vill ange Databricks Runtime 10.4 LTS och en Standard_DS3_v2 nodtyp:

   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'
   

Utforska kodexemplet

När du har konfigurerat kodexemplet använder du följande information för att lära dig hur de olika filerna i ide-demo/ide-best-practices mappen fungerar.

Kod modularisering

Omodulerad kod

Filen jobs/covid_trends_job_raw.py är en omodulerad version av kodlogik. Du kan köra den här filen på egen hand.

Modulariserad kod

Filen jobs/covid_trends_job.py är en modulariserad version av kodlogik. Den här filen förlitar sig på den delade koden i covid_analysis/transforms.py filen. Filen covid_analysis/__init__.py behandlar covide_analysis mappen som ett innehållande paket.

Testning

Enhetstest

Filen tests/testdata.csv innehåller en liten del av data i covid-hospitalizations.csv filen i testsyfte. Filen tests/transforms_test.py innehåller enhetstesterna covid_analysis/transforms.py för filen.

Enhetstestkörare

Filen pytest.ini innehåller konfigurationsalternativ för att köra tester med pytest. Se pytest.ini och konfigurationsalternativ i dokumentationen pytest .

Filen .coveragerc innehåller konfigurationsalternativ för Python-kodtäckningsmätningar med coverage.py. Se Konfigurationsreferens i dokumentationen coverage.py .

Filen requirements.txt , som är en delmängd av unit-requirements.txt filen som du körde tidigare med pip, innehåller en lista över paket som enhetstesterna också är beroende av.

Paketering

Filen setup.py innehåller kommandon som ska köras i konsolen (konsolskript), till exempel pip kommandot, för att paketera Python-projekt med setuptools. Se Startpunkter i dokumentationen setuptools .

Andra filer

Det finns andra filer i det här kodexemplet som inte har beskrivits tidigare:

• Mappen .github/workflows innehåller tre filer, databricks_pull_request_tests.yml, onpush.ymloch onrelease.yaml, som representerar GitHub Actions, som beskrivs senare i avsnittet GitHub Actions .
• Filen .gitignore innehåller en lista över lokala mappar och filer som Git ignorerar för lagringsplatsen.

Kör kodexemplet

Du kan använda dbx på din lokala dator för att instruera Azure Databricks att köra kodexemplet på fjärrarbetsytan på begäran, enligt beskrivningen i nästa underavsnitt. Eller så kan du använda GitHub Actions för att låta GitHub köra kodexemplet varje gång du skickar kodändringar till din GitHub-lagringsplats.

Kör med dbx

1. Installera innehållet i covid_analysis mappen som ett paket i Python-utvecklingsläge setuptoolsgenom att köra följande kommando från roten i projektet dbx (till exempel ide-demo/ide-best-practices mappen). Se till att inkludera punkten (.) i slutet av det här kommandot:

   pip install -e .
   

   Det här kommandot skapar en covid_analysis.egg-info mapp som innehåller information om den kompilerade versionen av covid_analysis/__init__.py filerna och covid_analysis/transforms.py .

2. Kör testerna genom att köra följande kommando:

   pytest tests/
   

   Testresultaten visas i terminalen. Alla fyra testerna bör visas som övergående.

   Dricks

   Ytterligare metoder för testning, inklusive testning för R- och Scala-notebook-filer, finns i Enhetstestning för notebook-filer.

3. Du kan också hämta testtäckningsmått för dina tester genom att köra följande kommando:

   coverage run -m pytest tests/
   

   Kommentar

   Om ett meddelande visas som coverage inte kan hittas kör du pip install coverageoch försöker igen.

   Om du vill visa testtäckningsresultat kör du följande kommando:

   coverage report -m
   

4. Om alla fyra testerna godkänns skickar dbx du projektets innehåll till din Azure Databricks-arbetsyta genom att köra följande kommando:

   dbx deploy --environment=default
   

   Information om projektet och dess körningar skickas till den plats som anges i workspace_directory objektet i .dbx/project.json filen.

   Projektets innehåll skickas till den plats som anges i artifact_location objektet i .dbx/project.json filen.

5. Kör förproduktionsversionen av koden på arbetsytan genom att köra följande kommando:

   dbx launch covid_analysis_etl_integ
   

   En länk till körningens resultat visas i terminalen. Den bör se ut ungefär så här:

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

   Följ den här länken i webbläsaren för att se körningens resultat på din arbetsyta.

6. Kör produktionsversionen av koden på din arbetsyta genom att köra följande kommando:

   dbx launch covid_analysis_etl_prod
   

   En länk till körningens resultat visas i terminalen. Den bör se ut ungefär så här:

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

   Följ den här länken i webbläsaren för att se körningens resultat på din arbetsyta.

Köra med GitHub Actions

I projektets .github/workflows mapp onpush.yml gör GitHub Actions-filerna och onrelease.yml följande:

• På varje push-överföring till en tagg som börjar med vanvänder dbx du för att distribuera covid_analysis_etl_prod jobbet.
• På varje push-överföring som inte är till en tagg som börjar med v:
  1. Använder pytest för att köra enhetstesterna.
  2. Använder dbx för att distribuera filen som anges i covid_analysis_etl_integ jobbet till fjärrarbetsytan.
  3. Använder dbx för att starta den redan distribuerade filen som anges i covid_analysis_etl_integ jobbet på fjärrarbetsytan och spåra den här körningen tills den är klar.

Följande underavsnitt beskriver hur du konfigurerar och kör onpush.yml GitHub Actions-filerna och onrelease.yml .

Konfigurera för att använda GitHub Actions

Konfigurera din Azure Databricks-arbetsyta genom att följa anvisningarna i Tjänstens huvudnamn för CI/CD. Detta omfattar följande åtgärder:

1. Skapa ett huvudnamn för tjänsten.
2. Skapa en Microsoft Entra-ID-token för tjänstens huvudnamn.

Som bästa säkerhet rekommenderar Databricks att du använder en Microsoft Entra-ID-token för tjänstens huvudnamn, i stället för databricks personliga åtkomsttoken för din arbetsyteanvändare, för att göra det möjligt för GitHub att autentisera med din Azure Databricks-arbetsyta.

När du har skapat tjänstens huvudnamn och dess Microsoft Entra-ID-token stoppar du och antecknar tokenvärdet För Microsoft Entra-ID som du ska använda i nästa avsnitt.

Kör GitHub Actions

Steg 1: Publicera din klonade lagringsplats

1. Klicka på GitHub-ikonen i sidofältet i Visual Studio Code. Om ikonen inte visas aktiverar du tillägget GitHub Pull Requests and Issues (GitHub Pull Requests and Issues) via tilläggsvyn (Visa > tillägg) först.
2. Om knappen Logga in visas klickar du på den och följer anvisningarna på skärmen för att logga in på ditt GitHub-konto.
3. På menyraden klickar du på Visa > kommandopalett, skriver Publish to GitHuboch klickar sedan på Publicera på GitHub.
4. Välj ett alternativ för att publicera din klonade lagringsplats till ditt GitHub-konto.

Steg 2: Lägga till krypterade hemligheter i lagringsplatsen

På GitHub-webbplatsen för din publicerade lagringsplats följer du anvisningarna i Skapa krypterade hemligheter för en lagringsplats för följande krypterade hemligheter:

• Skapa en krypterad hemlighet med namnet DATABRICKS_HOST, inställt på värdet för url:en per arbetsyta, till exempel https://adb-1234567890123456.7.azuredatabricks.net.
• Skapa en krypterad hemlighet med namnet DATABRICKS_TOKEN, inställt på värdet för Microsoft Entra ID-token för tjänstens huvudnamn.

Steg 3: Skapa och publicera en gren till lagringsplatsen

1. I Visual Studio Code i vyn Källkontroll (Visa > källkontroll) klickar du på ikonen ... (Vyer och fler åtgärder).
2. Klicka på Gren > Skapa gren från.
3. Ange ett namn för grenen, till exempel my-branch.
4. Välj grenen för att skapa grenen från, till exempel main.
5. Gör en mindre ändring i en av filerna på din lokala lagringsplats och spara sedan filen. Du kan till exempel göra en mindre ändring i en kodkommentare i tests/transforms_test.py filen.
6. I vyn Källkontroll klickar du på ikonen ... (Vyer och fler åtgärder) igen.
7. Klicka på Ändringar > Mellanlagra alla ändringar.
8. Klicka på ikonen ... (Vyer och fler åtgärder) igen.
9. Klicka på Checka in > mellanlagrad incheckning.
10. Ange ett meddelande för incheckningen.
11. Klicka på ikonen ... (Vyer och fler åtgärder) igen.
12. Klicka på Grenpubliceringsgren>.

Steg 4: Skapa en pull-begäran och slå samman

1. Gå till GitHub-webbplatsen för din publicerade lagringsplats, https://github/<your-GitHub-username>/ide-best-practices.
2. På fliken Pull-begäranden bredvid my-branchen har de senaste push-meddelandena klickar du på Jämför och pull-begäran.
3. Klicka på Skapa pull-begäran.
4. På sidan pull-begäran väntar du på att ikonen bredvid CI-pipleline/ci-pipeline (push) ska visa en grön bockmarkering. (Det kan ta några minuter innan ikonen visas.) Om det finns ett rött X i stället för en grön bockmarkering klickar du på Information för att ta reda på varför. Om ikonen eller Informationen inte längre visas klickar du på Visa alla kontroller.
5. Om den gröna bockmarkeringen visas sammanfogar du pull-begäran till grenen main genom att klicka på Koppla pull-begäran.