Migrace rozhraní příkazového řádku Databricks

Tento článek popisuje, jak migrovat z Rozhraní příkazového řádku Databricks verze 0.18 nebo novější na Rozhraní příkazového řádku Databricks verze 0.205 nebo novější. Databricks CLI verze 0.205 a vyšší jsou ve verzi Public Preview.

V zájmu stručnosti se tento článek týká rozhraní příkazového řádku Databricks verze 0.18 a níže jako "starší verze" rozhraní příkazového řádku a rozhraní příkazového řádku Databricks verze 0.205 a vyšší jako "nové" rozhraní příkazového řádku.

Další informace o starší verzi a nových rozhraních CLI najdete tady:

Odinstalovat starší verzi rozhraní příkazového řádku

Pokud máte nainstalované starší rozhraní příkazového řádku a chcete ho odinstalovat, použijte příkaz pip (nebo pip3 v závislosti na verzi Python) a spusťte příkaz uninstall následujícím způsobem:

pip uninstall databricks-cli

Instalace nového rozhraní příkazového řádku

Informace o instalaci nového rozhraní příkazového řádku najdete v tématu Instalace nebo aktualizace rozhraní příkazového řádku Databricks.

Ověřte instalaci rozhraní příkazového řádku

Pokud si nejste jistí, jestli používáte nové rozhraní příkazového řádku, podle pokynů v této části ověřte a podle potřeby upravte. Než budete postupovat podle těchto pokynů, nezapomeňte ukončit všechna Python virtuální prostředí, conda prostředí nebo podobná prostředí.

Pokud chcete zkontrolovat verzi výchozí instalace rozhraní příkazového řádku, spusťte následující příkaz:

databricks -v

Pokud číslo verze není to, co očekáváte, udělejte jednu z těchto věcí:

  • Pokud chcete použít jenom jednu verzi rozhraní příkazového řádku: odinstalujte všechny předchozí verze rozhraní příkazového řádku, které už nechcete používat. Možná budete muset aktualizovat operační systém PATH tak, aby byla uvedena cesta ke zbývající verzi rozhraní příkazového řádku, kterou chcete použít.
  • Pokud chcete dál používat více verzí rozhraní příkazového řádku: přidejte na začátek úplnou cestu k verzi rozhraní příkazového řádku, kterou chcete použít, ke každému volání rozhraní příkazového řádku.
  • Pokud chcete dál používat více verzí rozhraní příkazového řádku, ale nechcete pokračovat v úplné cestě k verzi rozhraní příkazového řádku, kterou používáte nejčastěji: ujistěte se, že úplná cesta k této verzi je uvedená jako první v operačním systému PATH. Mějte na paměti, že stále musíte předřadit úplnou cestu k verzím rozhraní příkazového řádku, které nejsou uvedeny jako první v operačním systému PATH.

Pokud chcete aktualizovat operační systém PATH, postupujte takto:

MacOS nebo Linux

  1. Seznam cest, kde databricks je nainstalována spuštěním jednoho z následujících příkazů:

    which -a databricks

# Or:
where databricks

  2. Získejte cestu k instalaci, kterou chcete použít, aniž by bylo nutné přidávat úplnou cestu ke každému volání CLI. Pokud si nejste jisti, která je to cesta, zobrazte úplnou cestu ke každému umístění, následovanou znakem -v, například:

    /usr/local/bin/databricks -v

  3. Pokud chcete umístit cestu k instalaci, kterou chcete použít jako první, PATHspusťte následující příkaz a nahraďte /usr/local/bin cestu, kterou chcete použít. Nepřidávejte databricks na konec této cesty. Příklad:

    export PATH="/usr/local/bin:$PATH"

  4. Pokud chcete ověřit, že PATH byla správně nastavena pro aktuální relaci terminálu, spusťte databricks a potom -v a zkontrolujte číslo verze:

    databricks -v

  5. Pokud chcete nastavit PATH tímto způsobem při každém restartování terminálu, přidejte do souboru inicializace prostředí příkaz z kroku 3. Například pro Zshell se tento soubor obvykle nachází na ~/.zshrcadrese . Pro Bash, tento soubor je obvykle umístěn v ~/.bashrc. Pro další shell vizte dokumentaci poskytovatele vašeho prostředí.

  6. Po aktualizaci souboru inicializace prostředí musíte restartovat terminál, aby se použila aktualizovaná hodnota PATH.

Windows

  1. Klikněte pravým tlačítkem myši na instalaci databricks , kterou chcete použít, aniž byste museli předefinovat úplnou cestu ke každé a každému volání rozhraní příkazového řádku.

  2. Klikněte na Otevřít umístění souboru.

  3. Poznamenejte si cestu k databricks, například C:\Windows.

  4. V nabídce Start vyhledejte proměnné prostředí.

  5. Klikněte na Upravit proměnné prostředí pro váš účet.

  6. V části vyberte proměnnou <username>.

  7. Klikněte na Upravit.

  8. Klikněte na Nový.

  9. Zadejte cestu, kterou chcete přidat, bez databricks.exe (například C:\Windows).

  10. Pomocí tlačítka Přesunout nahoru přesuňte cestu, kterou jste právě přidali na začátek seznamu.

  11. Klikněte na OK.

  12. Pokud chcete ověřit, jestli je PATH správně nastavený, otevřete nový příkazový řádek, spusťte databricks a potom -va zkontrolujte číslo verze:

    databricks -v

Použití dalších typů ověřování

Starší rozhraní příkazového řádku i nové rozhraní příkazového řádku podporují ověřování osobních přístupových tokenů Azure Databricks. Databricks ale doporučuje používat jiné typy ověřování Azure Databricks, pokud je to možné, což podporuje jenom nové rozhraní příkazového řádku.

Pokud musíte použít ověřování pomocí osobního přístupového tokenu Azure Databricks, služba Databricks doporučuje použít token, který je přidružený k předmětu služby, místo účtu Azure Databricks nebo uživatele pracovního prostoru. Viz principály služby.

Nové rozhraní příkazového řádku kromě Azure Databricks osobních přístupových tokenů podporuje Microsoft Entra ID tokeny. Tyto další tokeny jsou bezpečnější, protože obvykle vyprší za jednu hodinu, zatímco Azure Databricks osobní přístupové tokeny mohou být platné od jednoho dne až do neomezenou dobu. To je zvlášť důležité, pokud je token omylem zveřejněný do systému správy verzí, ke kterému mají přístup jiní uživatelé. Nové rozhraní příkazového řádku může také automaticky aktualizovat tyto další tokeny, když vyprší jejich platnost, zatímco aktualizace osobních přístupových tokenů Azure Databricks je buď ruční proces, nebo může být obtížné ji automatizovat.

Další informace najdete v tématu Ověřování rozhraní příkazového řádku Databricks.

Porovnání skupin příkazů a příkazů

Následující tabulka uvádí starší skupiny příkazů rozhraní příkazového řádku a jejich nové ekvivalenty skupin příkazů CLI. Pokud mezi rozhraními CLI existují významné rozdíly, další tabulky uvádějí starší příkazy nebo možnosti rozhraní příkazového řádku a jejich nové příkazy nebo ekvivalenty možností rozhraní příkazového řádku.

Skupiny příkazů

Původní skupina příkazů Nová skupina příkazů
cluster-policies cluster-policies. Všechny názvy příkazů jsou stejné.
clusters clusters. Všechny názvy příkazů jsou stejné.
configure configure. Viz configure možnosti.
fs fs. Viz fs příkazy.
groups groups. Viz groups příkazy.
instance-pools instance-pools. Všechny názvy příkazů jsou stejné.
jobs jobs. Všechny názvy příkazů jsou stejné.
libraries libraries. Všechny názvy příkazů jsou stejné s výjimkou list. Příkaz list už není k dispozici. Místo toho použijte all-cluster-statusescluster-status příkazy.
pipelines pipelines. Viz pipelines příkazy.
repos repos. Všechny názvy příkazů jsou stejné.
runs jobs. Viz runs příkazy.
secrets secrets. Viz secrets příkazy.
stack V novém rozhraní příkazového řádku není k dispozici. Databricks doporučuje místo toho použít zprostředkovatele Databricks Terraform .
tokens tokens. Viz tokens příkazy.
unity-catalog Různý. Viz unity-catalog skupiny příkazů.
workspace workspace. Viz workspace příkazy.

configure volby

Zastaralá varianta Nová možnost
-o Starší verze rozhraní příkazového řádku používá -o pro ověřování OAuth. Nové rozhraní příkazového řádku slouží -o k určení, jestli je výstup rozhraní příkazového řádku ve formátu textu nebo JSON. Nevztahuje se na Azure Databricks.
--oauth Nevztahuje se na Azure Databricks.
-s nebo --scope Nevztahuje se na Azure Databricks.
-t nebo --token -t nebo --token (stejné)
-f nebo --token-file V novém rozhraní příkazového řádku není k dispozici.
--host --host (stejné)
--aad-token Použijte --host a po zobrazení výzvy zadejte token Microsoft Entra ID místo osobního přístupového tokenu Azure Databricks.
--insecure V novém rozhraní příkazového řádku není k dispozici.
--jobs-api-version V novém rozhraní příkazového řádku není k dispozici. Nové rozhraní příkazového řádku používá pouze rozhraní API úloh 2.1. Pokud chcete volat starší verzi rozhraní API úloh 2.0, použijte starší rozhraní příkazového řádku a podívejte se na rozhraní příkazového řádku úloh (starší verze).
--debug Ladění a protokolování v novém rozhraní příkazového řádku najdete v režimu ladění.
--profile --profile (stejné) nebo -p
-h nebo --help -h nebo --help (stejné)

fs příkazy

Všechny fs příkazy ve starší verzi rozhraní příkazového řádku jsou v novém rozhraní příkazového řádku stejné, s výjimkou fs mv těch, které nejsou v novém rozhraní příkazového řádku k dispozici.

Starší příkaz Nový příkaz
fs cat fs cat (stejné)
fs cp fs cp (stejné)
fs ls fs ls (stejné)
fs mkdirs fs mkdir
fs mv V novém rozhraní příkazového řádku není k dispozici.
fs rm fs rm (stejné)

groups příkazy

Starší příkaz Nový příkaz
groups add-member groups patch
groups create groups create (stejné)
groups delete groups delete (stejné)
groups list groups list (stejné)
groups list-members groups list
groups list-parents groups list
groups remove-member groups patch

pipelines příkazy

Starší příkaz Nový příkaz
pipelines create pipelines create (stejné)
pipelines delete pipelines delete (stejné)
pipelines deploy pipelines create
pipelines edit pipelines update
pipelines get pipelines get (stejné)
pipelines list pipelines list-pipeline-eventsnebo pipelines list-pipelinespipelines list-updates
pipelines reset pipelines reset (stejné)
pipelines start pipelines start update
pipelines stop pipelines stop (stejné)
pipelines update pipelines update (stejné)

runs příkazy

Starší příkaz Nový příkaz
runs cancel jobs cancel-run
runs get jobs get-run
runs get-output jobs get-run-output
runs list jobs list-runs
runs submit jobs submit

secrets příkazy

Starší příkaz Nový příkaz
secrets create-scope secrets create-scope (stejné)
secrets delete secrets delete-secret
secrets delete-acl secrets delete-acl (stejné)
secrets delete-scope secrets delete-scope (stejné)
secrets get-acl secrets get-acl (stejné)
secrets list secrets list-secrets
secrets list-acls secrets list-acls (stejné)
secrets list-scopes secrets list-scopes (stejné)
secrets put secrets put-secret
secrets put-acl secrets put-acl (stejné)
secrets write secrets put-secret
secrets write-acl secrets put-acl

tokens příkazy

Starší příkaz Nový příkaz
tokens create tokens create (stejné)
tokens list tokens list (stejné)
tokens revoke tokens delete

unity-catalog skupiny příkazů

unity-catalog <command> ve starém rozhraní příkazového řádku se stává <command> v novém rozhraní příkazového řádku.

Původní skupina příkazů Nová skupina příkazů
unity-catalog catalogs catalogs (stejné, ale vypustit unity-catalog)
unity-catalog external-locations external-locations (stejné, ale vypustit unity-catalog)
unity-catalog lineage V novém rozhraní příkazového řádku není k dispozici. Viz Zobrazení rodokmenu dat pomocí katalogu Unity.
unity-catalog metastores metastores (stejné, ale vypustit unity-catalog)
unity-catalog permissions grants
unity-catalog providers providers (stejné, ale vypustit unity-catalog)
unity-catalog recipients recipients (stejné, ale vypustit unity-catalog)
unity-catalog schemas schemas (stejné, ale vypustit unity-catalog)
unity-catalog shares shares (stejné, ale vypustit unity-catalog)
unity-catalog storage-credentials storage-credentials (stejné, ale vypustit unity-catalog)
unity-catalog tables tables (stejné, ale vypustit unity-catalog)

workspace příkazy

Starší příkaz Nový příkaz
workspace delete workspace delete (stejné)
workspace export workspace export (stejné)
workspace export-dir workspace export
workspace import workspace import (stejné)
workspace import-dir workspace import
workspace list workspace list (stejné)
workspace ls workspace list
workspace mkdirs workspace mkdirs (stejné)
workspace rm workspace delete

Výchozí a poziční argumenty

Většina nových příkazů rozhraní příkazového řádku má alespoň jeden výchozí argument, který nemá doprovodnou možnost. Některé nové příkazy rozhraní příkazového řádku mají dva nebo více pozičních argumentů, které musí být zadány v určitém pořadí a které nemají doprovodné možnosti. To se liší od starší verze rozhraní příkazového řádku, kde většina příkazů vyžaduje zadání možností pro všechny argumenty. Příkaz nového rozhraní příkazového řádku clusters get například jako výchozí argument přebírá ID clusteru. Příkaz starší verze rozhraní příkazového řádku clusters get ale vyžaduje, abyste zadali --cluster-id možnost spolu s ID clusteru. Příklad:

Pro starší verzi rozhraní příkazového řádku:

# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d

# This does **not** work with the legacy CLI - "Error:
#   Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d

Pro nové rozhraní příkazového řádku:

# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d

# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d

V dalším příkladu má příkaz nového CLI grants get dva výchozí argumenty: zabezpečitelný typ, po němž následuje úplný název zabezpečitelného objektu. Příkaz starší verze rozhraní příkazového řádkuunity-catalog permissions get ale vyžaduje, abyste zadali možnost--<securable-type> spolu s úplným názvem zabezpečitelného objektu. Příklad:

Pro starší verzi rozhraní příkazového řádku:

databricks unity-catalog permissions get --schema main.default

Pro nové rozhraní příkazového řádku:

# This works with the new CLI.
databricks grants get schema main.default

# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default

Režim ladění

Starší rozhraní příkazového řádku nabízí --debug možnost zobrazit úplný výpis zásobníku v případě chyby. U nového rozhraní příkazového řádku se --debug možnost nerozpozná. Místo toho použijte následující možnosti:

  • Slouží --log-file <path> k zápisu informací protokolu do souboru zadaného v <path>. Pokud tato možnost není poskytnuta, jsou informace z protokolu poskytnuty na stderr. Zadání --log-file bez zadání --log-level nemá za výsledek, že by se do souboru zapisovaly žádné protokolové informace.
  • Slouží --log-format <type> k určení formátu zaprotokolovaných informací. <type> může být text (výchozí hodnota, pokud není zadána) nebo json.
  • Slouží --log-level <format> k určení úrovně zaprotokolovaných informací. Povolené hodnoty jsou disabled (výchozí, pokud nejsou zadané), trace, debug, info, warna error.

V případě starší verze rozhraní příkazového řádku následující příklad ukazuje úplné trasování zásobníku při chybě:

databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

V novém CLI následující příklad zaznamená úplné trasování zásobníku do souboru pojmenovaného new-cli-errors.log v aktuálním pracovním adresáři. Trasování zásobníku se zapíše do souboru ve formátu JSON:

databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace

# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)

Časté dotazy

Tato část obsahuje běžné dotazy týkající se migrace ze starší verze na nové rozhraní příkazového řádku.

Co se děje se starší verzí rozhraní příkazového řádku?

Starší verze rozhraní příkazového řádku je stále dostupná, ale nepřijímá žádné nekritické aktualizace. Tato starší dokumentace k rozhraní příkazového řádku to odráží. Databricks doporučuje, aby uživatelé migrovali na nové rozhraní příkazového řádku co nejdříve.

Starší verze rozhraní příkazového řádku byla vždy v experimentálním stavu s omezením, že Databricks neplánuje pro starší rozhraní příkazového řádku žádnou novou funkci a starší verze rozhraní příkazového řádku není podporována prostřednictvím kanálů podpory Databricks.

Kdy bude starší verze rozhraní příkazového řádku zastaralá?

Starší verze rozhraní příkazového řádku byla vždy v experimentálním stavu s omezením, že Databricks neplánuje pro starší rozhraní příkazového řádku žádnou novou funkci a starší verze rozhraní příkazového řádku není podporována prostřednictvím kanálů podpory Databricks.

Databricks dosud nenastavil datum ani časovou osu pro vyřazení starší verze rozhraní příkazového řádku. Databricks ale doporučuje, aby uživatelé migrovali na nové rozhraní příkazového řádku co nejdříve.

Kdy bude nové rozhraní příkazového řádku vydáno jako obecně dostupné (GA)?

Datum vydání nebo časový plán pro vydání nového rozhraní příkazového řádku jako GA ještě nebyl stanoven. To bude záviset na zpětné vazbě, kterou Databricks obdrží od uživatelů během verze Public Preview.

Jaké jsou hlavní rozdíly mezi starší verzí a novými rozhraními CLI?

  • Starší verze rozhraní příkazového řádku byla vydána jako balíček Python. Nové rozhraní příkazového řádku je vydáno jako samostatný spustitelný soubor a nevyžaduje nainstalované žádné závislosti modulu runtime.
  • Nové rozhraní příkazového řádku má úplné pokrytí rozhraní REST API Databricks. Starší verze rozhraní příkazového řádku to neumí.
  • Nové rozhraní příkazového řádku je k dispozici ve verzi Public Preview. Starší verze rozhraní příkazového řádku zůstane v experimentálním stavu.

Má nové rozhraní příkazového řádku úplnou paritu funkcí se starší verzí rozhraní příkazového řádku?

Nové rozhraní příkazového řádku má pokrytí téměř všech příkazů ze starší verze rozhraní příkazového řádku. V novém rozhraní příkazového řádku však chybí konkrétně skupina příkazů, která byla ve starší verzi stacks. Také několik starších skupin příkazů CLI, jako unity-catalog a runs, bylo refaktorováno do nových skupin příkazů v novém CLI. Pokyny k migraci najdete v informacích uvedených výše v tomto článku.

Jak migrovat z původního na nové rozhraní příkazového řádku?

Pokyny k migraci najdete v informacích uvedených výše v tomto článku. Všimněte si, že nové rozhraní příkazového řádku není náhradou za starší verzi rozhraní příkazového řádku a vyžaduje, aby se některá nastavení přesunula ze starší verze na nové rozhraní příkazového řádku.

Mohou na stejném počítači existovat instalace starší verze a nových rozhraní CLI?

Ano. Instalace starší verze a nových rozhraní CLI mohou existovat na stejném počítači, ale musí být umístěny v různých adresářích. Vzhledem k tomu, že oba spustitelné soubory jsou pojmenovány databricks, musíte řídit, který spustitelný soubor je spuštěn ve výchozím nastavení konfigurací počítače PATH. Pokud chcete spustit nové rozhraní příkazového řádku, ale nějakým způsobem omylem spustit starší rozhraní příkazového řádku, ve výchozím nastavení starší rozhraní příkazového řádku spustí nové rozhraní příkazového řádku se stejnými argumenty a zobrazí se následující zpráva s upozorněním:

Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>

Because both are installed and available in PATH,
I assume you are trying to run the newer version.

If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>

Jak je znázorněno v předchozí zprávě upozornění, můžete nastavit proměnnou prostředí DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION na 1, abyste zakázali toto chování a místo toho spustili starší rozhraní CLI pro příkazový řádek.

Získání nápovědy

Pokud chcete získat pomoc s migrací ze starší verze rozhraní příkazového řádku na nové rozhraní příkazového řádku, projděte si následující zdroje informací:

  • Last updated on