Udostępnij za pośrednictwem

Migracja interfejsu wiersza polecenia usługi Databricks

  • Artykuł

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 wersji 0.205 lub nowszej 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:

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 języka Python), aby uruchomić uninstall polecenie 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 interfejsu wiersza polecenia

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 pamiętaj, aby zamknąć wszystkie środowiska wirtualne, conda środowiska lub podobne środowiska języka Python.

Aby sprawdzić wersję domyślnej instalacji interfejsu wiersza polecenia, uruchom 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 elementów sytem PATH operacyjnych w taki sposób, aby ścieżka do pozostałej wersji interfejsu wiersza polecenia, którego chcesz użyć, znajduje się na liście.
  • Jeśli chcesz nadal używać wielu wersji interfejsu wiersza polecenia: poprzedza pełną ścieżkę do wersji interfejsu wiersza polecenia, której chcesz użyć do każdego i każdego wywołania interfejsu wiersza polecenia.
  • 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 należy nadal poprzedzać pełną ścieżkę do wersji interfejsu wiersza polecenia, które nie są wymienione jako pierwsze w systemie PATHoperacyjnym .

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

Macos lub linux

  1. 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

  2. Pobierz ścieżkę do instalacji, której chcesz użyć bez dołączania pełnej ścieżki do każdego i każdego wywołania interfejsu wiersza polecenia. 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

  3. Aby umieścić ścieżkę do instalacji, której chcesz użyć najpierw w pliku PATH, uruchom następujące polecenie, zastępując /usr/local/bin ciąg ś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"

  4. Aby sprawdzić, czy PATH parametr został poprawnie ustawiony dla bieżącej sesji terminalu, uruchom databricks polecenie i -v sprawdź numer wersji:

    databricks -v

  5. Aby ustawić PATH ten sposób za każdym razem, gdy ponownie uruchomisz terminal, dodaj polecenie z kroku 3 do pliku inicjowania powłoki. Na przykład w przypadku programu ZShell ten plik jest zwykle zlokalizowany w ~/.zshrclokalizacji . W przypadku powłoki Bash ten plik zazwyczaj znajduje się w lokalizacji ~/.bashrc. Inne powłoki można znaleźć w dokumentacji dostawcy powłoki.

  6. Po zaktualizowaniu pliku inicjowania powłoki należy ponownie uruchomić terminal, aby zastosować zaktualizowaną PATH wartość.

Windows

  1. Kliknij prawym przyciskiem myszy instalację databricks , której chcesz użyć bez dołączania pełnej ścieżki do każdego i każdego wywołania interfejsu wiersza polecenia.

  2. Kliknij pozycję Otwórz lokalizację pliku.

  3. Zanotuj ścieżkę do databricks, na przykład C:\Windows.

  4. W menu Start wyszukaj zmienne środowiskowe.

  5. Kliknij pozycję Edytuj zmienne środowiskowe dla konta.

  6. Wybierz zmienną Path w sekcji Zmienne <username> użytkownika.

  7. Kliknij przycisk Edytuj.

  8. Kliknij przycisk Nowy.

  9. Wprowadź ścieżkę, którą chcesz dodać, bez databricks.exe (np C:\Windows. ).

  10. Użyj przycisku Przenieś w górę, aby przenieść właśnie dodaną ścieżkę na początku listy.

  11. Kliknij przycisk OK.

  12. Aby sprawdzić, czy PATH element został poprawnie ustawiony, otwórz nowy wiersz polecenia, uruchom databricks polecenie -vi sprawdź numer wersji:

    databricks -v

Korzystanie z dodatkowych typów uwierzytelniania

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

Jeśli musisz użyć uwierzytelniania osobistego tokenu dostępu usługi Azure Databricks, usługa Databricks zaleca użycie konta usługi skojarzonego z jednostką usługi zamiast konta usługi Azure Databricks lub użytkownika obszaru roboczego. Zobacz Zarządzanie jednostkami usługi.

Nowy interfejs wiersza polecenia obsługuje tokeny identyfikatorów entra firmy Microsoft oprócz osobistych tokenów dostępu usługi Azure Databricks. Te dodatkowe tokeny są bezpieczniejsze, ponieważ zwykle wygasają w ciągu jednej godziny, natomiast osobiste tokeny dostępu usługi Azure Databricks mogą być ważne od jednego dnia do nieokreślonych. 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 nowy interfejs wiersza polecenia może automatycznie odświeżyć te dodatkowe tokeny po wygaśnięciu, natomiast odświeżanie osobistych tokenów dostępu usługi Azure Databricks jest procesem ręcznym lub może być trudne do zautomatyzowania.

Aby uzyskać więcej informacji, zobacz Authentication for the Databricks CLI (Uwierzytelnianie interfejsu wiersza polecenia usługi Databricks).

Porównania grup poleceń i 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ę starszych poleceń interfejsu wiersza polecenia lub opcji oraz ich nowe polecenie lub odpowiedniki opcji.

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 konfigurowanie opcji.
fs fs. Zobacz polecenia fs.
groups groups. Zobacz polecenia grup.
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 polecenia potoków.
repos repos. Wszystkie nazwy poleceń są takie same.
runs jobs. Zobacz polecenia uruchamiania.
secrets secrets. Zobacz polecenia wpisów tajnych.
stack Niedostępne w nowym interfejsie wiersza polecenia. Usługa Databricks zaleca zamiast tego użycie dostawcy narzędzia Terraform usługi Databricks.
tokens tokens. Zobacz polecenia tokenów.
unity-catalog Różnych. Zobacz grupy poleceń wykazu unity.
workspace workspace. Zobacz polecenia obszaru roboczego.

configure Opcje

Starsza opcja Nowa opcja
-o Starszy interfejs wiersza polecenia używa -o uwierzytelniania OAuth. Nowe funkcje -o interfejsu wiersza polecenia umożliwiają określenie, czy dane wyjściowe interfejsu wiersza polecenia są w formacie tekstowym, czy JSON. Nie dotyczy usługi Azure Databricks.
--oauth Nie dotyczy usługi Azure Databricks.
-s lub --scope Nie dotyczy usługi Azure Databricks.
-t lub --token -t lub --token (to samo)
-f lub --token-file Niedostępne w nowym interfejsie wiersza polecenia.
--host --host (to samo)
--aad-token Użyj --host i określ token Microsoft Entra ID (dawniej Azure Active Directory) po wyświetleniu monitu zamiast osobistego tokenu dostępu usługi Azure Databricks.
--insecure Niedostępne w nowym interfejsie wiersza polecenia.
--jobs-api-version Niedostępne w nowym interfejsie wiersza polecenia. 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 uzyskać informacje na temat debugowania i rejestrowania w nowym interfejsie wiersza polecenia, 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 interfejsie wiersza polecenia.
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-eventslub lub pipelines list-pipelinespipelines 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 interfejsie wiersza polecenia. Zobacz Pobieranie pochodzenia przy użyciu interfejsu API REST pochodzenia danych.
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 interfejsu wiersza polecenia clusters get przyjmuje identyfikator klastra jako argument domyślny. Jednak starsze polecenie interfejsu wiersza polecenia clusers get wymaga określenia --cluster-id opcji wraz 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 interfejsu wiersza polecenia:

# 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 nowego interfejsu wiersza polecenia przyjmuje dwa argumenty domyślne: zabezpieczany typ, po którym następuje pełna nazwa zabezpieczanego interfejsu wiersza polecenia grants get . Jednak starsze polecenie interfejsu wiersza polecenia wymaga określenia --<securable-type> opcji wraz z pełną nazwą zabezpieczanego interfejsu wiersza poleceniaunity-catalog permissions get. Na przykład:

W przypadku starszego interfejsu wiersza polecenia:

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

Dla nowego interfejsu wiersza polecenia:

# 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 udostępnia --debug opcję wyświetlania pełnego śledzenia stosu w przypadku błędu. W przypadku nowego interfejsu wiersza polecenia --debug opcja nie jest rozpoznawana. Zamiast tego użyj następujących opcji:

  • Użyj --log-file <path> polecenia , aby zapisać informacje dziennika w pliku określonym w <path>pliku . Jeśli ta opcja nie zostanie podana, informacje dziennika są danymi wyjściowymi narzędzia stderr. Określanie --log-file bez określania powoduje również, że --log-level ż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 po błędzie:

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ę dokumentacji . Usługa Databricks zaleca, aby użytkownicy migrowali do nowego interfejsu wiersza polecenia tak szybko, jak to możliwe.

Starszy interfejs wiersza polecenia zawsze był w stanie eksperymentalnym z zastrzeżeniem, że usługa Databricks nie planuje nowej funkcji dla starszego interfejsu wiersza polecenia, a starszy interfejs wiersza polecenia nie jest obsługiwany za pośrednictwem kanałów pomocy technicznej usługi Databricks.

Kiedy starszy interfejs wiersza polecenia będzie przestarzały?

Starszy interfejs wiersza polecenia zawsze był w stanie eksperymentalnym z zastrzeżeniem, że usługa Databricks nie planuje nowej funkcji dla starszego interfejsu wiersza polecenia, a starszy interfejs wiersza polecenia nie jest obsługiwany za pośrednictwem kanałów pomocy technicznej usługi Databricks.

Usługa Databricks nie ustanowiła daty ani osi czasu 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 nowy interfejs wiersza polecenia zostanie wydany jako ogólnie dostępny ??

Data wydania lub oś czasu wydania nowego interfejsu wiersza polecenia jako ogólnie dostępna nie została ustanowiona. 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 języka 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łny zakres interfejsów API REST usługi Databricks. Starszy interfejs wiersza polecenia nie.
  • Nowy interfejs wiersza polecenia jest dostępny jako publiczna wersja zapoznawcza. Starszy interfejs wiersza polecenia pozostaje w stanie eksperymentalnym.

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

Nowy interfejs wiersza polecenia ma pokrycie dla prawie wszystkich poleceń ze starszego interfejsu wiersza polecenia. Jednak szczególnie nieobecny w nowym interfejsie wiersza polecenia jest stacks grupa poleceń w starszym interfejsie 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ę ze starszej wersji do nowego interfejsu wiersza polecenia?

Aby uzyskać wskazówki dotyczące migracji, zobacz informacje podane wcześniej w tym artykule. Należy pamiętać, że nowy interfejs wiersza polecenia nie zastępuje starszego interfejsu wiersza polecenia i wymaga, aby niektóre konfiguracje przechodziły ze starszej wersji do nowego interfejsu wiersza polecenia.

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ą DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION środowiskową tak, aby 1 wyłączyć to zachowanie i zamiast tego uruchomić starszy interfejs wiersza polecenia.

Uzyskaj pomoc

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