Миграция интерфейса командной строки Databricks
В этой статье описывается, как выполнить миграцию из Databricks CLI версии 0.18 или ниже в Databricks CLI версии 0.205 или более поздней. Интерфейс командной строки Databricks версии 0.205 и выше находятся в общедоступной предварительной версии.
Для краткости эта статья относится к Databricks CLI версии 0.18 и ниже, как к интерфейсу командной строки прежних версий и Databricks CLI версии 0.205 и выше, как к новому интерфейсу командной строки.
Дополнительные сведения о устаревших и новых clis см. в следующих статье:
- Интерфейс командной строки Databricks (устаревшая версия) для устаревшего интерфейса командной строки.
- Что такое Интерфейс командной строки Databricks? для нового интерфейса командной строки.
Удаление устаревшего интерфейса командной строки
Если у вас установлен устаревший интерфейс командной строки и вы хотите удалить ее, используйте pip (или pip3, в зависимости от версии Python), чтобы выполнить uninstall команду, как показано ниже.
pip uninstall databricks-cli
Установка нового интерфейса командной строки
Сведения об установке нового интерфейса командной строки см. в статье "Установка или обновление интерфейса командной строки Databricks".
Проверка установки CLI
Если вы не уверены, используете ли вы новый интерфейс командной строки, следуйте инструкциям в этом разделе, чтобы проверить и настроить их по мере необходимости. Прежде чем следовать этим инструкциям, обязательно закройте все виртуальные среды Python, conda среды или аналогичные среды.
Чтобы проверить версию установки по умолчанию интерфейса командной строки, выполните следующую команду:
databricks -v
Если номер версии не является ожидаемым, выполните одно из следующих действий:
- Если вы хотите использовать только одну версию интерфейса командной строки: удалите все предыдущие версии интерфейса командной строки, которую вы больше не хотите использовать. Возможно, потребуется обновить путь
PATHк оставшейся версии интерфейса командной строки, которую вы хотите использовать. - Если вы хотите продолжать использовать несколько версий интерфейса командной строки: предопределите полный путь к версии интерфейса командной строки, которую вы хотите использовать для каждого и каждого вызова интерфейса командной строки.
- Если вы хотите использовать несколько версий интерфейса командной строки, но вы не хотите приступить к полной версии интерфейса командной строки, которую вы используете чаще всего: убедитесь, что полный путь к этой версии указан в вашей операционной системе
PATH. Обратите внимание, что вы по-прежнему должны приставить полный путь к версиям интерфейса командной строки, которые не перечислены в вашей операционной системеPATH.
Чтобы обновить операционную систему PATH, сделайте следующее:
MacOS или Linux
Выведите список путей, в которых
databricksустановлено, выполнив одну из следующих команд:which -a databricks # Or: where databricksПуть к установке, которую вы хотите использовать, не добавляя полный путь к каждому и каждому вызову интерфейса командной строки. Если вы не уверены, какой путь это, выполните полный путь к каждому расположению, а затем
-v, например:/usr/local/bin/databricks -vЧтобы поместить путь к установке, которую вы хотите использовать сначала в вашей
PATH, выполните следующую команду, заменив/usr/local/binпуть, который вы хотите использовать. Не добавляйтеdatabricksв конец этого пути. Например:export PATH="/usr/local/bin:$PATH"Чтобы проверить правильность
PATHустановки текущего сеанса терминала, выполнитеdatabricksи-vпроверьте номер версии:databricks -vPATHЧтобы задать этот способ при каждом перезапуске терминала, добавьте команду из шага 3 в файл инициализации оболочки. Например, для Zshell этот файл обычно находится в~/.zshrcпапке . Для Bash этот файл обычно находится по~/.bashrcадресу. Сведения о других оболочках см. в документации поставщика оболочки.После обновления файла инициализации оболочки необходимо перезапустить терминал, чтобы применить обновленное
PATHзначение.
Windows
Щелкните правой кнопкой мыши установку
databricks, которую вы хотите использовать, не добавляя полный путь к каждому и каждому вызову интерфейса командной строки.Щелкните "Открыть расположение файла".
Обратите внимание на путь,
databricksнапримерC:\Windows.В меню "Пуск" найдите переменные среды.
Щелкните "Изменить переменные среды" для учетной записи.
Выберите переменную Path в переменных пользователя для
<username>раздела.Выберите Изменить.
Нажмите кнопку Создать.
Введите путь, который вы хотите добавить, без
databricks.exe(напримерC:\Windows, ).Нажмите кнопку "Переместить вверх ", чтобы переместить путь, который вы только что добавили в начало списка.
Щелкните OK.
Чтобы проверить
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. См . параметры настройки. |
fs |
fs. См . команды fs. |
groups |
groups. См . команды групп. |
instance-pools |
instance-pools. Все имена команд одинаковы. |
jobs |
jobs. Все имена команд одинаковы. |
libraries |
libraries. Все имена команд одинаковы, кроме list. Команда list больше не доступна; используйте all-cluster-statuses вместо этого команды или cluster-status команды. |
pipelines |
pipelines. См . команды конвейеров. |
repos |
repos. Все имена команд одинаковы. |
runs |
jobs. См . команды выполнения. |
secrets |
secrets. См . команды секретов. |
stack |
Недоступно в новом интерфейсе командной строки. Databricks рекомендует вместо этого использовать поставщик Databricks Terraform. |
tokens |
tokens. См . команды токенов. |
unity-catalog |
Различный. См . группы команд unity-catalog. |
workspace |
workspace. См . команды рабочей области. |
configure options
| Вариант прежних версий | Новый параметр |
|---|---|
-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 clusers 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 отключить это поведение и запустить устаревший ИНТЕРФЕЙС командной строки.
Получить помощь
Чтобы получить справку по миграции из устаревшего интерфейса командной строки в новый интерфейс командной строки, ознакомьтесь со следующими ресурсами: