CLI Databricks (héritée)

Article
09/25/2024

Important

Cette documentation a été mise hors service et peut ne pas être mise à jour.

Databricks vous recommande d’utiliser une version 0.205 ou ultérieure de l’interface CLI Databricks au lieu de la version héritée 0.18 ou antérieure de l’interface CLI Databricks. La version 0.18 ou antérieure de l’interface CLI Databricks n’est pas pris en charge par Databricks. Pour plus d’informations sur les versions Databricks CLI 0,205 et supérieures, consultez Qu’est-ce que la CLI Databricks ?.

Pour migrer de l’interface CLI Databricks version 0.18 ou antérieure vers l’interface CLI Databricks version 0.205 ou ultérieure, consultez Migration de l’interface CLI Databricks.

L’interface CLI Databricks héritée se trouve à l’état expérimental. Databricks ne prévoit actuellement aucune nouvelle fonctionnalité pour l’interface CLI Databricks héritée.

L’interface CLI Databricks n’est pas pris en charge par les canaux de support Databricks. Pour envoyer des commentaires, poser des questions et signaler des problèmes, utilisez l’onglet Problèmes dans le dépôt de l’interface de ligne de commande pour Databricks sur GitHub.

L’interface de ligne de commande Databricks héritée (également appelée interface CLI Databricks héritée) est un utilitaire dont l’interface simple d’utilisation vous permet d’automatiser la plateforme Azure Databricks à partir de votre terminal, de l’invite de commandes ou de scripts d’automatisation.

Spécifications

Python 3 – 3.6 et supérieur
Python 2 – 2.7.9 et supérieur

Important

Sur macOS, l’installation par défaut de Python 2 n’implémente pas le protocole TLSv1_2 et l’exécution de l’interface CLI Databricks héritée avec cette installation de Python entraîne l’erreur : AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'. Utilisez Homebrew pour installer une version de Python qui a ssl.PROTOCOL_TLSv1_2.

Limites

L’utilisation de l’interface CLI Databricks héritée avec des conteneurs de stockage activés pour le pare-feu n’est pas prise en charge. Databricks vous recommande d’utiliser Databricks Connect ou az storage.

Configurer l’interface CLI

Cette section explique comment configurer l’interface CLI Databricks héritée.

Installer ou mettre à jour l’interface CLI

Cette section explique comment installer ou mettre à jour votre machine de développement pour exécuter l’interface CLI Databricks héritée.

Installer l’interface de ligne de commande

Exécutez pip install databricks-cli en utilisant la version appropriée de pip pour votre installation Python :

pip install databricks-cli

Mise à jour de l’interface CLI

Exécutez pip install databricks-cli --upgrade en utilisant la version appropriée de pip pour votre installation Python :

pip install databricks-cli --upgrade

Pour lister la version de l’interface CLI Databricks héritée actuellement installée, exécutez databricks --version :

databricks --version

Configurer l’authentification

Avant de pouvoir exécuter des commandes dans l’interface CLI Databricks héritée, vous devez configurer l’authentification entre l’interface CLI Databricks héritée et Azure Databricks. Cette section explique comment configurer l’authentification pour l’interface CLI Databricks héritée.

Pour vous authentifier auprès de l’interface CLI Databricks héritée, vous pouvez utiliser un jeton d’accès personnel Databricks ou un jeton Microsoft Entra ID (anciennement Azure Active Directory).

Remarque

En guise de bonne pratique de sécurité, quand vous vous authentifiez avec des outils, systèmes, scripts et applications automatisés, Databricks recommande d’utiliser des jetons d’accès personnels appartenant à des principaux de service et non des utilisateurs de l’espace de travail. Pour créer des jetons d’accès pour des principaux de service, consultez la section Gérer les jetons pour un principal de service.

Configurer l’authentification à l’aide d’un jeton Microsoft Entra ID

Pour configurer l’interface CLI Databricks héritée avec un jeton Microsoft Entra ID, générez le jeton Microsoft Entra ID (anciennement Azure Active Directory) et stockez-le dans la variable d’environnement DATABRICKS_AAD_TOKEN.

Exécutez la commande suivante :

databricks configure --aad-token

La commande émet l’invite :

Databricks Host (should begin with https://):

Entrez l’URL de votre espace de travail, au format https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Pour obtenir l’URL de l’espace de travail, consultez URL d’espace de travail.

Après avoir complété l’invite, vos informations d’identification d’accès sont stockées dans le fichier ~/.databrickscfg sur Linux ou macOS, ou dans %USERPROFILE%\.databrickscfg sur Windows. Le fichier contient une entrée de profil par défaut :

[DEFAULT]
host = <workspace-URL>
token = <Azure-AD-token>

Si le fichier .databrickscfg existe déjà, le profil de configuration DEFAULT de ce fichier est remplacé par les nouvelles données. Pour créer un profil de configuration avec un autre nom, consultez Profils de connexion.

Configurer l’authentification avec un jeton d’accès personnel Databricks

Pour configurer l’interface CLI Databricks héritée afin qu’elle utilise un jeton d’accès personnel, exécutez la commande suivante :

databricks configure --token

La commande commence par l’invite :

Databricks Host (should begin with https://):

La commande continue avec l’invite de saisie de votre jeton d’accès personnel :

Token:

Après avoir complété les invites, vos informations d’identification d’accès sont stockées dans le fichier ~/.databrickscfg sur Unix ou macOS, ou dans %USERPROFILE%\.databrickscfg sur Windows. Le fichier contient une entrée de profil par défaut :

[DEFAULT]
host = <workspace-URL>
token = <personal-access-token>

Pour CLI 0.8.1 et les versions ultérieures, vous pouvez changer le chemin de ce fichier en définissant la variable d’environnement DATABRICKS_CONFIG_FILE.

Linux ou macOS

export DATABRICKS_CONFIG_FILE=<path-to-file>

Windows

setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

Important

À compter de CLI 0.17.2, l’interface CLI ne fonctionne pas avec un fichier .netrc. Vous pouvez avoir un fichier .netrc dans votre environnement à d’autres fins, mais l’interface CLI n’utilise pas ce fichier .netrc.

CLI 0.8.0 et ultérieur prend en charge les variables d’environnement Azure Databricks suivantes :

DATABRICKS_HOST
DATABRICKS_TOKEN

La valeur d’une variable d’environnement est prioritaire par rapport à la valeur qui se trouve dans le fichier de configuration.

Tester la configuration de votre authentification

Pour vérifier que vous avez correctement configuré l’authentification, vous pouvez exécuter une commande comme celle qui suit :

databricks fs ls dbfs:/

Si elle aboutit, cette commande liste les fichiers et les répertoires à la racine DBFS de l’espace de travail associé à votre profil DEFAULT.

Profils de connexion

La configuration de l’interface CLI Databricks héritée prend en charge plusieurs profils de connexion. La même installation de l’interface CLI Databricks héritée peut être utilisée pour effectuer des appels d’API sur plusieurs espaces de travail Azure Databricks.

Pour ajouter un profil de connexion, spécifiez un nom unique pour le profil :

databricks configure [--token | --aad-token] --profile <profile-name>

Le fichier .databrickscfg contient une entrée de profil correspondante :

[<profile-name>]
host = <workspace-URL>
token = <token>

Pour utiliser le profil de connexion :

databricks <group> <command> --profile <profile-name>

Si --profile <profile-name> n’est pas spécifié, le profil par défaut est utilisé. Si aucun profil par défaut n’est disponible, vous êtes invité à configurer l’interface CLI avec un profil par défaut.

Tester vos profils de connexion

Pour vérifier que vous avez correctement configuré des profils de connexion, vous pouvez exécuter une commande comme celle qui suit avec l’un de vos noms de profil de connexion :

databricks fs ls dbfs:/ --profile <profile-name>

Si elle aboutit, cette commande liste les fichiers et les répertoires à la racine DBFS de l’espace de travail pour le profil de connexion spécifié. Exécutez cette commande pour chaque profil de connexion que vous souhaitez tester.

Pour examiner vos profils disponibles, consultez votre fichier .databrickscfg.

Utiliser l’interface CLI

Cette section vous montre comment obtenir de l’aide sur l’interface CLI Databricks héritée, analyser la sortie de l’interface CLI Databricks héritée et appeler des commandes dans chaque groupe de commandes.

Afficher l’aide du groupe de commandes CLI

Vous pouvez lister les sous-commandes de n’importe quel groupe de commandes à l’aide de l’option --help ou -h. Par exemple, pour lister les sous-commandes de l’interface CLI DBFS :

databricks fs -h

Afficher l’aide d’une sous-commande d’interface CLI

Vous pouvez lister l’aide d’une sous-commande en utilisant l’option --help ou -h. Par exemple, pour lister l’aide de la sous-commande de copie de fichiers DBFS :

databricks fs cp -h

Attribuer des alias à des groupes de commandes

Il n’est pas toujours pratique de préfixer chaque appel de l’interface CLI Databricks héritée du nom d’un groupe de commandes, par exemple databricks workspace ls dans l’interface CLI Databricks héritée. Pour faciliter l’utilisation de l’interface CLI Databricks héritée, vous pouvez créer un alias des groupes de commandes pour raccourcir les commandes. Par exemple, pour raccourcir databricks workspace ls en dw ls dans le shell Bourne-Again (Bash), vous pouvez ajouter alias dw="databricks workspace" au profil bash approprié. En général, ce fichier se trouve dans ~/.bash_profile.

Conseil

L’interface CLI Databricks héritée a déjà créé un alias de databricks fs pour dbfs. databricks fs ls et dbfs ls sont équivalents.

Utiliser `jq` pour analyser la sortie de l’interface CLI

Certaines commandes de l’interface CLI Databricks héritée génèrent la réponse JSON à partir du point de terminaison de l’API. Parfois, il peut être utile d’analyser des parties du JSON pour les insérer dans d’autres commandes chaînées. Par exemple, pour copier une définition de travail, vous devez prendre le champ settings d’une commande d’obtention de travail et l’utiliser comme argument de la commande de création de travail. Dans ce cas, nous vous recommandons d’utiliser l’utilitaire jq.

Par exemple, la commande suivante imprime les paramètres du travail avec l’ID 233.

databricks jobs list --output JSON | jq '.jobs[] | select(.job_id == 233) | .settings'

Sortie :

{
  "name": "Quickstart",
  "new_cluster": {
    "spark_version": "7.5.x-scala2.12",
    "spark_env_vars": {
      "PYSPARK_PYTHON": "/databricks/python3/bin/python3"
    },
    "num_workers": 8,
    ...
  },
  "email_notifications": {},
  "timeout_seconds": 0,
  "notebook_task": {
    "notebook_path": "/Quickstart"
  },
  "max_concurrent_runs": 1
}

Autre exemple : la commande suivante imprime uniquement les noms et les ID de tous les clusters disponibles dans l’espace de travail :

databricks clusters list --output JSON | jq '[ .clusters[] | { name: .cluster_name, id: .cluster_id } ]'

Sortie :

[
  {
    "name": "My Cluster 1",
    "id": "1234-567890-grip123"
  },
  {
    "name": "My Cluster 2",
    "id": "2345-678901-patch234"
  }
]

Vous pouvez installer jq sur macOS par exemple en utilisant Homebrew avec brew install jq, ou sur Windows en utilisant Chocolatey avec choco install jq. Pour plus d’informations sur jq, consultez le Manuel jq.

Paramètre de chaîne JSON

Les paramètres de chaîne sont gérés différemment en fonction de votre système d’exploitation :

Linux ou macOS

Vous devez mettre les paramètres de chaîne JSON entre guillemets simples. Par exemple :

'["20180505", "alantest"]'

Windows

Vous devez mettre les paramètres de chaîne JSON entre guillemets doubles et les caractères de guillemet dans la chaîne doivent être précédés de \. Par exemple :

"[\"20180505\", \"alantest\"]"

Dépannage

Les sections suivantes fournissent des conseils pour la résolution des problèmes courants liés à l’interface CLI Databricks héritée.

L’utilisation d’EOF avec `databricks configure` ne fonctionne pas

Pour l’interface Databricks CLI 0.12.0 et ultérieur, l’utilisation de la séquence de fin de fichier (EOF) dans un script pour passer des paramètres à la commande databricks configure ne fonctionne pas. Par exemple, le script suivant force l’interface Databricks CLI à ignorer les paramètres et aucun message d’erreur n’est généré :

# Do not do this.
databricksUrl=<per-workspace-url>
databricksToken=<personal-access-token-or-Azure-AD-token>

databricks configure --token << EOF
$databricksUrl
$databricksToken
EOF

Pour résoudre ce problème, effectuez l’une des opérations suivantes :

Utilisez l’une des autres options de configuration programmatique décrites dans Configurer l’authentification.
Ajoutez manuellement les valeurs host et token au fichier .databrickscfg, comme décrit dans Configurer l’authentification.
Rétrogradez votre installation de l’interface Databricks CLI à 0.11.0 ou antérieur, puis réexécutez votre script.

Partager via

CLI Databricks (héritée)

Spécifications

Limites

Configurer l’interface CLI

Installer ou mettre à jour l’interface CLI

Installer l’interface de ligne de commande

Mise à jour de l’interface CLI

Configurer l’authentification

Configurer l’authentification à l’aide d’un jeton Microsoft Entra ID

Configurer l’authentification avec un jeton d’accès personnel Databricks

Linux ou macOS

Windows

Tester la configuration de votre authentification

Profils de connexion

Tester vos profils de connexion

Utiliser l’interface CLI

Afficher l’aide du groupe de commandes CLI

Afficher l’aide d’une sous-commande d’interface CLI

Attribuer des alias à des groupes de commandes

Utiliser `jq` pour analyser la sortie de l’interface CLI

Paramètre de chaîne JSON

Linux ou macOS

Windows

Dépannage

L’utilisation d’EOF avec `databricks configure` ne fonctionne pas

Commandes CLI

Commentaires

Ressources supplémentaires

Partager via

CLI Databricks (héritée)

Spécifications

Limites

Configurer l’interface CLI

Installer ou mettre à jour l’interface CLI

Installer l’interface de ligne de commande

Mise à jour de l’interface CLI

Configurer l’authentification

Configurer l’authentification à l’aide d’un jeton Microsoft Entra ID

Configurer l’authentification avec un jeton d’accès personnel Databricks

Linux ou macOS

Windows

Tester la configuration de votre authentification

Profils de connexion

Tester vos profils de connexion

Utiliser l’interface CLI

Afficher l’aide du groupe de commandes CLI

Afficher l’aide d’une sous-commande d’interface CLI

Attribuer des alias à des groupes de commandes

Utiliser jq pour analyser la sortie de l’interface CLI

Paramètre de chaîne JSON

Linux ou macOS

Windows

Dépannage

L’utilisation d’EOF avec databricks configure ne fonctionne pas

Commandes CLI

Commentaires

Ressources supplémentaires

Utiliser `jq` pour analyser la sortie de l’interface CLI

L’utilisation d’EOF avec `databricks configure` ne fonctionne pas