Interface CLI Databricks héritée

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

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 ordinateur 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

Mettre à jour 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 répertorier 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 Databricks CLI héritées, 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).

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

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

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 par espace de travail, consultez l’URL par espace de travail.

Une fois l’invite terminée, vos informations d’identification d’accès sont stockées dans le fichier ~/.databrickscfg sur Linux ou macOS ou %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 de ce fichier DEFAULT sera remplacé par les nouvelles données. Pour créer un profil de configuration avec un autre nom à la place, consultez Profils de connexion.

Configurer l’authentification à l’aide d’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://):

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

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

Token:

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

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

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

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>

Fenêtres

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

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 si vous configurez l’authentification correctement, vous pouvez exécuter une commande telle que la suivante :

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 si vous configurez correctement des profils de connexion, vous pouvez exécuter une commande telle que la suivante 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 de 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 répertorier les sous-commandes pour n'importe quel groupe de commandes en utilisant l'option --help ou -h. Par exemple, pour répertorier les sous-commandes CLI DBFS :

databricks fs -h

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

Vous pouvez répertorier l’aide d’une sous-commande en utilisant l’option --help ou -h. Par exemple, pour répertorier l’aide pour 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.

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 settings champ d’une commande get job et l’utiliser comme argument de la commande create job. 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ètres 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 placer les paramètres de chaîne JSON entre guillemets simples. Par exemple :

'["20180505", "alantest"]'

Fenêtres

Vous devez placer les paramètres de chaîne JSON entre guillemets doubles, et les guillemets à l’intérieur de la chaîne doivent être précédés par \. 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 Databricks CLI 0.12.0 et versions ultérieures, l’utilisation de la séquence de fin de fichier (EOF) dans un script pour passer des paramètres à la databricks configure commande 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 par programmation, comme décrit dans Configurer l’authentification.
• Ajoutez manuellement les valeurs host et token dans le 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.

Commandes CLI

• Interface CLI (héritée) Stratégies de cluster
• Interface CLI (héritée) Clusters
• CLI DBFS (héritée)
• CLI des pipelines déclaratifs Spark Lakeflow (ancien)
• Interface CLI de groupes (héritée)
• Interface CLI des pools d’instances (hérité)
• Interface CLI (héritée) Travaux
• Interface CLI (héritée) Bibliothèques
• Interface CLI (héritée) Référentiels
• Exécute l’interface en ligne de commande (ancienne version)
• Secrets CLI (ancien)
• Interface CLI (héritée) Piles
• Interface CLI (héritée) Jetons
• Interface CLI (héritée) Unity Catalog
• Interface CLI (héritée) Espace de travail