Použití dbx se sadou Visual Studio Code

Článek
10/09/2024

Důležité

Tato dokumentace byla vyřazena a nemusí být aktualizována.

Databricks doporučuje používat sady prostředků Databricks místo dbx Databricks Labs. Podívejte se , co jsou sady prostředků Databricks? a migrace z dbx do sad.

Pokud chcete použít Azure Databricks se sadou Visual Studio Code, přečtěte si článek o rozšíření Databricks pro Visual Studio Code.

Tento článek popisuje ukázku kódu založeného na Pythonu, se kterou můžete pracovat v libovolném integrovaném vývojovém prostředí kompatibilním s Pythonem. Konkrétně tento článek popisuje, jak pracovat s tímto vzorovým kódem v editoru Visual Studio Code, který poskytuje následující funkce produktivity vývojářů:

Dokončování kódu
Analyzování kódu
Testování
Ladění objektů kódu, které nevyžadují připojení ke vzdáleným prostředkům Azure Databricks v reálném čase

Tento článek používá dbx by Databricks Labs spolu se sadou Visual Studio Code k odeslání ukázky kódu do vzdáleného pracovního prostoru Azure Databricks. dbxDává Službě Azure Databricks pokyn, aby v daném pracovním prostoru na clusteru úloh Azure Databricks naplánoval a orchestroval pracovní postupy pro spuštění odeslaného kódu.

Oblíbené poskytovatele Gitu třetích stran můžete použít pro správu verzí a kontinuální integraci a průběžné doručování nebo průběžné nasazování (CI/CD) vašeho kódu. Pro správu verzí zahrnují tito poskytovatelé Gitu následující:

GitHub
Bitbucket
GitLab
Azure DevOps (není k dispozici v oblastech Azure China)
AWS CodeCommit
GitHub AE

Pro CI/CD dbx podporuje následující platformy CI/CD:

Abyste si ukázali, jak může správa verzí a CI/CD fungovat, tento článek popisuje, jak používat Visual Studio Code, dbxa tuto ukázku kódu společně s GitHubem a GitHub Actions.

Požadavky na vzorový kód

Pokud chcete použít tento vzorový kód, musíte mít následující:

Pracovní prostor Azure Databricks v účtu Azure Databricks
Účet GitHub. Vytvořte účet GitHubu, pokud ho ještě nemáte.

Kromě toho na místním vývojovém počítači musíte mít následující:

Python verze 3.8 nebo vyšší

Měli byste použít verzi Pythonu, která odpovídá verzi nainstalované v cílových clusterech. Pokud chcete získat verzi Pythonu, která je nainstalovaná v existujícím clusteru, můžete příkaz spustit pomocí webového terminálu clusteru python --version . Viz také část Systémové prostředí v poznámkách k verzi Databricks Runtime verze a kompatibilitě verze Databricks Runtime pro vaše cílové clustery. V každém případě musí být verze Pythonu 3.8 nebo vyšší.

Pokud chcete získat verzi Pythonu, na kterou se aktuálně odkazuje na místní počítač, spusťte python --version ho z místního terminálu. (V závislosti na tom, jak nastavíte Python na místním počítači, možná budete muset spustit python3 místo python v tomto článku.) Viz také Výběr interpreta Pythonu.
pip. pip se automaticky nainstaluje s novějšími verzemi Pythonu. Pokud chcete zkontrolovat, jestli pip už je nainstalovaný, spusťte pip --version ho z místního terminálu. (V závislosti na tom, jak jste nastavili Python nebo pip na místním počítači, možná budete muset spustit pip3 místo pip v tomto článku.)
dbx verze 0.8.0 nebo vyšší. Balíček můžete nainstalovat z indexu dbx balíčků Pythonu (PyPI) spuštěním pip install dbxpříkazu .

Poznámka:

Teď nemusíte instalovat dbx . Můžete ho nainstalovat později v části s ukázkou kódu .
Metoda vytvoření virtuálních prostředí Pythonu, která zajistí, že ve svých dbx projektech používáte správné verze Pythonu a závislostí balíčků. Tento článek se zabývá pipenv.
Rozhraní příkazového řádku Databricks verze 0.18 nebo novější je nastavené s ověřováním.

Poznámka:

Starší verzi rozhraní příkazového řádku Databricks (Rozhraní příkazového řádku Databricks verze 0.17) nemusíte instalovat. Můžete ho nainstalovat později v části s ukázkou kódu . Pokud ho chcete nainstalovat později, nezapomeňte místo toho nastavit ověřování.
Visual Studio Code.
Rozšíření Pythonu pro Visual Studio Code
Rozšíření Žádosti o přijetí změn a problémy GitHubu pro Visual Studio Code
Git

Informace o ukázce kódu

Ukázka kódu Pythonu pro tento článek, která je k dispozici v úložišti databricks/ide-best-practices v GitHubu, dělá toto:

Získá data z úložiště owid/covid-19-data v GitHubu.
Filtruje data pro konkrétní kód země ISO.
Vytvoří kontingenční tabulku z dat.
Provádí čištění dat na datech.
Modularizuje logiku kódu do opakovaně použitelných funkcí.
Unit testuje funkce.
Poskytuje dbx konfigurace a nastavení projektu, které umožní kódu zapisovat data do tabulky Delta ve vzdáleném pracovním prostoru Azure Databricks.

Nastavení ukázky kódu

Jakmile pro tuto ukázku kódu použijete požadavky , proveďte následující kroky, abyste mohli začít používat ukázku kódu.

Poznámka:

Tyto kroky nezahrnují nastavení této ukázky kódu pro CI/CD. Pro spuštění této ukázky kódu nemusíte nastavit CI/CD. Pokud chcete CI/CD nastavit později, přečtěte si téma Spuštění s GitHub Actions.

Krok 1: Vytvoření virtuálního prostředí Pythonu

V terminálu vytvořte prázdnou složku, která bude obsahovat virtuální prostředí pro tuto ukázku kódu. Tyto pokyny používají nadřazenou složku s názvem ide-demo. Tuto složku můžete pojmenovat libovolným způsobem. Pokud použijete jiný název, nahraďte název v celém tomto článku. Po vytvoření složky na ni přepněte a spusťte Visual Studio Code z této složky. Nezapomeňte za příkaz vložit tečku code (.).

Pro Linux a macOS:
```
mkdir ide-demo
cd ide-demo
code .
```
Tip

Pokud se zobrazí chyba command not found: code, přečtěte si téma Spuštění z příkazového řádku na webu Microsoftu.

Pro Windows:
```
md ide-demo
cd ide-demo
code .
```
V editoru Visual Studio Code na řádku nabídek klikněte na Zobrazit > terminál.
V kořenové ide-demo složce spusťte pipenv příkaz s následující možností, kde <version> je cílová verze Pythonu, kterou už máte nainstalovanou místně (a v ideálním případě verzi, která odpovídá verzi Pythonu cílového clusteru), například 3.8.14.
```
pipenv --python <version>
```
Poznamenejte Virtualenv location si hodnotu ve výstupu pipenv příkazu, protože ji budete potřebovat v dalším kroku.
Vyberte cílový interpret Pythonu a pak aktivujte virtuální prostředí Pythonu:
1. Na řádku nabídek klikněte na Zobrazit > paletu příkazů, zadejte Python: Selecta potom klikněte na Python: Vybrat interpret.
2. Vyberte interpret Pythonu v cestě k virtuálnímu prostředí Pythonu, které jste právě vytvořili. (Tato cesta je uvedena Virtualenv location jako hodnota ve výstupu pipenv příkazu.)
3. Na řádku nabídek klepněte na příkaz Zobrazit paletu příkazů, zadejte Terminal: Createa potom klepněte na příkaz Terminál: Vytvořit nový terminál>.
4. Ujistěte se, že příkazový řádek indikuje, že jste v pipenv prostředí. Abyste to potvrdili, měli byste vidět něco podobného (<your-username>) před příkazovým řádkem. Pokud ho nevidíte, spusťte následující příkaz:
```
pipenv shell
```
  Pokud chcete prostředí opustit pipenv , spusťte příkaz exita závorky zmizí.
Další informace najdete v tématu Použití prostředí Pythonu ve VS Code v dokumentaci k editoru Visual Studio Code.

Krok 2: Klonování ukázky kódu z GitHubu

V editoru ide-demo Visual Studio Code otevřete složku (Soubor > otevřít složku), pokud ještě není otevřená.
Klikněte na Zobrazit paletu příkazů, zadejte Git: Clonea potom klikněte na Git: Clone>.
Do pole Zadejte adresu URL úložiště nebo vyberte zdroj úložiště, zadejte https://github.com/databricks/ide-best-practices
Přejděte do složky ide-demo a klikněte na Vybrat umístění úložiště.

Krok 3: Instalace závislostí ukázky kódu

Nainstalujte verzi rozhraní příkazového dbx řádku Databricks verze 0.18 nebo nižší, která je kompatibilní s vaší verzí Pythonu. Uděláte to tak, že v editoru Visual Studio Code z terminálu ve ide-demo složce s aktivovaným prostředím pipenv (pipenv shell) spustíte následující příkaz:
```
pip install dbx
```
Potvrďte, že dbx je nainstalovaná. Provedete to spuštěním následujícího příkazu:
```
dbx --version
```
Pokud se vrátí číslo verze, dbx nainstaluje se.

Pokud je číslo verze nižší než 0.8.0, upgradujte dbx spuštěním následujícího příkazu a znovu zkontrolujte číslo verze:
```
pip install dbx --upgrade
dbx --version

# Or ...
python -m pip install dbx --upgrade
dbx --version
```
Při instalaci dbxse automaticky nainstaluje i starší verze rozhraní příkazového řádku Databricks (Rozhraní příkazového řádku Databricks verze 0.17). Pokud chcete ověřit, že je nainstalované starší rozhraní příkazového řádku Databricks (Rozhraní příkazového řádku Databricks verze 0.17), spusťte následující příkaz:
```
databricks --version
```
Pokud se vrátí databricks CLI verze 0.17, nainstaluje se starší verze Rozhraní příkazového řádku Databricks.
Pokud jste nenastavili starší verzi rozhraní příkazového řádku Databricks (Databricks CLI verze 0.17) s ověřováním, musíte to udělat teď. Pokud chcete ověřit, že je ověřování nastavené, spusťte následující základní příkaz a získejte souhrnné informace o vašem pracovním prostoru Azure Databricks. Nezapomeňte za podpříkaz uvést lomítko (/):ls
```
databricks workspace ls /
```
Pokud se vrátí seznam názvů složek kořenové úrovně pro váš pracovní prostor, nastaví se ověřování.
Nainstalujte balíčky Pythonu, na které tato ukázka kódu závisí. Uděláte to tak, že ze ide-demo/ide-best-practices složky spustíte následující příkaz:
```
pip install -r unit-requirements.txt
```
Ověřte, že jsou nainstalované závislé balíčky ukázkového kódu. Provedete to spuštěním následujícího příkazu:
```
pip list
```
Pokud jsou balíčky uvedené v seznamu requirements.txt a unit-requirements.txt soubory jsou někde v tomto seznamu, nainstalují se závislé balíčky.

Poznámka:

Soubory uvedené v requirements.txt tomto seznamu jsou určené pro konkrétní verze balíčků. Kvůli lepší kompatibilitě můžete křížově odkazovat na tyto verze s typem uzlu clusteru, který má pracovní prostor Azure Databricks používat pro pozdější spuštění nasazení. Informace o verzi Databricks Runtime vašeho clusteru najdete v části Systémové prostředí ve verzích a kompatibilitě modulu Databricks Runtime.

Krok 4: Přizpůsobení ukázky kódu pro pracovní prostor Azure Databricks

Přizpůsobte nastavení projektu úložiště dbx . Uděláte to tak, že v .dbx/project.json souboru změníte hodnotu profile objektu DEFAULT na název profilu, který odpovídá názvu profilu, který jste nastavili pro ověřování pomocí starší verze Rozhraní příkazového řádku Databricks (Rozhraní příkazového řádku Databricks verze 0.17). Pokud jste nenastavili žádný jiný než výchozí profil, ponechte DEFAULT to tak, jak je. Příklad:
```
{
  "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
}
```

dbx Přizpůsobte nastavení nasazení projektu. Uděláte to tak, že v conf/deployment.yml souboru změníte hodnotu spark_version objektů z node_type_id m6gd.large 10.4.x-scala2.12 modulu runtime Azure Databricks na řetězec verze modulu runtime Azure Databricks a typ uzlu clusteru, ve kterém chcete, aby váš pracovní prostor Azure Databricks používal ke spouštění nasazení.

Pokud chcete například zadat Databricks Runtime 10.4 LTS a Standard_DS3_v2 typ uzlu:

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"

Tip

V tomto příkladu má každá z těchto tří definic úloh stejnou spark_version hodnotu a node_type_id hodnotu. Pro různé definice úloh můžete použít různé hodnoty. Můžete také vytvářet sdílené hodnoty a opakovaně je používat napříč definicemi úloh, abyste snížili chyby při psaní a údržbu kódu. Podívejte se na příklad YAML v dbx dokumentaci.

Prozkoumání ukázky kódu

Po nastavení ukázky kódu se pomocí následujících informací dozvíte, jak různé soubory ve ide-demo/ide-best-practices složce fungují.

Modularizace kódu

Nemodularizovaný kód

Soubor jobs/covid_trends_job_raw.py je nemodularizovaná verze logiky kódu. Tento soubor můžete spustit sám.

Modularizovaný kód

Soubor jobs/covid_trends_job.py je modularizovaná verze logiky kódu. Tento soubor spoléhá na sdílený kód v covid_analysis/transforms.py souboru. Soubor covid_analysis/__init__.py považuje covide_analysis složku za balíček obsahující.

Testování

Testy jednotky

Soubor tests/testdata.csv obsahuje malou část dat v covid-hospitalizations.csv souboru pro účely testování. Soubor tests/transforms_test.py obsahuje testy jednotek pro covid_analysis/transforms.py soubor.

Spouštěč testů jednotek

Soubor pytest.ini obsahuje možnosti konfigurace pro spouštění testů pomocí pytestu. Viz pytest.ini a možnosti konfigurace v pytest dokumentaci.

Soubor .coveragerc obsahuje možnosti konfigurace pro měření pokrytí kódu Pythonu s coverage.py. Viz referenční informace ke konfiguraci v coverage.py dokumentaci.

Soubor requirements.txt , který je podmnožinou unit-requirements.txt souboru, který jste spustili dříve, pipobsahuje seznam balíčků, na kterých testy jednotek také závisí.

Zabalení

Soubor setup.py poskytuje příkazy, které se mají spouštět v konzole (skripty konzoly), jako pip je například příkaz, pro balení projektů Pythonu pomocí nástrojů pro nastavení. Viz Vstupní body v setuptools dokumentaci.

Další soubory

V této ukázce kódu jsou další soubory, které nebyly dříve popsány:

Složka .github/workflows obsahuje tři soubory , databricks_pull_request_tests.ymlonpush.ymla onrelease.yaml, které představují GitHub Actions, které jsou popsány dále v části GitHub Actions.
Soubor .gitignore obsahuje seznam místních složek a souborů, které Git pro vaše úložiště ignoruje.

Spuštění ukázky kódu

Na místním počítači můžete azure Databricks instruovat dbx , aby spustil ukázku kódu ve vzdáleném pracovním prostoru na vyžádání, jak je popsáno v další pododdílu. Nebo můžete pomocí GitHub Actions nechat GitHub spustit ukázku kódu pokaždé, když nasdílíte změny kódu do úložiště GitHub.

Spuštění s využitím dbx

Nainstalujte obsah covid_analysis složky jako balíček v režimu vývoje Pythonu setuptools spuštěním následujícího příkazu z kořenového ide-demo/ide-best-practices adresáře projektu dbx (například složky). Nezapomeňte na konec tohoto příkazu zahrnout tečku (.):
```
pip install -e .
```
Tento příkaz vytvoří covid_analysis.egg-info složku, která obsahuje informace o zkompilované verzi souborů a covid_analysis/transforms.py souborechcovid_analysis/__init__.py.
Testy spusťte spuštěním následujícího příkazu:
```
pytest tests/
```
Výsledky testů se zobrazí v terminálu. Všechny čtyři testy by se měly zobrazit jako úspěšné.

Tip

Další přístupy k testování, včetně testování poznámkových bloků R a Scala, najdete v tématu Testování jednotek pro poznámkové bloky.
Volitelně můžete získat metriky pokrytí testů pro testy spuštěním následujícího příkazu:
```
coverage run -m pytest tests/
```
Poznámka:

Pokud se zobrazí zpráva, která coverage nebyla nalezena, spusťte pip install coveragea akci opakujte.

Pokud chcete zobrazit výsledky pokrytí testu, spusťte následující příkaz:
```
coverage report -m
```
Pokud všechny čtyři testy projdou, odešlete dbx obsah projektu do pracovního prostoru Azure Databricks spuštěním následujícího příkazu:
```
dbx deploy --environment=default
```
Informace o projektu a jeho spuštěních se odesílají do umístění zadaného v objektu workspace_directory .dbx/project.json v souboru.

Obsah projektu se odešle do umístění zadaného artifact_location v objektu .dbx/project.json v souboru.
Spuštěním následujícího příkazu spusťte v pracovním prostoru předprodukční verzi kódu:
```
dbx launch covid_analysis_etl_integ
```
V terminálu se zobrazí odkaz na výsledky spuštění. Měla by vypadat přibližně takto:
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345
```
Pokud chcete zobrazit výsledky spuštění ve vašem pracovním prostoru, postupujte podle tohoto odkazu ve webovém prohlížeči.
Spusťte v pracovním prostoru produkční verzi kódu spuštěním následujícího příkazu:
```
dbx launch covid_analysis_etl_prod
```
V terminálu se zobrazí odkaz na výsledky spuštění. Měla by vypadat přibližně takto:
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456
```
Pokud chcete zobrazit výsledky spuštění ve vašem pracovním prostoru, postupujte podle tohoto odkazu ve webovém prohlížeči.

Spuštění pomocí GitHub Actions

Ve složce onpush.yml projektu .github/workflows a onrelease.yml v souborech GitHub Actions postupujte takto:

Při každém nasdílení změn na značku, která začíná v, se používá dbx k nasazení covid_analysis_etl_prod úlohy.
Při každém nasdílení změn, která není značkou, která začíná na v:
1. Používá pytest se ke spuštění testů jednotek.
2. Používá dbx k nasazení souboru zadaného covid_analysis_etl_integ v úloze do vzdáleného pracovního prostoru.
3. Používá dbx ke spuštění již nasazeného souboru zadaného covid_analysis_etl_integ v úloze ve vzdáleném pracovním prostoru a trasování tohoto spuštění až do dokončení.

Poznámka:

Další soubor databricks_pull_request_tests.ymlGitHub Actions je k dispozici jako šablona, se kterou můžete experimentovat, aniž by to mělo vliv na onpush.yml soubory GitHub onrelease.yml Actions. Tuto ukázku kódu můžete spustit bez databricks_pull_request_tests.yml souboru GitHub Actions. Jeho použití není popsáno v tomto článku.

Následující pododdíly popisují, jak nastavit a spustit onpush.yml soubory GitHub onrelease.yml Actions.

Nastavení pro použití GitHub Actions

Podle pokynů v instančních objektech pro CI/CD nastavte pracovní prostor Azure Databricks. To zahrnuje následující akce:

Vytvořte instanční objekt.
Vytvořte token ID Microsoft Entra pro instanční objekt.

Jako osvědčený postup zabezpečení doporučuje Databricks použít token ID Microsoft Entra pro instanční objekt místo osobního přístupového tokenu Databricks pro uživatele pracovního prostoru, aby se GitHub ověřil ve vašem pracovním prostoru Azure Databricks.

Po vytvoření instančního objektu a tokenu MICROSOFT Entra ID zastavte a poznamenejte si hodnotu tokenu ID Microsoft Entra, kterou použijete v další části.

Spuštění GitHub Actions

Krok 1: Publikování klonovaného úložiště

V editoru Visual Studio Code na bočním panelu klikněte na ikonu GitHubu . Pokud tato ikona není viditelná, nejprve povolte rozšíření Žádosti o přijetí změn a problémy GitHubu prostřednictvím zobrazení rozšíření (rozšíření zobrazení>).
Pokud je tlačítko Přihlásit se viditelné, klikněte na něj a podle pokynů na obrazovce se přihlaste ke svému účtu GitHub.
Na řádku nabídek klikněte na Zobrazit > paletu příkazů, zadejte Publish to GitHuba potom klepněte na příkaz Publikovat na GitHubu.
Vyberte možnost publikování klonovaného úložiště do účtu GitHubu.

Krok 2: Přidání šifrovaných tajných kódů do úložiště

Na webu GitHubu pro publikované úložiště postupujte podle pokynů v tématu Vytváření šifrovaných tajných kódů pro úložiště pro následující šifrované tajné kódy:

Vytvořte šifrovaný tajný kód s názvem DATABRICKS_HOST, nastavte hodnotu adresy URL pro jednotlivé pracovní prostory, například https://adb-1234567890123456.7.azuredatabricks.net.
Vytvořte šifrovaný tajný kód s názvem DATABRICKS_TOKEN, nastavte na hodnotu tokenu ID Microsoft Entra pro instanční objekt.

Krok 3: Vytvoření a publikování větve do úložiště

V editoru Visual Studio Code klikněte v zobrazení správy zdrojového kódu (Zobrazit > správu zdrojového kódu) na ikonu ... (Zobrazení a další akce).
Klikněte na Větev > vytvořit větev z.
Zadejte název větve, například my-branch.
Vyberte větev, ze které chcete vytvořit větev, například z hlavní větve.
Proveďte menší změnu jednoho ze souborů v místním úložišti a pak soubor uložte. Proveďte například menší změnu komentáře ke kódu v tests/transforms_test.py souboru.
V zobrazení správy zdrojového kódu znovu klikněte na ikonu ... (zobrazení a další akce).
Klikněte na Změnit > fázi všech změn.
Znovu klikněte na ikonu ... (zobrazení a další akce).
Klikněte na Commit Commit > Commit staged.
Zadejte zprávu pro potvrzení.
Znovu klikněte na ikonu ... (zobrazení a další akce).
Klikněte na Větev > publikovat větev.

Krok 4: Vytvoření žádosti o přijetí změn a sloučení

Přejděte na web GitHubu pro vaše publikované úložiště. https://github/<your-GitHub-username>/ide-best-practices
Na kartě Žádosti o přijetí změn vedle větve obsahovala nedávné nabízení, klikněte na Porovnat a žádost o přijetí změn.
Klikněte na Create pull request (Vytvořit žádost o přijetí změn).
Na stránce žádosti o přijetí změn počkejte na ikonu vedle kanálu CI pipleline / ci-pipeline (push), aby se zobrazila zelená značka zaškrtnutí. (Zobrazení ikony může chvíli trvat.) Pokud je místo zelené značky zaškrtnutí červený symbol X, klikněte na Tlačítko Podrobnosti a zjistěte, proč. Pokud se ikona nebo podrobnosti už nezobrazují, klikněte na Zobrazit všechny kontroly.
Pokud se zobrazí zelená značka zaškrtnutí, sloučte žádost o přijetí změn do main větve kliknutím na Sloučit žádost o přijetí změn.

Sdílet prostřednictvím