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:

• Rozhraní příkazového řádku Databricks (starší verze) pro starší rozhraní příkazového řádku
• Co je rozhraní příkazového řádku Databricks? pro nové rozhraní příkazového řádku.

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ů

configure volby

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.

groups příkazy

pipelines příkazy

runs příkazy

secrets příkazy

tokens příkazy

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.

workspace příkazy

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

• Centrum nápovědy pro Databricks
• Hodiny kanceláře Databricks