Sdílet prostřednictvím

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

  • Článek

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:

Odinstalace starší verze rozhraní příkazového řádku

Pokud máte nainstalované starší rozhraní příkazového řádku a chcete ho odinstalovat, spusťte pip ho pomocí příkazu (nebo pip3v závislosti na verzi Pythonu 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ěření instalace 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 virtuální prostředí, conda prostředí nebo podobná prostředí Pythonu.

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í sytem PATH tak, aby byla uvedená 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ředejděte úplnou cestu k verzi rozhraní příkazového řádku, kterou chcete použít pro každé volání rozhraní příkazového řádku a každé 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 ú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. Vypíšete cesty, ve kterých 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ž byste museli předem provést úplnou cestu ke každé a každému volání rozhraní příkazového řádku. Pokud si nejste jistí, která cesta je, spusťte úplnou cestu ke každému umístění následované -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, jestli PATH byla správně nastavená pro aktuální relaci terminálu, spusťte databricks a -v zkontrolujte číslo verze:

    databricks -v

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

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

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 Proměnné <username>uživatele vyberte proměnnou Cesta.

  7. Klikněte na možnost Upravit.

  8. Klepněte na možnost 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 správnost PATH nastavení, otevřete nový příkazový řádek, spusťte a zkontrolujte databricks-včí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í tokenů pat Azure Databricks. Databricks však doporučuje, abyste v případě potřeby používali jiné typy ověřování Azure Databricks, které podporuje jenom nové rozhraní příkazového řádku.

Pokud musíte použít ověřování pomocí tokenu pat pro Azure Databricks, služba Databricks doporučuje použít takový, který je přidružený k instančnímu objektu místo účtu Azure Databricks nebo uživatele pracovního prostoru. Viz Správa instančních objektů.

Nové rozhraní příkazového řádku podporuje tokeny Microsoft Entra ID kromě osobních přístupových tokenů Azure Databricks. Tyto další tokeny jsou bezpečnější, protože obvykle vyprší za jednu hodinu, zatímco osobní přístupové tokeny Azure Databricks můžou být platné od jednoho dne až po neomezenou dobu. To je zvlášť důležité, pokud je token omylem vrácený se změnami do systémů správy verzí, ke kterým mají přístup jiní uživatelé. Nové rozhraní příkazového řádku také může automaticky aktualizovat tyto další tokeny, když vyprší jejich platnost, zatímco aktualizace tokenů pat Azure Databricks je ruční proces nebo může být obtížné je 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ů

Starší 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 možnosti konfigurace.
fs fs. Viz příkazy fs.
groups groups. Viz příkazy skupiny.
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 příkazy kanálů.
repos repos. Všechny názvy příkazů jsou stejné.
runs jobs. Viz příkazy spuštění.
secrets secrets. Podívejte se na příkazy tajných kódů.
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 příkazy tokenů.
unity-catalog Různých. Viz skupiny příkazů unity-catalog.
workspace workspace. Viz příkazy pracovního prostoru.

configure Možnosti

Starší možnost 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 Při zobrazení výzvy místo tokenu pat patu Azure Databricks použijte --host a zadejte token Microsoft Entra ID (dříve Azure Active Directory).
--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> starší verze rozhraní příkazového řádku se stane právě <command> v novém rozhraní příkazového řádku.

Starší skupina příkazů Nová skupina příkazů
unity-catalog catalogs catalogs (stejné, ale pokles unity-catalog)
unity-catalog external-locations external-locations (stejné, ale pokles unity-catalog)
unity-catalog lineage V novém rozhraní příkazového řádku není k dispozici. Viz Načtení rodokmenu pomocí rozhraní REST API rodokmenu dat.
unity-catalog metastores metastores (stejné, ale pokles unity-catalog)
unity-catalog permissions grants
unity-catalog providers providers (stejné, ale pokles unity-catalog)
unity-catalog recipients recipients (stejné, ale pokles unity-catalog)
unity-catalog schemas schemas (stejné, ale pokles unity-catalog)
unity-catalog shares shares (stejné, ale pokles unity-catalog)
unity-catalog storage-credentials storage-credentials (stejné, ale pokles unity-catalog)
unity-catalog tables tables (stejné, ale pokles 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 clusers get ale vyžaduje, abyste zadali --cluster-id možnost spolu s ID clusteru. Příklad:

Starší verze 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 rozhraní příkazového řádku dva výchozí argumenty: zabezpečitelný typ následovaný úplným názvem zabezpečitelného rozhraní příkazového řádku grants get . Příkaz starší verze rozhraní příkazového řádku ale vyžaduje, abyste zadali --<securable-type> možnost spolu s úplným názvem zabezpečitelného rozhraní příkazového řádkuunity-catalog permissions get. Příklad:

Starší verze 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é trasování zásobníku při chybě. 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í za předpokladu, informace protokolu jsou výstupem stderr. Zadání --log-file bez zadání --log-level výsledků také neobsahuje žádné informace protokolu, které se do souboru zapisují.
  • 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í hodnota, pokud není zadána), trace, debug, info, warn, a 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 rozhraní příkazového řádku 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 nenastavila datum nebo č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á osa pro vydání nového rozhraní příkazového řádku, protože ga nebyla vytvořena. 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 Pythonu. 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 není.
  • 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 ale chybí zejména skupina příkazů ve starší verzi rozhraní příkazového řádku stacks . Také několik starších skupin příkazů rozhraní příkazového řádku, jako unity-catalog jsou a runs byly refaktorovány do nových skupin příkazů v novém rozhraní příkazového řádku. Pokyny k migraci najdete v informacích uvedených výše v tomto článku.

Návody migrovat ze starší verze 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 proměnnou prostředí nastavit DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION tak, aby 1 toto chování zakázala, a místo toho spustit starší rozhraní příkazového řádku.

Získání pomoci

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í: