Interface CLI Databricks

L’interface de ligne de commande (CLI) Databricks est une interface facile à utiliser pour la plateforme Azure Databricks. Le projet open source est hébergé sur GitHub. l’interface CLI repose sur l' api REST Databricks 2,0 et est organisée en groupes de commandes basés sur les stratégies de cluster api 2,0, api clusters 2,0, api DBFS 2,0, groupes api 2,0, api pools d’instances 2,0, api travaux 2,1, api bibliothèques 2,0, Repos api2,0, Secrets api 2,0, api Token2,0 et api de l’espace de travail 2,0 via le , ,,,, et, respectivement,,, et les groupes de commandes.

Important

Cette interface CLI est en cours de développement et est publiée en tant que client expérimental. Cela signifie que les interfaces peuvent encore faire l’objet de modifications.

Configurer l’interface CLI

Cette section liste les conditions requises de l’interface CLI, et décrit comment installer et configurer votre environnement pour exécuter l’interface CLI.

Spécifications

  • Python 3 - 3.6 et ultérieur

  • Python 2 - 2.7.9 et ulté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 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 possède .

Limites

L’utilisation de l’interface CLI Databricks 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.

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.

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.

Pour lister la version de l’interface CLI actuellement installée, exécutez databricks --version (ou databricks -v).

Configurer l’authentification

Avant de pouvoir exécuter des commandes CLI, vous devez configurer l’authentification. Pour vous authentifier auprès de l’interface CLI, vous pouvez utiliser un jeton d’accès personnel Databricks ou un jeton Azure Active Directory (AAD).

Configurer l’authentification avec un jeton Azure AD

pour configurer l’interface CLI à l’aide d’un jeton Azure AD, générez le jeton Azure AD et stockez-le dans la variable d’environnement .

UNIX, Linux, MacOS
export DATABRICKS_AAD_TOKEN=<Azure-AD-token>

Sinon, utilisez jq :

export DATABRICKS_AAD_TOKEN=$(az account get-access-token | jq .accessToken --raw-output)
Windows
setx DATABRICKS_AAD_TOKEN "<Azure-AD-token>" /M

Sinon, utilisez Windows PowerShell et jq :

$databricks_aad_token = az account get-access-token | jq .accessToken --raw-output
[System.Environment]::SetEnvironmentVariable('DATABRICKS_AAD_TOKEN', $databricks_aad_token, [System.EnvironmentVariableTarget]::Machine)`

Exécuter 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.

Une fois l’invite terminée, vos informations d’identification d’accès sont stockées dans le fichier ~/.databrickscfg sur Unix, 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>

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

Pour que l’interface CLI utilise le jeton d’accès personnel, exécutez 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 de l’espace de travail, consultez URL d’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 Unix, 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 = <personal-access-token>

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

UNIX, Linux, MacOS

export DATABRICKS_CONFIG_FILE=<path-to-file>

Windows

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

Important

Étant donné que l’interface CLI repose sur l’API REST, votre configuration d’authentification dans votre fichier. netrc est prioritaire sur votre configuration dans .

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

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN
  • DATABRICKS_CONFIG_PROFILE

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

Profils de connexion

La configuration de l’interface CLI Databricks prend en charge plusieurs profils de connexion. La même installation de CLI Databricks 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.

Alias de groupes de commandes

Parfois, il peut être peu pratique de préfixer chaque appel de l’interface de commande CLI du nom d’un groupe de commandes, par exemple databricks workspace ls. Pour faciliter l’utilisation de l’interface CLI, 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

Azure Databricks a déjà créé un alias de databricks fs pour dbfs. databricks fs ls et dbfs ls sont équivalents.

Utiliser l’interface CLI

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

Afficher l’aide du groupe de commandes CLI

Vous listez les sous-commandes de n’importe quel groupe de commandes en exécutant databricks <group> --help (ou databricks <group> -h). Par exemple, vous répertoriez les sous-commandes de l’interface CLI de DBFS en exécutant databricks fs -h.

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

Vous listez l’aide d’une sous-commande en exécutant databricks <group> <subcommand> --help (ou databricks <group> <subcommand> -h). Par exemple, vous listez l’aide de la sous-commande de copie de fichiers DBFS en exécutant databricks fs cp -h.

Utiliser jq pour analyser la sortie de l’interface CLI

Certaines commandes de l’interface CLI Databricks 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 databricks jobs get et l’utiliser comme argument de la commande databricks jobs create. 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'
{
  "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 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 } ]'
[
  {
    "name": "My Cluster 1",
    "id": "1234-567890-grip123"
  },
  {
    "name": "My Cluster 2",
    "id": "2345-678901-patch234"
  }
]

Vous pouvez installer jq, par exemple, sur macOS à l’aide de Homebrew avec brew install jq ou sur Windows à l’aide de Chocolatey avec choco install jq. Pour plus d’informations sur jq , consultez le 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 :

UNIX, Linux, MacOS

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

databricks jobs run-now --job-id 9 --jar-params '["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 :

databricks jobs run-now --job-id 9 --jar-params "[\"20180505\", \"alantest\"]"

Dépannage

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

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 hosttoken valeurs et au .databrickscfg fichier, comme décrit dans host.
  • Rétrogradez votre installation de l’interface Databricks CLI à 0.11.0 ou antérieur, puis réexécutez votre script.

Commandes CLI