Migracja CLI Databricks

W tym artykule opisano sposób migracji z interfejsu wiersza polecenia usługi Databricks w wersji 0.18 lub nowszej do interfejsu wiersza polecenia usługi Databricks w wersji 0.205 lub nowszej. Interfejs wiersza polecenia usługi Databricks w wersjach 0.205 lub nowszych jest w publicznej wersji zapoznawczej.

W przypadku zwięzłości ten artykuł odnosi się do interfejsu wiersza polecenia usługi Databricks w wersji 0.18 i poniżej jako "starszego" interfejsu wiersza polecenia oraz interfejsu wiersza polecenia usługi Databricks w wersji 0.205 lub nowszej jako "nowy" interfejs wiersza polecenia.

Aby uzyskać więcej informacji na temat starszych i nowych interfejsów API, zobacz:

Legacy Databricks CLI dla starszego interfejsu wiersza polecenia
Databricks CLI dla nowego CLI.

Odinstalowywanie starszego interfejsu wiersza polecenia

Jeśli masz zainstalowany starszy interfejs wiersza polecenia i chcesz go odinstalować, użyj polecenia pip (lub pip3, w zależności od wersji Python), aby uruchomić polecenie uninstall w następujący sposób:

pip uninstall databricks-cli

Instalowanie nowego interfejsu wiersza polecenia

Aby dowiedzieć się, jak zainstalować nowy interfejs wiersza polecenia, zobacz Instalowanie lub aktualizowanie interfejsu wiersza polecenia usługi Databricks.

Weryfikowanie instalacji CLI

Jeśli nie masz pewności, czy używasz nowego interfejsu wiersza polecenia, postępuj zgodnie z instrukcjami w tej sekcji, aby zweryfikować i dostosować je zgodnie z potrzebami. Przed wykonaniem tych instrukcji, upewnij się, że opuścisz wszystkie środowiska wirtualne Pythona, conda środowiska lub podobne środowiska.

Aby sprawdzić wersję domyślnej instalacji CLI, wykonaj następujące polecenie:

databricks -v

Jeśli numer wersji nie jest oczekiwany, wykonaj jedną z następujących czynności:

Jeśli chcesz użyć tylko jednej wersji interfejsu wiersza polecenia: odinstaluj całą poprzednią wersję interfejsu wiersza polecenia, której nie chcesz już używać. Może być konieczne zaktualizowanie systemu PATH operacyjnego w taki sposób, aby ścieżka do pozostałej wersji interfejsu wiersza polecenia, której chcesz użyć, znajduje się na liście.
Jeśli chcesz nadal używać wielu wersji interfejsu wiersza polecenia: poprzedzaj pełną ścieżkę do wersji interfejsu wiersza polecenia, której chcesz użyć, do każdego wywołania.
Jeśli chcesz nadal używać wielu wersji interfejsu wiersza polecenia, ale nie chcesz kontynuować wprowadzania pełnej ścieżki do wersji interfejsu wiersza polecenia, której używasz najczęściej: upewnij się, że pełna ścieżka do tej wersji jest wymieniona jako pierwsza w systemie PATHoperacyjnym . Należy pamiętać, że nadal trzeba poprzedzać pełną ścieżkę do wersji interfejsu wiersza polecenia, które nie są wymienione jako pierwsze w systemie operacyjnym PATH.

Aby zaktualizować system PATHoperacyjny , wykonaj następujące czynności:

MacOS lub Linux

Wyświetl listę ścieżek, w których databricks jest zainstalowany, uruchamiając jedno z następujących poleceń:
```
which -a databricks

# Or:
where databricks
```
Pobierz ścieżkę do instalacji, której chcesz użyć, bez dołączania pełnej ścieżki do każdego wywołania CLI. Jeśli nie masz pewności, która ścieżka jest taka, uruchom pełną ścieżkę do każdej lokalizacji, a następnie -v, na przykład:
```
/usr/local/bin/databricks -v
```
Aby ustawić ścieżkę do instalacji, której chcesz użyć jako pierwszej w PATH, uruchom następujące polecenie, zastępując /usr/local/bin ścieżką, której chcesz użyć. Nie należy dodawać databricks na końcu tej ścieżki. Na przykład:
```
export PATH="/usr/local/bin:$PATH"
```
Aby sprawdzić, czy parametr PATH został poprawnie ustawiony dla bieżącej sesji terminalu, uruchom polecenie databricks, a następnie sprawdź za pomocą -v numer wersji.
```
databricks -v
```
Aby ustawić PATH w ten sposób za każdym razem, gdy ponownie uruchomisz terminal, dodaj polecenie z kroku 3 do pliku startowego powłoki. Na przykład w przypadku programu ZShell ten plik jest zwykle zlokalizowany w ~/.zshrc. W przypadku powłoki Bash ten plik zazwyczaj znajduje się w lokalizacji ~/.bashrc. Aby uzyskać informacje o innych powłokach, zapoznaj się z dokumentacją dostawcy powłoki.
Po zaktualizowaniu pliku inicjowania powłoki należy ponownie uruchomić terminal, aby zastosować zaktualizowaną PATH wartość.

Windows

Kliknij prawym przyciskiem myszy instalację databricks, której chcesz użyć, bez dołączania pełnej ścieżki do każdego wywołania interfejsu wiersza polecenia (CLI).
Kliknij pozycję Otwórz lokalizację pliku.
Zanotuj ścieżkę do databricks, na przykład C:\Windows.
W menu Start wyszukaj zmienne środowiskowe.
Kliknij pozycję Edytuj zmienne środowiskowe dla konta.
Wybierz zmienną Path w sekcji Zmienne <username>użytkownika.
Kliknij pozycję Edytuj.
Kliknij pozycję Nowy.
Wprowadź ścieżkę, którą chcesz dodać bez databricks.exe (na przykład C:\Windows).
Użyj przycisku Przenieś w górę, aby przenieść właśnie dodaną ścieżkę na początku listy.
Kliknij przycisk OK.
Aby sprawdzić, czy PATH został poprawnie ustawiony, otwórz nowy wiersz polecenia, uruchom databricks, a następnie -v, i sprawdź numer wersji:
```
databricks -v
```

Korzystanie z dodatkowych typów uwierzytelniania

Dziedziczny CLI i nowy CLI obsługują uwierzytelnianie za pomocą osobistego tokenu dostępu Azure Databricks. Jednak usługa Databricks zaleca używanie innych Azure Databricks typów uwierzytelniania, jeśli to możliwe, które obsługuje tylko nowy interfejs wiersza polecenia.

Jeśli musisz użyć Azure Databricks do uwierzytelniania za pomocą osobistego tokenu dostępu, Databricks zaleca użycie takiego tokenu, który jest powiązany z tożsamością jednostki usługi, zamiast z kontem Azure Databricks lub użytkownikiem przestrzeni roboczej. Zobacz Jednostki usługi.

Nowy CLI obsługuje tokeny Microsoft Entra ID oprócz tokenów dostępu osobistych w Azure Databricks. Te dodatkowe tokeny są bezpieczniejsze, ponieważ zwykle wygasają w ciągu jednej godziny, podczas gdy osobiste tokeny dostępu Azure Databricks mogą być ważne od jednego dnia do nieograniczonego czasu. Jest to szczególnie ważne, jeśli token jest przypadkowo zaewidencjonowany w systemach kontroli wersji, do których można uzyskać dostęp przez inne osoby. Ponadto nowe CLI może automatycznie odświeżać te dodatkowe tokeny po wygaśnięciu, podczas gdy odświeżanie osobistych tokenów dostępu Azure Databricks jest procesem ręcznym lub może być trudne do zautomatyzowania.

Aby uzyskać więcej informacji, zobacz Uwierzytelnianie dla interfejsu wiersza poleceń Databricks.

Grupa poleceń i porównania poleceń

W poniższej tabeli wymieniono starsze grupy poleceń interfejsu wiersza polecenia i ich nowe odpowiedniki grup poleceń interfejsu wiersza polecenia. Jeśli istnieją znaczące różnice między interfejsami wiersza polecenia, dodatkowe tabele zawierają listę poleceń z przestarzałych wersji interfejsu wiersza polecenia lub opcji oraz ich nowe odpowiedniki.

Grupy poleceń

Starsza grupa poleceń	Nowa grupa poleceń
`cluster-policies`	`cluster-policies`. Wszystkie nazwy poleceń są takie same.
`clusters`	`clusters`. Wszystkie nazwy poleceń są takie same.
`configure`	`configure`. Zobacz `configure` opcje.
`fs`	`fs`. Zobacz `fs` polecenia.
`groups`	`groups`. Zobacz `groups` polecenia.
`instance-pools`	`instance-pools`. Wszystkie nazwy poleceń są takie same.
`jobs`	`jobs`. Wszystkie nazwy poleceń są takie same.
`libraries`	`libraries`. Wszystkie nazwy poleceń są takie same z wyjątkiem .`list` Polecenie `list` nie jest już dostępne; zamiast tego użyj `all-cluster-statuses` poleceń lub `cluster-status` .
`pipelines`	`pipelines`. Zobacz `pipelines` polecenia.
`repos`	`repos`. Wszystkie nazwy poleceń są takie same.
`runs`	`jobs`. Zobacz `runs` polecenia.
`secrets`	`secrets`. Zobacz `secrets` polecenia.
`stack`	Niedostępne w nowym CLI. Databricks zaleca użycie dostawcę Terraform dla Databricks zamiast tego.
`tokens`	`tokens`. Zobacz `tokens` polecenia.
`unity-catalog`	Rozmaity. Zobacz `unity-catalog` grupy poleceń.
`workspace`	`workspace`. Zobacz `workspace` polecenia.

`configure` Opcje

Starsza opcja	Nowa opcja
`-o`	Starszy CLI używa `-o` do uwierzytelniania OAuth. Nowy interfejs wiersza polecenia wykorzystuje `-o` do określenia, czy dane wyjściowe interfejsu są w formacie tekstowym, czy JSON. Nie dotyczy Azure Databricks.
`--oauth`	Nie dotyczy Azure Databricks.
`-s` lub `--scope`	Nie dotyczy Azure Databricks.
`-t` lub `--token`	`-t` lub `--token` (to samo)
`-f` lub `--token-file`	Niedostępne w nowym CLI.
`--host`	`--host` (to samo)
`--aad-token`	Użyj `--host` i określ token Microsoft Entra ID, gdy zostaniesz o to poproszony, zamiast osobistego tokenu dostępu Azure Databricks.
`--insecure`	Niedostępne w nowym CLI.
`--jobs-api-version`	Niedostępne w nowym CLI. Nowy interfejs wiersza polecenia używa tylko interfejsu API zadań 2.1. Aby wywołać starszy interfejs API zadań 2.0, użyj starszego interfejsu wiersza polecenia i zobacz Interfejs wiersza polecenia zadań (starsza wersja).
`--debug`	Aby debugować i rejestrować w nowym CLI, zobacz Tryb debugowania.
`--profile`	`--profile` (takie same) lub `-p`
`-h` lub `--help`	`-h` lub `--help` (to samo)

`fs` Polecenia

Wszystkie fs polecenia w starszym interfejsie wiersza polecenia są takie same w nowym interfejsie wiersza polecenia, z fs mv wyjątkiem tych poleceń, które nie są dostępne w nowym interfejsie wiersza polecenia.

Starsze polecenie	Nowe polecenie
`fs cat`	`fs cat` (to samo)
`fs cp`	`fs cp` (to samo)
`fs ls`	`fs ls` (to samo)
`fs mkdirs`	`fs mkdir`
`fs mv`	Niedostępne w nowym CLI.
`fs rm`	`fs rm` (to samo)

`groups` Polecenia

Starsze polecenie	Nowe polecenie
`groups add-member`	`groups patch`
`groups create`	`groups create` (to samo)
`groups delete`	`groups delete` (to samo)
`groups list`	`groups list` (to samo)
`groups list-members`	`groups list`
`groups list-parents`	`groups list`
`groups remove-member`	`groups patch`

`pipelines` Polecenia

Starsze polecenie	Nowe polecenie
`pipelines create`	`pipelines create` (to samo)
`pipelines delete`	`pipelines delete` (to samo)
`pipelines deploy`	`pipelines create`
`pipelines edit`	`pipelines update`
`pipelines get`	`pipelines get` (to samo)
`pipelines list`	`pipelines list-pipeline-events` lub `pipelines list-pipelines` lub `pipelines list-updates`
`pipelines reset`	`pipelines reset` (to samo)
`pipelines start`	`pipelines start update`
`pipelines stop`	`pipelines stop` (to samo)
`pipelines update`	`pipelines update` (to samo)

`runs` Polecenia

Starsze polecenie	Nowe polecenie
`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` Polecenia

Starsze polecenie	Nowe polecenie
`secrets create-scope`	`secrets create-scope` (to samo)
`secrets delete`	`secrets delete-secret`
`secrets delete-acl`	`secrets delete-acl` (to samo)
`secrets delete-scope`	`secrets delete-scope` (to samo)
`secrets get-acl`	`secrets get-acl` (to samo)
`secrets list`	`secrets list-secrets`
`secrets list-acls`	`secrets list-acls` (to samo)
`secrets list-scopes`	`secrets list-scopes` (to samo)
`secrets put`	`secrets put-secret`
`secrets put-acl`	`secrets put-acl` (to samo)
`secrets write`	`secrets put-secret`
`secrets write-acl`	`secrets put-acl`

`tokens` Polecenia

Starsze polecenie	Nowe polecenie
`tokens create`	`tokens create` (to samo)
`tokens list`	`tokens list` (to samo)
`tokens revoke`	`tokens delete`

`unity-catalog` grupy poleceń

unity-catalog <command> w starszym interfejsie wiersza polecenia dopiero <command> w nowym interfejsie wiersza polecenia.

Starsza grupa poleceń	Nowa grupa poleceń
`unity-catalog catalogs`	`catalogs` (to samo, ale upuść `unity-catalog`)
`unity-catalog external-locations`	`external-locations` (to samo, ale upuść `unity-catalog`)
`unity-catalog lineage`	Niedostępne w nowym CLI. Zobacz linie pochodzenia danych przy użyciu Unity Catalog.
`unity-catalog metastores`	`metastores` (to samo, ale upuść `unity-catalog`)
`unity-catalog permissions`	`grants`
`unity-catalog providers`	`providers` (to samo, ale upuść `unity-catalog`)
`unity-catalog recipients`	`recipients` (to samo, ale upuść `unity-catalog`)
`unity-catalog schemas`	`schemas` (to samo, ale upuść `unity-catalog`)
`unity-catalog shares`	`shares` (to samo, ale upuść `unity-catalog`)
`unity-catalog storage-credentials`	`storage-credentials` (to samo, ale upuść `unity-catalog`)
`unity-catalog tables`	`tables` (to samo, ale upuść `unity-catalog`)

`workspace` Polecenia

Starsze polecenie	Nowe polecenie
`workspace delete`	`workspace delete` (to samo)
`workspace export`	`workspace export` (to samo)
`workspace export-dir`	`workspace export`
`workspace import`	`workspace import` (to samo)
`workspace import-dir`	`workspace import`
`workspace list`	`workspace list` (to samo)
`workspace ls`	`workspace list`
`workspace mkdirs`	`workspace mkdirs` (to samo)
`workspace rm`	`workspace delete`

Argumenty domyślne i pozycyjne

Większość nowych poleceń interfejsu wiersza polecenia ma co najmniej jeden argument domyślny, który nie ma towarzyszącej opcji. Niektóre nowe polecenia interfejsu wiersza polecenia mają co najmniej dwa argumenty pozycyjne, które muszą być określone w określonej kolejności i które nie mają towarzyszących opcji. Różni się to od starszego interfejsu wiersza polecenia, w którym większość poleceń wymaga określenia opcji dla wszystkich argumentów. Na przykład polecenie nowego CLI clusters get przyjmuje identyfikator klastra jako standardowy argument. Jednak starsze polecenie wiersza polecenia clusters get wymaga podania opcji --cluster-id razem z identyfikatorem klastra. Na przykład:

W przypadku starszego interfejsu wiersza polecenia:

# 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

Dla nowego CLI:

# 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

W innym przykładzie polecenie grants get nowego CLI przyjmuje dwa argumenty domyślne: typ zabezpieczanego obiektu, po którym następuje pełna nazwa tego obiektu. Jednak starsze polecenie CLI wymaga określenia opcji unity-catalog permissions get wraz z pełną nazwą zabezpieczanego obiektu. Na przykład:

W przypadku starszego interfejsu wiersza polecenia:

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

Dla nowego CLI:

# 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

Tryb debugowania

Starszy interfejs wiersza polecenia zapewnia opcję --debug do wyświetlania pełnego śledzenia stosu w przypadku błędu. W przypadku nowego CLI opcja --debug nie jest rozpoznawana. Zamiast tego użyj następujących opcji:

Użyj --log-file <path> do zapisania informacji dziennika w pliku określonym w <path>. Jeśli ta opcja nie zostanie podana, informacje dziennika są danymi wyjściowymi narzędzia stderr. Określenie --log-file bez jednoczesnego określenia --log-level powoduje, że żadne informacje dziennika nie są zapisywane w pliku.
Użyj --log-format <type> polecenia , aby określić format zarejestrowanych informacji. <type> może to być text (wartość domyślna, jeśli nie została określona) lub json.
Użyj --log-level <format> polecenia , aby określić poziom zarejestrowanych informacji. Dozwolone wartości to disabled (wartość domyślna, jeśli nie została określona), trace, , debuginfo, warni error.

W przypadku starszego interfejsu wiersza polecenia w poniższym przykładzie przedstawiono pełny ślad stosu w przypadku błędu.

databricks fs ls / --debug

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

W przypadku nowego interfejsu wiersza polecenia poniższy przykład rejestruje pełny ślad stosu do pliku o nazwie new-cli-errors.log w bieżącym katalogu roboczym. Ślad stosu jest zapisywany w pliku w formacie 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.)

Często zadawane pytania

W tej sekcji wymieniono typowe pytania dotyczące migracji ze starszej wersji do nowego interfejsu wiersza polecenia.

Co się dzieje ze starszym interfejsem wiersza polecenia?

Starszy interfejs wiersza polecenia jest nadal dostępny, ale nie otrzymuje żadnych aktualizacji niekrytycznych. Starsza dokumentacja interfejsu wiersza polecenia odzwierciedla tę dokumentację. Usługa Databricks zaleca, aby użytkownicy migrowali do nowego interfejsu wiersza polecenia tak szybko, jak to możliwe.

Starszy CLI zawsze był w stanie eksperymentalnym z zastrzeżeniem, że Databricks nie planuje wdrażania nowych funkcji dla starszego CLI, a starszy CLI nie jest obsługiwany poprzez kanały wsparcia Databricks.

Kiedy starszy interfejs wiersza polecenia zostanie zdezaktualizowany?

Usługa Databricks nie określiła daty ani harmonogramu wycofania starszego interfejsu wiersza polecenia. Jednak usługa Databricks zaleca, aby użytkownicy migrowali do nowego interfejsu wiersza polecenia tak szybko, jak to możliwe.

Kiedy nowe CLI zostanie wydane jako wersja ogólnodostępna?

Data wydania lub harmonogram wydania nowego interfejsu wiersza polecenia (CLI) jako ogólna dostępność (GA) nie zostały jeszcze ustalone. Będzie to zależeć od opinii otrzymywanych przez usługę Databricks od użytkowników w publicznej wersji zapoznawczej.

Jakie są kluczowe różnice między starszymi i nowymi interfejsami CLI?

Starszy interfejs wiersza polecenia został wydany jako pakiet Python. Nowy interfejs wiersza polecenia jest udostępniany jako autonomiczny plik wykonywalny i nie wymaga zainstalowanych żadnych zależności środowiska uruchomieniowego.
Nowy interfejs wiersza polecenia ma pełne pokrycie API REST Databricks. Starszy interfejs wiersza polecenia tego nie robi.
Nowy interfejs wiersza polecenia (CLI) jest dostępny jako publiczna wersja zapoznawcza. Starszy CLI pozostaje nadal w fazie eksperymentalnej.

Czy nowy interfejs wiersza polecenia ma pełną równoważność funkcji ze starszym interfejsem wiersza polecenia?

Nowy CLI obsługuje prawie wszystkie polecenia ze starszej wersji CLI. Jednak w nowym interfejsie wiersza polecenia brakuje grupy poleceń stacks ze starszego interfejsu wiersza polecenia. Ponadto kilka starszych grup poleceń interfejsu wiersza polecenia, takich jak unity-catalog i runs zostały refaktoryzowane do nowych grup poleceń w nowym interfejsie wiersza polecenia. Aby uzyskać wskazówki dotyczące migracji, zobacz informacje podane wcześniej w tym artykule.

Jak mogę przeprowadzić migrację z dziedzicznego do nowego interfejsu wiersza polecenia (CLI)?

Aby uzyskać wskazówki dotyczące migracji, zobacz informacje podane wcześniej w tym artykule. Należy pamiętać, że nowy CLI nie jest zamiennikiem starszego CLI i wymaga pewnej konfiguracji, aby przejść ze starszej wersji na nowy CLI.

Czy na tej samej maszynie mogą istnieć instalacje starszych i nowych interfejsów CLI?

Tak. Instalacje starszych i nowych interfejsów API mogą istnieć na tej samej maszynie, ale muszą znajdować się w różnych katalogach. Ponieważ pliki wykonywalne mają obie nazwy databricks, należy kontrolować, który plik wykonywalny jest uruchamiany domyślnie, konfigurując maszynę PATH. Jeśli chcesz uruchomić nowy interfejs wiersza polecenia, ale w jakiś sposób przypadkowo uruchomisz starszy interfejs wiersza polecenia, domyślnie starszy interfejs wiersza polecenia uruchomi nowy interfejs wiersza polecenia z tymi samymi argumentami i wyświetli następujący komunikat ostrzegawczy:

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 pokazano w poprzednim komunikacie ostrzegawczym, możesz ustawić zmienną środowiskową DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION na 1 w celu wyłączenia tego zachowania i uruchomienia starszego CLI.

Uzyskaj pomoc

Aby uzyskać pomoc dotyczącą migracji ze starszego interfejsu wiersza polecenia do nowego interfejsu wiersza polecenia, zobacz następujące zasoby:

Centrum pomocy Databricks

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-19