Použití dbx s Visual Studio Code

Důležité

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

Databricks doporučuje používat balíčky deklarativní automatizace místo dbx od Databricks Labs. Podívejte se, co jsou balíčky deklarativní automatizace? a migrujte z dbx na sady.

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
Lintování
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. dbx Dává Službě Azure Databricks pokyn, aby úlohy Lakeflow spustily odeslaný kód v clusteru úloh Azure Databricks v daném pracovním prostoru.

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 ve vašem úč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 a kompatibilitě pro verzi Databricks Runtime určenou pro vaše cílové clustery. V každém případě musí být verze Pythonu 3.8 nebo vyšší.

Chcete-li zjistit verzi Pythonu, kterou aktuálně používá váš místní počítač, spusťte python --version 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 starší, 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í GitHub Pull Requesty a Issues 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.
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 máte požadavky na tuto ukázku kódu splněny, proveďte následující kroky, abyste mohli začít používat tuto 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 zahrnout tečku (.) po příkazu code.

Pro Linux a macOS:
```
mkdir ide-demo
cd ide-demo
code .
```
Návod

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 si hodnotu Virtualenv location ve výstupu příkazu pipenv, 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 klikněte na View > Command Palette, zadejte Terminal: Create, a potom klikněte na Terminal: Create New Terminal.
4. Ujistěte se, že příkazový řádek ukazuje, že jste v prostředí shellu pipenv. 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 opustit prostředí pipenv, spusťte příkaz exit, a 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 prostředí Visual Studio Code otevřete složku (ide-demo), pokud ještě není otevřená.
Klikněte na Paletu příkazů< c0 />, zadejte a potom klikněte na Git: Klonovat.
Do pole Zadejte adresu URL úložiště nebo vyberte zdroj 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 dbx a rozhraní příkazového řádku Databricks verze 0.18 nebo nižší, která je kompatibilní s vaší verzí Pythonu. Aby to fungovalo, spusťte v editoru Visual Studio Code z vašeho terminálu následující příkaz ve složce ide-demo s aktivovaným prostředím pipenv (pipenv shell):
```
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 je vrácena verze Databricks CLI 0.17, je nainstalována 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 se balíčky uvedené v souborech requirements.txt a unit-requirements.txt nacházejí 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ů. Pro zajištění lepší kompatibility můžete porovnat tyto verze s typem uzlu clusteru, který má váš pracovní prostor Azure Databricks používat pro pozdější realizaci nasazení. Informace o verzi Databricks Runtime vašeho clusteru najdete v části "System environment" v poznámkách k vydání a kompatibilitě 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 souboru změníte hodnotu objektů a z a na řetězec verze modulu runtime Azure Databricks a typ uzlu clusteru , které chcete, aby váš pracovní prostor Azure Databricks použil pro 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'

Návod

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í

Jednotkové testy

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

Spouštěč jednotkových testů

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 souboru unit-requirements.txt, který jste dříve spustili pomocí pip, obsahuje seznam balíčků, na kterých jednotkové testy 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 vašem místním počítači můžete pomocí dbx instruovat Azure Databricks, aby ve vzdáleném pracovním prostoru spustil ukázku kódu, jak je popsáno v další podsekci, na vyžádání. 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.

Spustit s dbx

Nainstalujte obsah složky covid_analysis jako balíček v Pythonu v režimu setuptools vývoje spuštěním následujícího příkazu z kořenového adresáře projektu dbx (například složky ide-demo/ide-best-practices). Nezapomeňte na konec tohoto příkazu zahrnout tečku (.):
```
pip install -e .
```
Tento příkaz vytvoří složku covid_analysis.egg-info, která obsahuje informace o zkompilované verzi souborů covid_analysis/__init__.py a covid_analysis/transforms.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é.

Návod

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 Databricks.
Volitelně můžete získat metriky pokrytí testů tím, že spustíte následující příkaz:
```
coverage run -m pytest tests/
```
Poznámka:

Pokud se zobrazí zpráva, že coverage nebyla nalezena, spusťte pip install coverage a 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í, které je specifikováno v objektu artifact_location v souboru .dbx/project.json.
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
```
Odkaz na výsledky spuštění je zobrazen v terminálu. 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
```
Odkaz na výsledky spuštění je zobrazen v terminálu. 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 projektu .github/workflows se soubory onpush.yml a onrelease.yml GitHub Actions starají o následující:

Při každém přidání změn na značku, která začíná v, se dbx používá k nasazení úlohy covid_analysis_etl_prod.
Při každém provedení změn, která nevede na značku začínající s v:
1. Používá se pytest ke spuštění jednotkových testů.
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í souboru, který je již nasazen a specifikován v úloze covid_analysis_etl_integ ve vzdáleném pracovním prostoru, a sleduje toto spuštění, dokud není dokončeno.

Poznámka:

Další soubor GitHub Actions, databricks_pull_request_tests.yml je k dispozici jako šablona, se kterou můžete experimentovat, aniž by to ovlivnilo soubory GitHub Actions onpush.yml a onrelease.yml. 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 soubory GitHub Actions onpush.yml a onrelease.yml.

Nastavení pro použití GitHub Actions

Podle pokynů ve služebních identitách pro CI/CD nastavte pracovní prostor Azure Databricks. To zahrnuje následující akce:

Vytvořte objekt "service principal".
Vytvořte token Microsoft Entra ID pro služebního principála.

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í servisního principálu a jeho tokenu Microsoft Entra ID se zastavte a poznamenejte si hodnotu tokenu Microsoft Entra ID, kterou použijete v další sekci.

Spustit 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 ikona není viditelná, nejprve povolte rozšíření GitHub Pull Requests a Issues prostřednictvím zobrazení Rozšíření (View > Extensions).
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 ho na hodnotu tokenu ID Microsoft Entra pro služební účet.

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 odvodit větev, například hlavní.
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ěny > Uzavřít všechny změny.
Znovu klikněte na ikonu ... (zobrazení a další akce).
Klikněte na Commit > Commit staged.
Zadejte zprávu pro potvrzení.
Znovu klikněte na ikonu ... (zobrazení a další akce).
Klikněte na Branch > Publish Branch.

Krok 4: Vytvořit pull request a sloučit

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 my-branch s nedávnými pushy klikněte na Porovnat a vytvořit žá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, až se vedle kanálu CI pipeline / ci-pipeline (push) zobrazí zelená fajfka. (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 pull request do větve main kliknutím na Sloučit pull request.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-03-26