Поделиться через

Миграция интерфейса командной строки Databricks

В этой статье описывается, как выполнить миграцию из Databricks CLI версии 0.18 или ниже в Databricks CLI версии 0.205 или более поздней. Интерфейс командной строки Databricks версии 0.205 и выше находятся в общедоступной предварительной версии.

Для краткости эта статья относится к Databricks CLI версии 0.18 и ниже, как к интерфейсу командной строки прежних версий и Databricks CLI версии 0.205 и выше, как к новому интерфейсу командной строки.

Дополнительные сведения о устаревших и новых clis см. в следующих статье:

Удаление устаревшего интерфейса командной строки

Если у вас установлен устаревший интерфейс командной строки и вы хотите удалить ее, используйте pip (или pip3, в зависимости от версии Python), чтобы выполнить uninstall команду, как показано ниже.

pip uninstall databricks-cli

Установка нового интерфейса командной строки

Сведения об установке нового интерфейса командной строки см. в статье "Установка или обновление интерфейса командной строки Databricks".

Проверка установки CLI

Если вы не уверены, используете ли вы новый интерфейс командной строки, следуйте инструкциям в этом разделе, чтобы проверить и настроить их по мере необходимости. Прежде чем следовать этим инструкциям, обязательно закройте все виртуальные среды Python, conda среды или аналогичные среды.

Чтобы проверить версию установки по умолчанию интерфейса командной строки, выполните следующую команду:

databricks -v

Если номер версии не является ожидаемым, выполните одно из следующих действий:

  • Если вы хотите использовать только одну версию интерфейса командной строки: удалите все предыдущие версии интерфейса командной строки, которую вы больше не хотите использовать. Возможно, потребуется обновить вашу операционную систему PATH, чтобы путь к версии интерфейса командной строки, которую вы хотите использовать, был указан.
  • Если вы хотите продолжать использовать несколько версий интерфейса командной строки: предопределите полный путь к версии интерфейса командной строки, которую вы хотите использовать для каждого и каждого вызова интерфейса командной строки.
  • Если вы хотите продолжать использовать несколько версий интерфейса командной строки, но не хотите каждый раз добавлять полный путь к той версии, которую вы используете чаще всего: убедитесь, что полный путь к этой версии указан первым в настройках вашей операционной системы. Обратите внимание, что вы по-прежнему должны указать полный путь к версиям интерфейса командной строки, которые не указаны в вашей операционной системе PATH.

Чтобы обновить операционную систему PATH, сделайте следующее:

MacOS или Linux

  1. Выведите список путей, в которых databricks установлено, выполнив одну из следующих команд:

    which -a databricks

# Or:
where databricks

  2. Путь к установке, которую вы хотите использовать, не добавляя полный путь к каждому и каждому вызову интерфейса командной строки. Если вы не уверены, какой путь это, выполните полный путь к каждому расположению, а затем -v, например:

    /usr/local/bin/databricks -v

  3. Чтобы поместить путь к установке, которую вы хотите использовать сначала в вашей PATH, выполните следующую команду, заменив /usr/local/bin путь, который вы хотите использовать. Не добавляйте databricks в конец этого пути. Например:

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

  4. Чтобы проверить правильность PATH установки текущего сеанса терминала, выполните databricks и -v проверьте номер версии:

    databricks -v

  5. PATH Чтобы задать этот способ при каждом перезапуске терминала, добавьте команду из шага 3 в файл инициализации оболочки. Например, для Zshell этот файл обычно находится в ~/.zshrcпапке . Для Bash этот файл обычно находится по ~/.bashrcадресу. Сведения о других оболочках см. в документации поставщика оболочки.

  6. После обновления файла инициализации оболочки необходимо перезапустить терминал, чтобы применить обновленное PATH значение.

Виндоус

  1. Щелкните правой кнопкой мыши установку databricks , которую вы хотите использовать, не добавляя полный путь к каждому и каждому вызову интерфейса командной строки.

  2. Щелкните "Открыть расположение файла".

  3. Обратите внимание на путь, databricksнапример C:\Windows.

  4. В меню "Пуск" найдите переменные среды.

  5. Щелкните "Изменить переменные среды" для учетной записи.

  6. Выберите переменную Path в переменных пользователя для <username> раздела.

  7. Выберите Изменить.

  8. Нажмите кнопку Создать.

  9. Введите путь, который вы хотите добавить, без databricks.exe (например C:\Windows, ).

  10. Нажмите кнопку "Переместить вверх ", чтобы переместить путь, который вы только что добавили в начало списка.

  11. Щелкните OK.

  12. Чтобы проверить PATH правильность установки, откройте новую командную строку, запустите databricks-vи проверьте номер версии:

    databricks -v

Использование дополнительных типов проверки подлинности

Устаревший интерфейс командной строки и новый интерфейс командной строки поддерживают проверку подлинности личного маркера доступа Azure Databricks. Однако Databricks рекомендует использовать другие типы проверки подлинности Azure Databricks, которые поддерживают только новый интерфейс командной строки.

Если необходимо использовать проверку подлинности маркера личного доступа Azure Databricks, Databricks рекомендует использовать его, связанный с субъектом-службой, а не учетной записью Azure Databricks или пользователем рабочей области. См. Субъекты-службы.

Новый интерфейс командной строки поддерживает маркеры идентификатора Microsoft Entra в дополнение к личным маркерам доступа Azure Databricks. Эти дополнительные маркеры являются более безопасными, так как они обычно истекают в течение одного часа, в то время как личные маркеры доступа Azure Databricks могут быть действительными с одного дня до неопределенного времени. Это особенно важно, если маркер случайно проверяется в системах управления версиями, к которым можно получить доступ другим пользователям. Кроме того, новый интерфейс командной строки может автоматически обновлять эти дополнительные маркеры при истечении срока действия, в то время как обновление личных маркеров доступа Azure Databricks является ручным процессом или может быть сложно автоматизировать.

Дополнительные сведения см. в разделе "Проверка подлинности" для интерфейса командной строки Databricks.

Сравнения групп команд и команд

В следующей таблице перечислены устаревшие группы команд CLI и их новые эквиваленты группы команд CLI. Где существуют значительные различия между clIs, дополнительные таблицы перечисляют устаревшие команды или параметры CLI и их новые команды CLI или эквиваленты параметров.

Группы команд

Устаревшая группа команд Новая группа команд
cluster-policies cluster-policies. Все имена команд одинаковы.
clusters clusters. Все имена команд одинаковы.
configure configure. См. параметры configure.
fs fs. См. fs команды.
groups groups. См. groups команды.
instance-pools instance-pools. Все имена команд одинаковы.
jobs jobs. Все имена команд одинаковы.
libraries libraries. Все имена команд одинаковы, кроме list. Команда list больше не доступна; используйте all-cluster-statuses вместо этого команды или cluster-status команды.
pipelines pipelines. См. pipelines команды.
repos repos. Все имена команд одинаковы.
runs jobs. См. runs команды.
secrets secrets. См. secrets команды.
stack Недоступно в новом интерфейсе командной строки. Databricks рекомендует вместо этого использовать поставщик Databricks Terraform.
tokens tokens. См. tokens команды.
unity-catalog Различный. См. unity-catalog группы команд.
workspace workspace. См. workspace команды.

configure параметры

Вариант прежних версий Новый параметр
-o Устаревший интерфейс командной строки используется -o для проверки подлинности OAuth. Новый интерфейс командной строки позволяет -o указать, находится ли выходные данные CLI в текстовом или формате JSON. Неприменимо к Azure Databricks.
--oauth Неприменимо к Azure Databricks.
-s или --scope Неприменимо к Azure Databricks.
-t или --token -t или --token (то же)
-f или --token-file Недоступно в новом интерфейсе командной строки.
--host --host (то же самое)
--aad-token Используйте --host и укажите маркер идентификатора Microsoft Entra при появлении запроса вместо личного маркера доступа Azure Databricks.
--insecure Недоступно в новом интерфейсе командной строки.
--jobs-api-version Недоступно в новом интерфейсе командной строки. Новый интерфейс командной строки использует только API заданий 2.1. Чтобы вызвать api устаревших заданий 2.0, используйте устаревший интерфейс командной строки и ознакомьтесь с интерфейсом командной строки заданий (устаревшей версией).
--debug Сведения об отладке и входе в новый режим отладки cli см . в разделе "Режим отладки".
--profile --profile (то же самое) или -p
-h или --help -h или --help (то же)

Команды fs.

Все fs команды в устаревшем интерфейсе командной строки одинаковы в новом интерфейсе командной строки, за исключением fs mv того, что она недоступна в новом интерфейсе командной строки.

Устаревшая команда Новая команда
fs cat fs cat (то же самое)
fs cp fs cp (то же самое)
fs ls fs ls (то же самое)
fs mkdirs fs mkdir
fs mv Недоступно в новом интерфейсе командной строки.
fs rm fs rm (то же самое)

Команды groups.

Устаревшая команда Новая команда
groups add-member groups patch
groups create groups create (то же самое)
groups delete groups delete (то же самое)
groups list groups list (то же самое)
groups list-members groups list
groups list-parents groups list
groups remove-member groups patch

Команды pipelines.

Устаревшая команда Новая команда
pipelines create pipelines create (то же самое)
pipelines delete pipelines delete (то же самое)
pipelines deploy pipelines create
pipelines edit pipelines update
pipelines get pipelines get (то же самое)
pipelines list pipelines list-pipeline-events или pipelines list-pipelines или pipelines list-updates
pipelines reset pipelines reset (то же самое)
pipelines start pipelines start update
pipelines stop pipelines stop (то же самое)
pipelines update pipelines update (то же самое)

Команды runs.

Устаревшая команда Новая команда
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.

Устаревшая команда Новая команда
secrets create-scope secrets create-scope (то же самое)
secrets delete secrets delete-secret
secrets delete-acl secrets delete-acl (то же самое)
secrets delete-scope secrets delete-scope (то же самое)
secrets get-acl secrets get-acl (то же самое)
secrets list secrets list-secrets
secrets list-acls secrets list-acls (то же самое)
secrets list-scopes secrets list-scopes (то же самое)
secrets put secrets put-secret
secrets put-acl secrets put-acl (то же самое)
secrets write secrets put-secret
secrets write-acl secrets put-acl

Команды tokens.

Устаревшая команда Новая команда
tokens create tokens create (то же самое)
tokens list tokens list (то же самое)
tokens revoke tokens delete

unity-catalog группы команд

unity-catalog <command> в устаревшем интерфейсе командной строки становится только <command> в новом интерфейсе командной строки.

Устаревшая группа команд Новая группа команд
unity-catalog catalogs catalogs (то же самое, но падение unity-catalog)
unity-catalog external-locations external-locations (то же самое, но падение unity-catalog)
unity-catalog lineage Недоступно в новом интерфейсе командной строки. См. статью "Получение происхождения данных" с помощью REST API data lineage.
unity-catalog metastores metastores (то же самое, но падение unity-catalog)
unity-catalog permissions grants
unity-catalog providers providers (то же самое, но падение unity-catalog)
unity-catalog recipients recipients (то же самое, но падение unity-catalog)
unity-catalog schemas schemas (то же самое, но падение unity-catalog)
unity-catalog shares shares (то же самое, но падение unity-catalog)
unity-catalog storage-credentials storage-credentials (то же самое, но падение unity-catalog)
unity-catalog tables tables (то же самое, но падение unity-catalog)

Команды workspace.

Устаревшая команда Новая команда
workspace delete workspace delete (то же самое)
workspace export workspace export (то же самое)
workspace export-dir workspace export
workspace import workspace import (то же самое)
workspace import-dir workspace import
workspace list workspace list (то же самое)
workspace ls workspace list
workspace mkdirs workspace mkdirs (то же самое)
workspace rm workspace delete

Аргументы по умолчанию и позиции

Большинство новых команд CLI имеют по крайней мере один аргумент по умолчанию, который не имеет сопровождающего параметра. Некоторые новые команды CLI имеют два или более позиционных аргументов, которые должны быть указаны в определенном порядке и не имеют сопровождающих параметров. Это отличается от устаревшего интерфейса командной строки, где большинство команд требуют указания параметров для всех аргументов. Например, команда нового интерфейса командной строки clusters get принимает идентификатор кластера в качестве аргумента по умолчанию. Однако для устаревшей команды CLI clusters get необходимо указать --cluster-id параметр вместе с идентификатором кластера. Например:

Для устаревшего интерфейса командной строки:

# 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

Для нового интерфейса командной строки:

# 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

В качестве другого примера, команда grants get нового интерфейса командной строки принимает два аргумента по умолчанию: тип защищаемого объекта, за которым следует полное имя этого объекта. Однако команда устаревшего интерфейса командной строки unity-catalog permissions get требует указать вариант --<securable-type> вместе с полным именем объекта безопасности. Например:

Для устаревшего интерфейса командной строки:

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

Для нового интерфейса командной строки:

# 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

Режим отладки

Устаревший интерфейс командной строки предоставляет --debug возможность отображения полной трассировки стека при ошибке. Для нового интерфейса командной строки --debug параметр не распознается. Вместо этого используйте следующие параметры:

  • Используется --log-file <path> для записи сведений журнала в файл, указанный в <path>. Если этот параметр не указан, данные журнала выводится в stderr. Указание --log-file без указания результатов без указания --log-level сведений журнала, записанных в файл.
  • Используется --log-format <type> для указания формата регистрируемой информации. <type> может быть text (значение по умолчанию, если не указано) или json.
  • Используется --log-level <format> для указания уровня зарегистрированной информации. Допустимые значения : disabled (значение по умолчанию, если не указано), trace, debug, info, warnи error.

В устаревшем интерфейсе командной строки в следующем примере показана полная трассировка стека при ошибке:

databricks fs ls / --debug

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

В новом интерфейсе командной строки следующий пример регистрирует полную трассировку стека в файл с именем new-cli-errors.log в текущем рабочем каталоге. Трассировка стека записывается в файл в формате 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.)

Часто задаваемые вопросы

В этом разделе перечислены распространенные вопросы о миграции из прежних версий в новый интерфейс командной строки.

Что происходит с устаревшим интерфейсом командной строки?

Устаревший интерфейс командной строки по-прежнему доступен, но не получает критически важных обновлений. В документации по устаревшей интерфейсу командной строки это отражается. Databricks рекомендует пользователям переходить в новый интерфейс командной строки как можно скорее.

Устаревший интерфейс командной строки всегда находится в экспериментальном состоянии с отказом от ответственности, что Databricks не планирует новую функцию для устаревшего интерфейса командной строки, и устаревший интерфейс командной строки не поддерживается через каналы поддержки Databricks.

Когда устаревший интерфейс командной строки будет устаревшим?

Устаревший интерфейс командной строки всегда находится в экспериментальном состоянии с отказом от ответственности, что Databricks не планирует новую функцию для устаревшего интерфейса командной строки, и устаревший интерфейс командной строки не поддерживается через каналы поддержки Databricks.

Databricks не установил дату или временную шкалу для отмены устаревшей cli. Однако Databricks рекомендует пользователям как можно скорее перейти в новый интерфейс командной строки.

Когда будет выпущен новый ИНТЕРФЕЙС командной строки как общедоступная версия (GA)?

Дата выпуска или временная шкала для выпуска нового интерфейса командной строки, так как общедоступная версия не была установлена. Это будет зависеть от отзывов о том, что Databricks получает от пользователей во время общедоступной предварительной версии.

Каковы основные различия между устаревшими и новыми clis?

  • Устаревший интерфейс командной строки был выпущен в виде пакета Python. Новый интерфейс командной строки выпускается как автономный исполняемый файл и не требует установки зависимостей среды выполнения.
  • Новый интерфейс командной строки полностью охватывает ИНТЕРФЕЙСы REST API Databricks. Устаревший интерфейс командной строки не поддерживается.
  • Новый интерфейс командной строки доступен как общедоступная предварительная версия. Устаревший интерфейс командной строки остается в экспериментальном состоянии.

Имеет ли новый интерфейс командной строки полный паритет функций с устаревшим интерфейсом командной строки?

В новом интерфейсе командной строки почти все команды из устаревшего интерфейса командной строки. Тем не менее, особенно отсутствие в новом интерфейсе командной строки — это stacks группа команд в устаревшем интерфейсе командной строки. Кроме того, несколько устаревших групп команд CLI, таких как unity-catalog и runs были рефакторингованы в новые группы команд в новом интерфейсе командной строки. Инструкции по миграции см. в этой статье.

Разделы справки переходить из устаревшей версии в новый интерфейс командной строки?

Инструкции по миграции см. в этой статье. Обратите внимание, что новый интерфейс командной строки не является раскрывающейся заменой для устаревшего интерфейса командной строки и требует некоторых настроек перейти от устаревшей версии к новому интерфейсу командной строки.

Могут ли установки устаревших и новых clIs существовать на том же компьютере?

Да. Установки устаревших и новых интерфейсов CLIs могут существовать на одном компьютере, но они должны находиться в разных каталогах. Поскольку оба исполняемых файла имеют одинаковое имя databricks, необходимо контролировать, какой исполняемый файл будет выполняться по умолчанию, настроив PATH вашей машины. Если вы хотите запустить новый интерфейс командной строки, но как-то случайно запустить устаревший ИНТЕРФЕЙС командной строки по умолчанию будет запускать новый интерфейс командной строки с теми же аргументами и отобразить следующее предупреждение:

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>

Как показано в предыдущем предупреждении, можно задать DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION переменную среды, чтобы 1 отключить это поведение и запустить устаревший ИНТЕРФЕЙС командной строки.

Получите помощь

Чтобы получить справку по миграции из устаревшего интерфейса командной строки в новый интерфейс командной строки, ознакомьтесь со следующими ресурсами:

  • Last updated on