Migration de l’interface CLI Databricks

Cet article explique comment migrer de Databricks CLI version 0.18 ou antérieure vers Databricks CLI version 0.205 ou ultérieure. Les versions 0.205 et ultérieures de l’interface CLI Databricks sont en préversion publique.

Par souci de concision, cet article fait référence à Databricks CLI versions 0.18 et antérieures en tant qu’interface CLI « héritée », et à Databricks CLI versions 0.205 et ultérieures en tant que « nouvelle » CLI.

Pour plus d'informations sur les CLIs hérités et nouveaux, consultez :

• Databricks CLI (hérité) pour l’interface CLI hérité.
• Présentation de l’interface CLI Databricks pour la nouvelle interface CLI.

Désinstaller l’interface CLI héritée

Si vous avez installé l’interface CLI héritée et que vous souhaitez la désinstaller, utilisez pip (ou pip3, selon votre version de Python) pour exécuter la uninstall commande, comme suit :

pip uninstall databricks-cli

Installer la nouvelle interface CLI

Pour savoir comment installer la nouvelle interface CLI, consultez Installer ou mettre à jour l’interface CLI Databricks.

Vérifier l’installation de l’interface CLI

Si vous n’êtes pas sûr d’utiliser la nouvelle interface CLI, suivez les instructions de cette section pour vérifier et ajuster si nécessaire. Avant de suivre ces instructions, veillez à quitter les environnements virtuels Python, conda les environnements ou les environnements similaires.

Pour case activée la version de votre installation par défaut de l’interface CLI, exécutez la commande suivante :

databricks -v

Si le numéro de version ne correspond pas à ce que vous attendez, effectuez l’une des opérations suivantes :

• Si vous souhaitez utiliser une seule version de l’interface CLI : désinstallez toutes les versions précédentes de l’interface CLI que vous ne souhaitez plus utiliser. Vous devrez peut-être mettre à jour votre système d’exploitation PATH afin que le chemin d’accès à la version restante de l’interface CLI que vous souhaitez utiliser soit répertorié.
• Si vous souhaitez continuer à utiliser plusieurs versions de l’interface CLI : ajoutez le chemin d’accès complet à la version de l’interface CLI que vous souhaitez utiliser pour chaque appel à l’interface CLI.
• Si vous souhaitez continuer à utiliser plusieurs versions de l’interface CLI, mais que vous ne souhaitez pas continuer à précéder le chemin d’accès complet à la version de l’interface CLI que vous utilisez le plus souvent : assurez-vous que le chemin d’accès complet à cette version est répertorié en premier dans le système d’exploitation de votre système d’exploitation PATH. Notez que vous devez toujours ajouter le chemin d’accès complet aux versions de l’interface CLI qui ne sont pas répertoriées en premier dans le système d’exploitation de votre système d’exploitation PATH.

Pour mettre à jour le système d’exploitation PATH, procédez comme suit :

MacOS ou Linux

1. Répertoriez les chemins d’accès où databricks est installé en exécutant l’une des commandes suivantes :

   which -a databricks
   
   # Or:
   where databricks
   

2. Obtenez le chemin d’accès à l’installation que vous souhaitez utiliser sans reporter le chemin d’accès complet à chaque appel à l’interface CLI. Si vous ne savez pas de quel chemin il s’agit, exécutez le chemin d’accès complet à chaque emplacement, suivi de -v, par exemple :

   /usr/local/bin/databricks -v
   

3. Pour placer le chemin d’accès à l’installation que vous souhaitez utiliser en premier dans votre PATH, exécutez la commande suivante, en remplaçant par /usr/local/bin le chemin que vous souhaitez utiliser. N’ajoutez pas databricks à la fin de ce chemin d’accès. Par exemple :

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

4. Pour vérifier que le PATH a été correctement défini pour la session de terminal actuelle, exécutez databricks suivi de -v et examiner le numéro de version :

   databricks -v
   

5. Pour que le PATH paramètre soit défini de cette façon chaque fois que vous redémarrez votre terminal, ajoutez la commande de l’étape 3 à votre fichier d’initialisation de l’interpréteur de commandes. Par exemple, pour Zshell, ce fichier se trouve généralement dans ~/.zshrc. Pour Bash, ce fichier se trouve généralement dans ~/.bashrc. Pour les autres interpréteurs de commandes, consultez la documentation de votre fournisseur d’interpréteur de commandes.

6. Après avoir mis à jour votre fichier d’initialisation de l’interpréteur de commandes, vous devez redémarrer votre terminal pour appliquer la valeur mise à jour PATH.

Windows

1. Obtenez le chemin d’accès à l’installation databricks que vous souhaitez utiliser sans reporter le chemin d’accès complet à chaque appel à l’interface CLI.

2. Cliquez sur Ouvrir l'emplacement du fichier.

3. Notez le chemin d'accès à databricks , par exemple C:\Windows.

4. Dans le menu Démarrer, recherchez Variables d’environnement.

5. Cliquez sur Modifier les variables d’environnement pour votre compte.

6. Sélectionnez la variable Chemin d’accès dans la section Variables utilisateur pour <username>.

7. Cliquez sur Modifier.

8. Cliquez sur Nouveau.

9. Entrez le chemin que vous souhaitez ajouter, sans databricks.exe (par exemple C:\Windows).

10. Utilisez le bouton Monter pour déplacer le chemin que vous venez d’ajouter au début de la liste.

11. Cliquez sur OK.

12. Pour vérifier que le PATH a été correctement défini, ouvrez une nouvelle invite de commandes, exécutez databricks suivi de -vet examinez le numéro de version :

    databricks -v
    

Utiliser des types d’authentification supplémentaires

L’interface CLI héritée et la nouvelle interface CLI prennent en charge l’authentification par jeton d’accès personnel Azure Databricks. Toutefois, Databricks vous recommande d’utiliser d’autres types d’authentification Azure Databricks si possible, que seule la nouvelle interface CLI prend en charge.

Si vous devez utiliser l’authentification par jeton d’accès personnel Azure Databricks, Databricks vous recommande d’en utiliser un associé à un principal de service au lieu d’un compte Azure Databricks ou d’un utilisateur d’espace de travail. Si vous souhaitez en savoir plus, veuillez consulter la rubrique Gérer les principaux de service.

La nouvelle interface CLI prend en charge les jetons Microsoft Entra ID en plus des jetons d’accès personnels Azure Databricks. Ces jetons supplémentaires sont plus sécurisés, car ils expirent généralement dans une heure, tandis que les jetons d’accès personnels Azure Databricks peuvent être valides d’un jour à indéfiniment. Cela est particulièrement important si un jeton est accidentellement archivé dans des systèmes de contrôle de version accessibles par d’autres utilisateurs. En outre, la nouvelle interface CLI peut actualiser automatiquement ces jetons supplémentaires lorsqu’ils expirent, tandis que l’actualisation des jetons d’accès personnel Azure Databricks est un processus manuel ou peut être difficile à automatiser.

Pour plus d’informations, consultez Authentification pour l’interface CLI Databricks.

Comparaisons de groupes de commandes et de commandes

Le tableau suivant répertorie les groupes de commandes CLI hérités et leurs nouveaux équivalents de groupe de commandes CLI. Lorsqu’il existe des différences significatives entre les CLIs, des tables supplémentaires répertorient les commandes ou options CLI héritées et leurs nouvelles commandes CLI ou leurs équivalents d’option.

Groupes de commandes

configure options

Commandes fs

Toutes les commandes fs de l’interface CLI héritée sont les mêmes dans la nouvelle interface CLI, à l’exception de fs mv laquelle n’est pas disponible dans la nouvelle interface CLI.

Commandes groups

Commandes pipelines

Commandes runs

Commandes secrets

Commandes tokens

Groupes de commandes unity-catalog

unity-catalog <command> dans l’interface CLI héritée devient juste <command> dans la nouvelle interface CLI.

Commandes workspace

Arguments par défaut et positionnels

La plupart des nouvelles commandes CLI ont au moins un argument par défaut qui n’a pas d’option d’accompagnement. Certaines nouvelles commandes CLI ont au moins deux arguments positionnels qui doivent être spécifiés dans un ordre particulier et qui n’ont pas d’options d’accompagnement. Cela diffère de l’interface CLI héritée, où la plupart des commandes nécessitent que des options soient spécifiées pour tous les arguments. Par exemple, la nouvelle commande CLI clusters get prend un ID de cluster comme argument par défaut. Toutefois, la commande de clusers get l’interface CLI héritée vous oblige à spécifier une --cluster-id option avec l’ID de cluster. Par exemple :

Pour l’interface CLI héritée :

# 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 interface 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

Autre exemple, la nouvelle commande CLIgrants get prend deux arguments par défaut : le type sécurisable suivi du nom complet de la sécurisable. Toutefois, la commande de l’interface CLI héritée unity-catalog permissions get vous oblige à spécifier une --<securable-type> option avec l’ID de cluster. Par exemple :

Pour l’interface CLI héritée :

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

Pour la nouvelle interface 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

L’interface CLI héritée fournit une option permettant d’afficher --debug la trace complète de la pile en cas d’erreur. Pour la nouvelle interface CLI, l’option --debug n’est pas reconnue. Utilisez plutôt les options suivantes :

• Utilisez --log-file <path> pour écrire des informations de journal dans le fichier spécifié dans <path>. Si cette option n’est pas fournie, les informations de journal sont transmises à stderr. La spécification --log-filesans spécifier également --log-level les résultats dans aucune information de journal n’est écrite dans le fichier.
• Utilisez --log-format <type> pour spécifier le format des informations journalisées. <type> peut être text (la valeur par défaut, si elle n’est pas spécifiée) ou json.
• Utilisez --log-level <format> pour spécifier le niveau d’informations journalisées. Les valeurs autorisées sont disabled (la valeur par défaut, si elle n’est pas spécifiée), trace, debug, info, warnet error.

Pour l’interface CLI héritée, l’exemple suivant montre la trace complète de la pile en cas d’erreur :

databricks fs ls / --debug

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

Pour la nouvelle interface CLI, l’exemple suivant consigne la trace complète de la pile 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 répertorie les questions courantes sur la migration de l’ancien vers la nouvelle interface CLI.

Qu’arrive-t-il à l’interface CLI héritée ?

L’interface CLI héritée est toujours disponible, mais ne reçoit aucune mise à jour non critique. La documentation de l’interface CLI héritée reflète cela. Databricks recommande aux utilisateurs de migrer vers la nouvelle interface CLI dès que possible.

L’interface CLI héritée a toujours été dans un état expérimental avec une clause de non-responsabilité indiquant que Databricks ne prévoit aucune nouvelle fonctionnalité pour l’interface CLI héritée, et que l’interface CLI héritée n’est pas prise en charge via les canaux de support Databricks.

Quand l’interface CLI héritée sera-t-elle dépréciée ?

L’interface CLI héritée a toujours été dans un état expérimental avec une clause de non-responsabilité indiquant que Databricks ne prévoit aucune nouvelle fonctionnalité pour l’interface CLI héritée, et que l’interface CLI héritée n’est pas prise en charge via les canaux de support Databricks.

Databricks n’a pas établi de date ou de chronologie pour la dépréciation de l’interface CLI héritée. Toutefois, Databricks recommande aux utilisateurs de migrer vers la nouvelle interface CLI dès que possible.

Quand la nouvelle interface CLI sera-t-elle publiée en disponibilité générale (GA) ?

Aucune date de publication ou chronologie de publication de la nouvelle interface CLI en disponibilité générale n’a été établie. Cela dépend des commentaires que Databricks reçoit des utilisateurs pendant la préversion publique.

Quelles sont les principales différences entre les CLI hérités et les nouveaux CLIs ?

• L’interface CLI héritée a été publiée en tant que package Python. La nouvelle interface CLI est publiée en tant qu’exécutable autonome et n’a pas besoin d’installer de dépendances au runtime.
• La nouvelle interface CLI a une couverture complète des API REST Databricks. Ce n’est pas le cas de l’interface CLI héritée.
• La nouvelle interface CLI est disponible en préversion publique. L’interface CLI héritée se trouve à l’état expérimental.

La nouvelle interface CLI a-t-elle une parité de fonctionnalités complète avec l’interface CLI héritée ?

La nouvelle interface CLI couvre presque toutes les commandes de l’interface CLI héritée. Toutefois, le groupe de commandes de l’interface CLI héritée est stacks particulièrement absent de la nouvelle interface CLI. En outre, quelques groupes de commandes CLI hérités tels que unity-catalog et runs ont été refactorisé en nouveaux groupes de commandes dans la nouvelle interface CLI. Pour obtenir des conseils sur la migration, consultez les informations fournies plus haut dans cet article.

Comment faire migrer de l’hérité vers la nouvelle interface CLI ?

Pour obtenir des conseils sur la migration, consultez les informations fournies plus haut dans cet article. Notez que la nouvelle interface CLI n’est pas un remplacement de l’interface CLI héritée et nécessite une configuration pour passer de l’interface héritée à la nouvelle interface CLI.

Les installations des CLI hérités et nouvelles peuvent-elles exister sur la même machine ?

Oui. Les installations des CLI hérités et nouvelles peuvent exister sur la même machine, mais elles doivent se trouver dans des répertoires différents. Étant donné que les exécutables sont tous deux nommés databricks, vous devez contrôler l’exécutable qui est exécuté par défaut en configurant le fichier de votre ordinateur PATH. Si vous souhaitez exécuter la nouvelle interface CLI, mais que vous exécutez accidentellement l’interface CLI héritée à la place, par défaut, l’interface CLI héritée exécute la nouvelle interface CLI avec les mêmes arguments et affiche 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 DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION variable d’environnement1 sur pour désactiver ce comportement et exécuter l’interface CLI héritée à la place.

Obtenir de l’aide

Pour obtenir de l’aide sur la migration de l’interface CLI héritée vers la nouvelle interface CLI, consultez les ressources suivantes :

• Centre d’aide Databricks
• Databricks Office Hours