Dbx gebruiken met Visual Studio Code

In dit artikel wordt een codevoorbeeld op basis van Python beschreven waarmee u kunt werken in elke met Python compatibele IDE. In dit artikel wordt beschreven hoe u met dit codevoorbeeld in Visual Studio Code kunt werken, wat de volgende productiviteitsfuncties voor ontwikkelaars biedt:

• Codeaanvulling
• Linting
• Testen.
• Foutopsporing van codeobjecten waarvoor geen realtime verbinding met externe Azure Databricks-resources is vereist.

In dit artikel wordt dbx door Databricks Labs samen met Visual Studio Code gebruikt om het codevoorbeeld te verzenden naar een externe Azure Databricks-werkruimte. dbxinstrueert Azure Databricks aan Lakeflow-taken om de ingediende code uit te voeren op een Azure Databricks-taakcluster in die werkruimte.

U kunt populaire Git-providers van derden gebruiken voor versiebeheer en continue integratie en continue levering of continue implementatie (CI/CD) van uw code. Voor versiebeheer omvatten deze Git-providers het volgende:

• GitHub
• Bitbucket
• GitLab
• Azure DevOps (niet beschikbaar in Azure China-regio's)
• AWS CodeCommit
• GitHub AE

Voor CI/CD ondersteunt dbx de volgende CI/CD-platforms:

• GitHub Actions
• Azure-pijplijnen
• GitLab CI/CD

Om te laten zien hoe versiebeheer en CI/CD kunnen werken, wordt in dit artikel beschreven hoe u Visual Studio Code dbxen dit codevoorbeeld gebruikt, samen met GitHub en GitHub Actions.

Codevoorbeeldvereisten

Als u dit codevoorbeeld wilt gebruiken, moet u het volgende hebben:

• Een Azure Databricks-werkruimte in uw Azure Databricks-account.
• Een GitHub-account. Maak een GitHub-account als u er nog geen hebt.

Daarnaast moet u op uw lokale ontwikkelcomputer het volgende hebben:

• Python versie 3.8 of hoger.

  U moet een versie van Python gebruiken die overeenkomt met de versie die is geïnstalleerd op uw doelclusters. Als u de versie van Python wilt ophalen die op een bestaand cluster is geïnstalleerd, kunt u de webterminal van het cluster gebruiken om de python --version opdracht uit te voeren. Zie ook de sectie "Systeemomgeving" in de releaseopmerkingen van Databricks Runtime versies en compatibiliteit voor de Databricks Runtime-versie voor uw doelclusters. In elk geval moet de versie van Python 3.8 of hoger zijn.

  Als u de versie van Python wilt ophalen waarnaar momenteel wordt verwezen op uw lokale computer, voert u python --version uit vanuit uw lokale terminal. (Afhankelijk van hoe u Python instelt op uw lokale computer, moet u mogelijk python3 uitvoeren in plaats van python in dit artikel.) Zie ook Een Python-interpreter selecteren.

• pip. pip wordt automatisch geïnstalleerd met nieuwere versies van Python. Om te controleren of pip al is geïnstalleerd, voert u pip --version uit vanuit uw lokale terminal. (Afhankelijk van hoe u Python of pip instelt op uw lokale computer, moet u mogelijk pip3 uitvoeren in plaats van pip in dit artikel.)

• dbx versie 0.8.0 of hoger. U kunt het dbx pakket installeren vanuit de Python Package Index (PyPI) door uit te voeren pip install dbx.

  Notitie

  U hoeft nu niet te installeren dbx . U kunt deze later installeren in de instellingssectie van het codevoorbeeld.

• Een methode voor het maken van virtuele Python-omgevingen om ervoor te zorgen dat u de juiste versies van Python en pakketafhankelijkheden in uw dbx projecten gebruikt. In dit artikel wordt pipenv behandeld.

• De Databricks CLI versie 0.18 of lager, ingesteld met authenticatie.

  Notitie

  U hoeft de verouderde Databricks CLI (Databricks CLI versie 0.17) nu niet te installeren. U kunt deze later installeren in de instellingssectie van het codevoorbeeld. Als u deze later wilt installeren, moet u in plaats daarvan verificatie instellen.

• Visual Studio-code.

• De Python-extensie voor Visual Studio Code.

• De Extensie voor pull-aanvragen en problemen van GitHub voor Visual Studio Code.

• Git.

Over het codevoorbeeld

Het Python-codevoorbeeld voor dit artikel, dat beschikbaar is in de opslagplaats databricks/ide-best practices in GitHub, doet het volgende:

1. Haalt gegevens op uit de opslagplaats owid/covid-19-data in GitHub.
2. Hiermee filtert u de gegevens voor een specifieke ISO-landcode.
3. Hiermee maakt u een draaitabel op basis van de gegevens.
4. Voert gegevensopschoning uit op de gegevens.
5. Modulariseert de codelogica in herbruikbare functies.
6. Eenheid test de functies.
7. Biedt dbx projectconfiguraties en -instellingen om de code in te schakelen voor het schrijven van de gegevens naar een Delta-tabel in een externe Azure Databricks-werkruimte.

Het codevoorbeeld instellen

Nadat u de vereisten voor dit codevoorbeeld hebt ingesteld, voert u de volgende stappen uit om het codevoorbeeld te gaan gebruiken.

Stap 1: Een virtuele Python-omgeving maken

1. Maak vanuit de terminal een lege map die een virtuele omgeving voor dit codevoorbeeld bevat. Deze instructies gebruiken een hoofddirectorie met de naam ide-demo. U kunt deze map elke gewenste naam geven. Als u een andere naam gebruikt, vervangt u de naam in dit artikel. Nadat u de map hebt gemaakt, gaat u naar de map en start u Visual Studio Code vanuit die map. Zorg ervoor dat u de punt (.) na de code opdracht opneemt.

   Voor Linux en macOS:

   mkdir ide-demo
   cd ide-demo
   code .
   

   Aanbeveling

   Als u de fout command not found: codekrijgt, kijk dan naar Starten vanaf de opdrachtregel op de website van Microsoft.

   Voor Windows:

   md ide-demo
   cd ide-demo
   code .
   

2. Klik in Visual Studio Code op de menubalk op Beeld > Terminal.

3. Voer vanuit de hoofdmap van de ide-demo map de pipenv opdracht uit met de volgende optie, waarbij <version> de doelversie van Python is die u al lokaal hebt geïnstalleerd (en, in het ideale voorbeeld, een versie die overeenkomt met de versie van Python van uw doelclusters), bijvoorbeeld 3.8.14.

   pipenv --python <version>
   

   Noteer de Virtualenv location waarde in de uitvoer van de pipenv opdracht, omdat u deze in de volgende stap nodig hebt.

4. Selecteer de Python-doel-interpreter en activeer vervolgens de virtuele Python-omgeving:

   1. Klik in de menubalk op Weergave > Commando Palet, typ Python: Select en klik vervolgens op Python: Selecteer Interpreter.

   2. Selecteer de Python-interpreter in het pad naar de virtuele Python-omgeving die u zojuist hebt gemaakt. (Dit pad wordt vermeld als de Virtualenv location waarde in de uitvoer van de pipenv opdracht.)

   3. Klik op de menubalk op >, typ , en klik vervolgens op Terminal: Create.

   4. Zorg ervoor dat de opdrachtprompt aangeeft dat u zich in de pipenv shell bevindt. Ter bevestiging ziet u iets zoals (<your-username>) vóór de opdrachtprompt. Als u deze niet ziet, voert u de volgende opdracht uit:

      pipenv shell
      

      Als u de shell wilt afsluiten, voert u de pipenv opdracht exituit en verdwijnen de haakjes.

   Zie Python-omgevingen gebruiken in VS Code in de documentatie van Visual Studio Code voor meer informatie.

Stap 2: Het codevoorbeeld klonen vanuit GitHub

1. Open de ide-demo map in Visual Studio Code (Map openen >) als deze nog niet is geopend.
2. Klik op Bekijk > Command Palette, typ Git: Clone, en klik vervolgens op Git: Klonen.
3. Voor De URL van de opslagplaats opgeven of een opslagplaatsbron kiezen, voert u inhttps://github.com/databricks/ide-best-practices
4. Blader naar de map ide-demo en klik op Locatie van opslagplaats selecteren.

Stap 3: De afhankelijkheden van het codevoorbeeld installeren

1. Installeer een versie van dbx en Databricks CLI versie 0.18 of lager die compatibel is met uw versie van Python. Voer hiervoor in Visual Studio Code vanuit uw terminal vanuit uw ide-demo map met een pipenv shell geactiveerd (pipenv shell) de volgende opdracht uit:

   pip install dbx
   

2. Bevestig dat dbx geïnstalleerd is. Voer hiervoor de volgende opdracht uit:

   dbx --version
   

   Als het versienummer wordt geretourneerd, dbx wordt geïnstalleerd.

   Als het versienummer lager is dan 0.8.0, voert u een upgrade dbx uit door de volgende opdracht uit te voeren en controleert u het versienummer opnieuw:

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

3. Wanneer u installeert dbx, wordt de verouderde Databricks CLI (Databricks CLI versie 0.17) ook automatisch geïnstalleerd. Voer de volgende opdracht uit om te controleren of de verouderde Databricks CLI (Databricks CLI versie 0.17) is geïnstalleerd:

   databricks --version
   

   Als Databricks CLI versie 0.17 wordt geretourneerd, wordt de verouderde Databricks CLI geïnstalleerd.

4. Als u de verouderde Databricks CLI (Databricks CLI versie 0.17) niet hebt ingesteld met verificatie, moet u dit nu doen. Voer de volgende basisopdracht uit om te bevestigen dat verificatie is ingesteld om samenvattingsinformatie over uw Azure Databricks-werkruimte op te halen. Zorg ervoor dat u de schuine streep (/) opneemt na de ls subopdracht.

   databricks workspace ls /
   

   Als er een lijst met mapnamen op hoofdniveau voor uw werkruimte wordt geretourneerd, wordt verificatie ingesteld.

5. Installeer de Python-pakketten waarvoor dit codevoorbeeld afhankelijk is. Voer hiervoor de volgende opdracht uit vanuit de ide-demo/ide-best-practices map:

   pip install -r unit-requirements.txt
   

6. Controleer of de afhankelijke pakketten van het codevoorbeeld zijn geïnstalleerd. Voer hiervoor de volgende opdracht uit:

   pip list
   

   Als de pakketten die worden vermeld in de requirements.txt en unit-requirements.txt bestanden zich ergens in deze lijst bevinden, worden de afhankelijke pakketten geïnstalleerd.

   Notitie

   De bestanden die worden vermeld, requirements.txt zijn bedoeld voor specifieke pakketversies. Voor betere compatibiliteit kunt u deze versies kruislings verwijzen naar het clusterknooppunttype dat u wilt gebruiken voor uw Azure Databricks-werkruimte voor het uitvoeren van implementaties later. Zie de sectie Systeemomgeving voor de Databricks Runtime-versie van uw cluster in releaseversies en compatibiliteit van Databricks Runtime.

Stap 4: Het codevoorbeeld voor uw Azure Databricks-werkruimte aanpassen

1. Pas de instellingen van het dbx project van de opslagplaats aan. Hiervoor wijzigt u in het .dbx/project.json bestand de waarde van het profile-object van DEFAULT in de naam van het profiel dat overeenkomt met het profiel dat u hebt ingesteld voor verificatie met de verouderde Databricks CLI (Databricks CLI versie 0.17). Als u geen niet-standaardprofiel hebt ingesteld, laat u DEFAULT zoals dat is. Voorbeeld:

   {
     "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. Pas de implementatie-instellingen van het dbx project aan. Hiervoor wijzigt u in het conf/deployment.yml-bestand de waarden van de spark_version en node_type_id objecten van 10.4.x-scala2.12 en m6gd.large naar de Azure Databricks runtime versie string en clusterknooppunttype die u wilt dat uw Azure Databricks-werkruimte gebruikt voor het uitvoeren van implementaties.

   Als u bijvoorbeeld Databricks Runtime 10.4 LTS en een Standard_DS3_v2 knooppunttype wilt opgeven:

   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'
   

Het codevoorbeeld verkennen

Nadat u het codevoorbeeld hebt ingesteld, kunt u de volgende informatie gebruiken om te leren hoe de verschillende bestanden in de map ide-demo/ide-best-practices werken.

Modularisering van code

Ongemoduleerde code

Het jobs/covid_trends_job_raw.py bestand is een niet-gemodulariseerde versie van de codelogica. U kunt dit bestand zelf uitvoeren.

Modulaire code

Het jobs/covid_trends_job.py bestand is een modulaire versie van de codelogica. Dit bestand is afhankelijk van de gedeelde code in het covid_analysis/transforms.py bestand. Het covid_analysis/__init__.py bestand beschouwt de covide_analysis map als een pakket.

Testen

Eenheidstests

Het tests/testdata.csv bestand bevat een klein deel van de gegevens in het covid-hospitalizations.csv bestand voor testdoeleinden. Het tests/transforms_test.py bestand bevat de eenheidstests voor het covid_analysis/transforms.py bestand.

Eenheidstestloper

Het pytest.ini bestand bevat configuratieopties voor het uitvoeren van tests met pytest. Zie pytest.ini en configuratieopties in de pytest documentatie.

Het .coveragerc bestand bevat configuratieopties voor python-codedekkingsmetingen met coverage.py. Zie Configuratiereferentie in de coverage.py documentatie.

Het requirements.txt-bestand, een subset van het unit-requirements.txt-bestand dat u eerder hebt uitgevoerd met pip, bevat een lijst met pakketten waarvan de eenheidstests ook afhankelijk zijn.

Verpakking

Het setup.py bestand bevat opdrachten die moeten worden uitgevoerd op de console (consolescripts), zoals de opdracht, voor het pip verpakken van Python-projecten met setuptools. Zie Toegangspunten in de setuptools documentatie.

Andere bestanden

Er zijn andere bestanden in dit codevoorbeeld die nog niet eerder zijn beschreven:

• De .github/workflows map bevat drie bestanden, databricks_pull_request_tests.yml, onpush.ymlen onrelease.yaml, die de GitHub Actions vertegenwoordigen, die verderop in de sectie GitHub Actions worden behandeld.
• Het .gitignore-bestand bevat een lijst met lokale mappen en bestanden die Door Git worden genegeerd voor uw opslagplaats.

Het codevoorbeeld uitvoeren

U kunt azure Databricks op uw lokale computer gebruiken dbx om het codevoorbeeld op aanvraag uit te voeren in uw externe werkruimte, zoals beschreven in de volgende subsectie. U kunt Ook GitHub Actions gebruiken om gitHub het codevoorbeeld uit te voeren telkens wanneer u codewijzigingen naar uw GitHub-opslagplaats pusht.

Uitvoeren met dbx

1. Installeer de inhoud van de covid_analysis map als een pakket in de ontwikkelmodus van Python setuptoolsdoor de volgende opdracht uit te voeren vanuit de hoofdmap van uw dbx project (bijvoorbeeld de ide-demo/ide-best-practices map). Zorg ervoor dat u de punt (.) aan het einde van deze opdracht opneemt:

   pip install -e .
   

   Met deze opdracht maakt u een covid_analysis.egg-info map, die informatie bevat over de gecompileerde versie van de covid_analysis/__init__.py en covid_analysis/transforms.py bestanden.

2. Voer de tests uit door de volgende opdracht uit te voeren:

   pytest tests/
   

   De resultaten van de tests worden weergegeven in de terminal. Alle vier de tests moeten worden weergegeven als geslaagd.

   Aanbeveling

   Zie Eenheidstests voor notebooks voor aanvullende methoden voor testen, waaronder testen voor R- en Scala-notebooks.

3. U kunt eventueel metrische gegevens voor de testdekking voor uw tests ophalen door de volgende opdracht uit te voeren:

   coverage run -m pytest tests/
   

   Notitie

   Als een bericht wordt weergegeven dat coverage niet kan worden gevonden, voert u het uit pip install coverageen probeert u het opnieuw.

   Voer de volgende opdracht uit om testdekkingsresultaten weer te geven:

   coverage report -m
   

4. Als alle vier de tests zijn geslaagd, verzendt u de inhoud van het dbx project naar uw Azure Databricks-werkruimte door de volgende opdracht uit te voeren:

   dbx deploy --environment=default
   

   Informatie over het project en de uitvoeringen worden verzonden naar de locatie die is opgegeven in het workspace_directory object in het .dbx/project.json bestand.

   De inhoud van het project wordt verzonden naar de locatie die is opgegeven in het artifact_location object in het .dbx/project.json bestand.

5. Voer de preproductieversie van de code in uw werkruimte uit door de volgende opdracht uit te voeren:

   dbx launch covid_analysis_etl_integ
   

   Er wordt een koppeling naar de resultaten van de run weergegeven in de terminal. Het ziet er ongeveer als volgt uit:

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

   Volg deze koppeling in uw webbrowser om de resultaten van de uitvoering in uw werkruimte te bekijken.

6. Voer de productieversie van de code in uw werkruimte uit door de volgende opdracht uit te voeren:

   dbx launch covid_analysis_etl_prod
   

   Er wordt een koppeling naar de resultaten van de run weergegeven in de terminal. Het ziet er ongeveer als volgt uit:

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

   Volg deze koppeling in uw webbrowser om de resultaten van de uitvoering in uw werkruimte te bekijken.

Uitvoeren met GitHub Actions

In de map .github/workflows van het project doen de onpush.yml en onrelease.yml GitHub Actions-bestanden het volgende:

• Bij elke push naar een tag die begint met v, wordt dbx gebruikt om de covid_analysis_etl_prod taak uit te voeren.
• Bij elke push die niet naar een tag is die begint met v:
  1. Gebruikt pytest om de unittests uit te voeren.
  2. Met dbx implementeert u het bestand dat in de covid_analysis_etl_integ job is opgegeven in de externe werkruimte.
  3. Wordt dbx gebruikt om het al geïmplementeerde bestand te starten dat is opgegeven in de covid_analysis_etl_integ job in de externe werkruimte, waarbij de uitvoering wordt getraceerd totdat deze is voltooid.

In de volgende subsecties wordt beschreven hoe u de onpush.yml- en onrelease.yml GitHub Actions-bestanden instelt en uitvoert.

Instellen voor het gebruik van GitHub Actions

Stel uw Azure Databricks-werkruimte in door de instructies in Service-principals voor CI/CDte volgen. Dit omvat de volgende acties:

1. Een service-principal maken.
2. Maak een Microsoft Entra ID-token voor de service-principal.

Als een beveiligingsbest practice raadt Databricks aan om een Microsoft Entra ID-token voor een service-principal te gebruiken in plaats van het persoonlijke toegangstoken van Databricks voor uw werkruimtegebruiker, om verificatie van GitHub met uw Azure Databricks-werkruimte mogelijk te maken.

Nadat u de service-principal en het bijbehorende Microsoft Entra ID-token hebt gemaakt, stopt u om de waarde van het Microsoft Entra ID-token te noteren, die u in de volgende sectie zult gebruiken.

GitHub Actions uitvoeren

Stap 1: Uw gekloonde opslagplaats publiceren

1. Klik in Visual Studio Code in de zijbalk op het GitHub-pictogram . Als het pictogram niet zichtbaar is, schakelt u eerst de GitHub Pull Requests en Issues extensie in via de Extensions weergave (Weergave > Extensies).
2. Als de knop Aanmelden zichtbaar is, klikt u erop en volgt u de instructies op het scherm om u aan te melden bij uw GitHub-account.
3. Klik op de menubalk op Bekijk Opdrachtpalet, typ , en klik vervolgens op Publiceren naar GitHub.
4. Selecteer een optie om uw gekloonde opslagplaats naar uw GitHub-account te publiceren.

Stap 2: Versleutelde geheimen toevoegen aan uw opslagplaats

Volg op de GitHub-website voor uw gepubliceerde opslagplaats de instructies in Versleutelde geheimen maken voor een opslagplaats voor de volgende versleutelde geheimen:

• Maak een versleuteld geheim met de naam DATABRICKS_HOST, stel deze in op de waarde van uw URL per werkruimte, bijvoorbeeld https://adb-1234567890123456.7.azuredatabricks.net.
• Maak een versleuteld geheim met de naam DATABRICKS_TOKEN, ingesteld op de waarde van het Microsoft Entra ID-token voor de service-principal.

Stap 3: Een vertakking aanmaken en publiceren in uw opslagplaats

1. Klik in Visual Studio Code in versiebeheer weergave (weergave > versiebeheer) op het pictogram ... (Weergaven en Meer Acties).
2. Klik op Branch > Maak Branch Van.
3. Voer een naam in voor de vertakking, bijvoorbeeld my-branch.
4. Selecteer de vertakking waaruit u de vertakking wilt maken, bijvoorbeeld hoofd-.
5. Breng een kleine wijziging aan in een van de bestanden in uw lokale opslagplaats en sla het bestand vervolgens op. Breng bijvoorbeeld een kleine wijziging aan in een code-opmerking in het tests/transforms_test.py bestand.
6. Klik in de Bronbeheerweergave nogmaals op het ... pictogram (Weergaven en Meer Acties).
7. Klik op Wijzigingen > fase alle wijzigingen.
8. Klik nogmaals op het pictogram ... (weergaven en meer acties).
9. Klik op Doorvoer > doorvoer gefaseerd.
10. Voer een bericht in voor de commit.
11. Klik nogmaals op het pictogram ... (weergaven en meer acties).
12. Klik op Vertakking Publiceer Vertakking>.

Stap 4: Een pull-aanvraag maken en samenvoegen

1. Ga naar de GitHub-website voor uw gepubliceerde opslagplaats. https://github/<your-GitHub-username>/ide-best-practices
2. Klik op het tabblad Pull-aanvragen, naast my-branch had recent pushes, op Vergelijken en pull-aanvraag.
3. Klik op Create pull-request (Pull-aanvraag maken).
4. Op de pull request-pagina, wacht totdat het pictogram naast CI pipleline/ci-pipeline (push) een groen vinkje weergeeft. (Het kan enkele ogenblikken duren voordat het pictogram wordt weergegeven.) Als er een rode X is in plaats van een groen vinkje, klikt u op Details om erachter te komen waarom. Als het pictogram of de details niet meer worden weergegeven, klikt u op Alle controles weergeven.
5. Als het groene vinkje wordt weergegeven, voegt u de pull-aanvraag samen in de main vertakking door op Pull-aanvraag samenvoegen te klikken.