Migration de Databricks CLI
Cet article décrit comment migrer de la CLI Databricks version 0.18 ou inférieure vers la CLI Databricks version 0.205 ou supérieure. Les versions 0.205 et supérieures du CLI Databricks sont en aperçu public.
Par souci de concision, cet article fait référence aux versions 0.18 et inférieures de la CLI Databricks en tant que CLI « héritée », et aux versions 0.205 et supérieures de la CLI Databricks en tant que « nouvelle » CLI.
Pour plus d’information sur les anciennes et les nouvelles CLI, voir :
- CLI Databricks héritée pour la CLI héritée.
- CLI Databricks pour la nouvelle CLI.
Désinstaller l'ancienne CLI
Si la CLI héritée est installée et que vous souhaitez la désinstaller, utilisez pip (ou pip3, selon votre version de Python) pour exécuter la commande uninstall, comme suit :
pip uninstall databricks-cli
Installez la nouvelle CLI
Pour découvrir comment installer la nouvelle CLI, consultez Installer ou mettre à jour la CLI Databricks.
Vérifier votre installation de CLI
Si vous n'êtes pas sûr d'utiliser le nouveau CLI, suivez les instructions de cette section pour vérifier et ajuster si nécessaire. Avant de suivre ces instructions, assurez-vous de quitter tout environnement virtuel Python, environnement conda ou tout environnement similaire.
Pour vérifier la version de votre installation default du CLI, exécutez la commande suivante :
databricks -v
Si le numéro de version n'est pas celui que vous attendez, effectuez l'une des opérations suivantes :
- Si vous voulez utiliser une seule version du CLI : désinstallez toutes les versions précédentes du CLI que vous ne souhaitez plus utiliser. Vous devrez peut-être mettre à jour le
PATHde votre système d'exploitation afin que le chemin d'accès à la version restante de la CLI que vous souhaitez utiliser soit répertorié. - Si vous voulez continuer à utiliser plusieurs versions de la CLI : ajoutez le chemin d’accès complet à la version de la CLI que vous souhaitez utiliser à chaque appel de la CLI.
- Si vous souhaitez continuer à utiliser plusieurs versions de la CLI, mais que vous ne voulez pas continuer à préfixer le chemin complet à la version de la CLI que vous utilisez le plus souvent : assurez-vous que le chemin complet vers cette version est répertorié en premier dans le
PATHde votre système d'exploitation. Notez que vous devez toujours ajouter le chemin complet aux versions de la CLI qui ne sont pas répertoriées en premier dans lePATHde votre système d'exploitation.
Pour mettre à jour le PATH de votre système d'exploitation, procédez comme suit :
- MacOS or Linux
- Windows
-
Listez les chemins d'accès où
databricksest installé en exécutant l'une des commandes suivantes :Bashwhich -a databricks
# Or:
where databricks -
Obtenez le chemin d'accès à l'installation que vous souhaitez utiliser sans préfixer le chemin complet à chaque appel à la CLI. Si vous ne savez pas de quel chemin il s'agit, exécutez le chemin complet vers chaque emplacement, suivi de
-v, par exemple :Bash/usr/local/bin/databricks -v -
Pour placer le chemin de l'installation que vous souhaitez utiliser en premier dans votre
PATH, exécutez la commande suivante, en remplaçant/usr/local/binpar le chemin que vous souhaitez utiliser. N'ajoutez pasdatabricksà la fin de ce chemin. Par exemple :Bashexport PATH="/usr/local/bin:$PATH" -
Pour vérifier que le
PATHa été correctement défini pour la session de terminal actuelle, exécutezdatabrickssuivi de-vet vérifiez le numéro de version :Bashdatabricks -v -
Pour que le
PATHsoit configuré de cette manière chaque fois que vous redémarrez votre terminal, ajoutez la commande de l'étape 3 à votre fichier d'initialisation Shell. Par exemple, pour Zshell, ce fichier se trouve généralement à l'emplacement~/.zshrc. Pour Bash, ce fichier se trouve généralement à l’emplacement~/.bashrc. Pour les autres Shells, consultez la documentation de votre fournisseur de Shell. -
Après avoir mis à jour votre fichier d'initialisation Shell, vous devez redémarrer votre terminal pour appliquer la valeur
PATHmise à jour.
-
Cliquez avec le bouton droit sur l'installation de
databricksque vous souhaitez utiliser sans ajouter le chemin d'accès complet à chaque appel à l'interface CLI. -
Cliquez sur Ouvrir l'emplacement du fichier .
-
Notez le chemin vers
databricks, par exempleC:\Windows. -
Dans le menu Start , recherchez Variables d'environnement .
-
Cliquez sur Modifier les variables d'environnement de votre compte .
-
Sélectionnez la variable **Chemin** dans la section **Variables utilisateur pour **.
<username> -
Cliquez sur Modifier .
-
Cliquez sur Nouveau .
-
Saisissez le chemin que vous souhaitez ajouter, sans
databricks.exe(tel queC:\Windows). -
Utilisez le bouton **Déplacer vers le haut** pour déplacer le chemin que vous venez d'ajouter au début de la liste.
-
Cliquez sur **OK**.
-
Pour vérifier que le
PATHa été défini correctement, ouvrez une nouvelle invite de commande, exécutezdatabrickssuivi de-v, et vérifiez le numéro de version.Bashdatabricks -v
Utiliser des types d'authentification supplémentaires
L'ancienne CLI et la nouvelle CLI prennent toutes deux en charge l'authentification par jeton d'accès personnel Databricks. Cependant, Databricks recommande d'utiliser d'autres types d'authentification Databricks si possible, que seule la nouvelle CLI prend en charge.
Si vous devez utiliser l'authentification par jeton d'accès personnel Databricks, Databricks vous recommande d'en utiliser un qui est associé à un Service Principal plutôt qu'à un compte Databricks ou à un utilisateur de Workspace. See Service Principal.
La nouvelle CLI prend en charge les jetons OAuth en plus des jetons d'accès personnels Databricks. Ces jetons supplémentaires sont plus sécurisés car ils expirent généralement en une heure, tandis que les jetons d'accès personnels Databricks peuvent être valides d'un jour à indéfiniment. Ceci est particulièrement important si un jeton est accidentellement enregistré dans des systèmes de contrôle de version accessibles à d'autres. De plus, le nouveau CLI peut automatiquement refresh ces jetons supplémentaires lorsqu'ils expirent, tandis que le refresh des jetons d'accès personnels Databricks est un processus manuel ou peut être difficile à automatiser.
Pour plus d'information, consultez Authentification pour la CLI Databricks.
Comparaisons des groupes de commandes et des commandes
Le tableau suivant répertorie les groupes de commandes CLI hérités et leurs nouveaux équivalents de groupes de commandes CLI. Lorsque des différences significatives existent entre les CLI, des tables supplémentaires listent les commandes ou options CLI héritées et leurs équivalents en nouvelles commandes ou options CLI.
Groupes de commandes
Groupe de commandes hérité | Nouveau groupe de commandes |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Non disponible dans la nouvelle CLI. Databricks vous recommande d'utiliser plutôt le fournisseur Databricks Terraform. |
|
|
| Différents. Voir les |
|
|
configure options
Option existante | Nouvelle option |
|---|---|
| La CLI héritée utilise |
| Pour OAuth dans la nouvelle CLI, consultez l’authentification OAuth machine-à-machine (M2M) ou l’authentification OAuth utilisateur-à-machine (U2M). |
| Pour OAuth dans la nouvelle CLI, consultez l’authentification OAuth machine-à-machine (M2M) ou l’authentification OAuth utilisateur-à-machine (U2M). |
|
|
| Non disponible dans la nouvelle CLI. |
|
|
| Utilisez |
| Non disponible dans la nouvelle CLI. |
| Non disponible dans la nouvelle CLI. La nouvelle CLI utilise uniquement l'API Jobs 2.1. Pour appeler l'API Jobs 2.0 héritée, utilisez l'interface de ligne de commande héritée et consultez la page CLI Databricks héritée. |
| Pour le debugging et la journalisation dans la nouvelle CLI, voir Mode débogage. |
|
|
|
|
Commandesfs
Toutes les commandes fs de l'ancienne CLI sont les mêmes dans la nouvelle CLI, à l'exception de fs mv qui n'est pas disponible dans la nouvelle CLI.
Commande héritée | Nouvelle commande |
|---|---|
|
|
|
|
|
|
|
|
| Non disponible dans la nouvelle CLI. |
|
|
Commandesgroups
Commande héritée | Nouvelle commande |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Commandespipelines
Commande héritée | Nouvelle commande |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Commandesruns
Commande héritée | Nouvelle commande |
|---|---|
|
|
|
|
|
|
|
|
|
|
Commandessecrets
Commande héritée | Nouvelle commande |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Commandestokens
Commande héritée | Nouvelle commande |
|---|---|
|
|
|
|
|
|
unity-catalog groupes de commandes
unity-catalog <command> dans l'ancienne CLI devient juste <command> dans la nouvelle CLI.
Groupe de commandes hérité | Nouveau groupe de commandes |
|---|---|
|
|
|
|
| Non disponible dans la nouvelle CLI. Consultez la traçabilité dans Unity Catalog. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Commandesworkspace
Commande héritée | Nouvelle commande |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Arguments default et positionnels
La plupart des nouvelles commandes CLI ont au moins un argument default qui n'a pas d'option associée. Certaines nouvelles commandes CLI ont deux arguments positionnels ou plus qui doivent être spécifiés dans un ordre particulier et qui n'ont pas d'options d'accompagnement. Ceci est différent du CLI hérité, où la plupart des commandes vous obligent à spécifier des options pour tous les arguments. Par exemple, la commande clusters get du nouveau CLI prend un ID de cluster comme argument par default. Cependant, la commande clusters get du CLI hérité vous oblige à spécifier une option --cluster-id avec l'ID du cluster. Par exemple :
Pour l'ancienne CLI :
# 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
Pour la nouvelle 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
À titre d'autre exemple, la commande grants get de la nouvelle CLI prend deux arguments par default : le type d'élément sécurisable suivi du nom complet de l'élément sécurisable. Cependant, la commande unity-catalog permissions get de la CLI héritée vous demande de spécifier une option --<securable-type> ainsi que le nom complet du sécurisable. Par exemple :
Pour l'ancienne CLI :
databricks unity-catalog permissions get --schema main.default
Pour la nouvelle 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
Mode débogage
La CLI héritée fournit une option --debug pour afficher la trace complète de la pile en cas d'erreur. Pour la nouvelle CLI, l'option --debug n'est pas reconnue. Plutôt, utilisez les options suivantes :
- Utilisez
--log-file <path>pour écrire les informations de log dans le fichier spécifié dans<path>. Si cette option n'est pas fournie, les informations de log sont sorties vers stderr. Spécifier--log-filesans également spécifier--log-leveln'entraîne l'écriture d'aucune information de log dans le fichier. - Utilisez
--log-format <type>pour spécifier le format des informations Logs.<type>peut êtretext(le default, si non spécifié) oujson. - Utilisez
--log-level <format>pour spécifier le niveau d'information consigné. Les valeurs autorisées sontdisabled(le default, si non spécifié),trace,debug,info,warneterror.
Pour l’ancienne CLI, l’exemple suivant affiche la trace de la pile complète en cas d’erreur :
databricks fs ls / --debug
# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"
Pour le nouveau CLI, l'exemple suivant enregistre la trace de pile complète dans un fichier nommé new-cli-errors.log dans le répertoire de travail actuel. La trace de pile est écrite dans le fichier au format 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.)
Questions courantes
Cette section liste les questions courantes sur la migration de l'ancien vers le nouveau CLI.
Qu'arrive-t-il à la CLI héritée ?
L'ancienne CLI est toujours disponible, mais ne reçoit aucune mise à jour non essentielle. La documentation de l'ancienne CLI en témoigne. Databricks recommande aux utilisateurs de migrer vers la nouvelle CLI dès que possible.
L'ancienne CLI a toujours été dans un état expérimental avec une clause de non-responsabilité indiquant que Databricks n'a pas prévu de nouveaux travaux sur les fonctionnalités pour l'ancienne CLI, et que l'ancienne CLI n'est pas prise en charge par les canaux de support Databricks.
Quand la CLI héritée sera-t-elle obsolète ?
L'ancienne CLI a toujours été dans un état expérimental avec une clause de non-responsabilité indiquant que Databricks n'a pas prévu de nouveaux travaux sur les fonctionnalités pour l'ancienne CLI, et que l'ancienne CLI n'est pas prise en charge par les canaux de support Databricks.
Databricks n'a pas établi de date ou d'échéancier pour la dépréciation de l'ancienne CLI. Cependant, Databricks recommande aux utilisateurs de migrer vers la nouvelle CLI dès que possible.
Quand la nouvelle CLI sera-t-elle généralement disponible (GA) ?
Une date de lancement ou un calendrier pour la publication de la nouvelle CLI en tant que version de disponibilité générale n'a pas été établi. Cela dépendra des retours que Databricks recevra des utilisateurs pendant l'aperçu public.
Quelles sont les principales différences entre les anciennes et les nouvelles CLI ?
- La CLI héritée a été distribuée en tant que package Python. La nouvelle CLI est distribuée en tant qu’exécutable autonome et n’a pas besoin de dépendances d’exécution installées.
- La nouvelle CLI couvre entièrement les APIs REST de Databricks. L'ancienne CLI ne le fait pas.
- La nouvelle CLI est disponible en préversion publique. La CLI héritée demeure à l'état expérimental.
La nouvelle CLI dispose-t-elle d'une parité fonctionnelle complète avec l'ancienne CLI ?
La nouvelle CLI couvre presque toutes les commandes de l'ancienne CLI. Cependant, le groupe de commandes stacks de l'ancienne CLI est notamment absent de la nouvelle CLI. De plus, quelques anciens groupes de commandes CLI tels que unity-catalog et runs ont été refactorisés en de nouveaux groupes de commandes dans la nouvelle CLI. Pour obtenir des conseils sur la migration, consultez les informations fournies précédemment dans cet article.
Comment migrer de l'ancienne vers la nouvelle CLI ?
Pour obtenir des conseils en matière de migration, reportez-vous aux informations fournies précédemment dans cet article. Notez que la nouvelle CLI ne remplace pas directement l'ancienne CLI et nécessite une certaine configuration pour passer de l'ancienne à la nouvelle CLI.
Les installations des CLI existantes et nouvelles peuvent-elles coexister sur la même machine ?
Oui. Les installations des anciens et nouveaux CLIs peuvent exister sur la même machine, mais elles doivent être situées dans des répertoires différents. Puisque les exécutables sont tous deux nommés databricks, vous devez contrôler quel exécutable est exécuté par default en configurant le PATH de votre machine. Si vous souhaitez exécuter le nouveau CLI mais qu’il arrive que vous exécutiez accidentellement l’ancien CLI à la place, par default, l’ancien CLI exécutera le nouveau CLI avec les mêmes arguments et affichera le message d'avertissement suivant :
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>
Comme indiqué dans le message d'avertissement précédent, vous pouvez définir la variable d'environnement DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION à 1 pour désactiver ce comportement et exécuter le CLI hérité à la place.
Obtenir de l'aide
Pour obtenir de l'aide concernant la migration de l'ancien CLI vers le nouveau CLI, consultez les ressources suivantes :