Condividi tramite

CLI di Databricks (legacy)

  • Articolo

Importante

Questa documentazione è stata ritirata e potrebbe non essere aggiornata.

Databricks consiglia di usare la CLI di Databricks versione 0.205 o successiva anziché la CLI legacy di Databricks versione 0.18 o precedente. La CLI di Databricks versione 0.18 o precedente non è supportata da Databricks. Per informazioni sulla CLI di Databricks versione 0.205 o successiva, vedere Che cos'è la CLI di Databricks?.

Per eseguire la migrazione dalla CLI di Databricks versione 0.18 o precedente alla CLI di Databricks versione 0.205 o successiva, vedere Migrazione della CLI di Databricks.

La CLI legacy di Databricks si trova in uno stato di sperimentazione. Attualmente, Databricks non pianifica alcuna nuova funzionalità per la CLI legacy di Databricks.

La CLI legacy di Databricks non è supportata tramite i canali di supporto di Databricks. Per fornire commenti e suggerimenti, porre domande e segnalare i problemi, usare la scheda Problemi nel repository CLI di Databricks su GitHub.

L'interfaccia della riga di comando legacy di Databricks (nota anche come CLI legacy di Databricks) è un'utilità che fornisce un'interfaccia facile da usare per automatizzare la piattaforma Azure Databricks dal terminale, dal prompt dei comandi o dagli script di automazione.

Requisiti

  • Python 3 - 3.6 e versioni successive
  • Python 2 - 2.7.9 e versioni successive

Importante

In MacOS l'installazione predefinita di Python 2 non implementa il protocollo TLSv1_2; eseguire la CLI legacy di Databricks con questa installazione di Python restituisce l'errore AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'. Usare Homebrew per installare una versione di Python che includa ssl.PROTOCOL_TLSv1_2.

Limiti

L'uso della CLI legacy di Databricks con i contenitori di archiviazione abilitati per il firewall non è supportato In Databricks è consigliabile usare Databricks Connect o az storage.

Configurare l'interfaccia della riga di comando

Questa sezione descrive come configurare la versione legacy dell'interfaccia a riga di comando di Databricks.

Installare o aggiornare il CLI

Questa sezione descrive come installare o aggiornare il computer di sviluppo per eseguire l'interfaccia della riga di comando di Databricks legacy.

Installare la CLI

Eseguire pip install databricks-cli usando la versione appropriata di pip per l'installazione di Python.

pip install databricks-cli

Aggiornare il CLI

Eseguire pip install databricks-cli --upgrade usando la versione appropriata di pip per l'installazione di Python.

pip install databricks-cli --upgrade

Per elencare la versione della CLI legacy di Databricks attualmente installata, eseguire databricks --version:

databricks --version

Configurare l'autenticazione

Prima di eseguire i comandi legacy dell'interfaccia della riga di comando di Databricks, è necessario configurare l'autenticazione tra l'interfaccia della riga di comando di Databricks legacy e Azure Databricks. Questa sezione descrive come configurare l'autenticazione per l'interfaccia della riga di comando di Databricks legacy.

Per eseguire l'autenticazione con la CLI legacy di Databricks, è possibile usare un token di accesso personale di Databricks o un token di Microsoft Entra ID (in precedenza Azure Active Directory).

Nota

Come procedura consigliata per la sicurezza, quando si esegue l'autenticazione con strumenti automatizzati, sistemi, script e app, Databricks consiglia di usare token di accesso personali appartenenti alle entità servizio, anziché agli utenti dell'area di lavoro. Per creare token per le entità servizio, consultare Gestire i token per un'entità servizio.

Configurare l'autenticazione usando un token ID di Microsoft Entra

Per configurare la CLI legacy di Databricks usando un token Microsoft Entra ID, generare il token Microsoft Entra ID (in precedenza Azure Active Directory) e salvarlo nella variabile di ambiente DATABRICKS_AAD_TOKEN.

Esegui questo comando:

databricks configure --aad-token

Il comando visualizza la richiesta:

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

Immettere l'URL per area di lavoro con il formato https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Per ottenere l'URL specifico per area di lavoro, vedere URL per area di lavoro.

Dopo aver completato la richiesta, le credenziali di accesso vengono archiviate nel file ~/.databrickscfg in Linux o macOS o %USERPROFILE%\.databrickscfg in Windows. Il file contiene una voce del profilo predefinita:

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

Se il file .databrickscfg esiste già, il profilo di configurazione del file DEFAULT viene sovrascritto con i nuovi dati. Per creare un profilo di configurazione con un nome diverso, vedere Profili di connessione.

Configurare l'autenticazione usando un token di accesso personale di Databricks

Per configurare la CLI legacy di Databricks per l'uso di un token di accesso personale, eseguire il comando seguente:

databricks configure --token

Il comando inizia visualizzando la richiesta:

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

Immettere l'URL per area di lavoro con il formato https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Per ottenere l'URL per area di lavoro, vedere URL per area di lavoro.

Il comando continua visualizzando la richiesta per immettere il token di accesso personale:

Token:

Dopo aver completato le richieste, le credenziali di accesso vengono archiviate nel file ~/.databrickscfg in Linux o macOS o %USERPROFILE%\.databrickscfg in Windows. Il file contiene una voce del profilo predefinita:

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

Se il file .databrickscfg esiste già, il profilo di configurazione del file DEFAULT viene sovrascritto con i nuovi dati. Per creare un profilo di configurazione con un nome diverso, vedere Profili di connessione.

Per la CLI 0.8.1 e versioni successive, è possibile modificare il percorso di questo file impostando la variabile di ambiente DATABRICKS_CONFIG_FILE.

Linux o macOS
export DATABRICKS_CONFIG_FILE=<path-to-file>
Windows
setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

Importante

A partire dalla CLI 0.17.2, la CLI non funziona con un file .netrc. È possibile avere un file .netrc nell'ambiente per altri scopi, ma la CLI non userà il file .netrc.

La CLI 0.8.0 e versioni successive supporta le seguenti variabili di ambiente di Azure Databricks:

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN

Un'impostazione della variabile di ambiente ha la precedenza sull'impostazione specificata nel file di configurazione.

Testare la configurazione dell'autenticazione

Per verificare se l'autenticazione è stata configurata correttamente, è possibile eseguire un comando come il seguente:

databricks fs ls dbfs:/

In caso di esito positivo, questo comando elenca i file e le directory nel root DBFS dell'area di lavoro associata al profilo DEFAULT.

Profili di connessione

La configurazione della CLI legacy di Databricks supporta più profili di connessione. È possibile usare la stessa installazione della CLI legacy di Databricks per eseguire chiamate API su più aree di lavoro di Azure Databricks.

Per aggiungere un profilo di connessione, specificare un nome univoco per il profilo:

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

Il file .databrickscfg contiene una voce del profilo corrispondente:

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

Per usare il profilo di connessione:

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

Se --profile <profile-name> non viene specificato, viene usato il valore predefinito. Se non viene trovato un profilo predefinito, viene richiesto di configurare la CLI con un profilo predefinito.

Testare la connessione dei profili

Per verificare se si configurano correttamente profili di connessione, è possibile eseguire un comando come il seguente con uno dei nomi del profilo di connessione:

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

In caso di esito positivo, questo comando elenca i file e le directory nel root DBFS dell'area di lavoro per il profilo di connessione specificato. Eseguire questo comando per ogni profilo di connessione da testare.

Per visualizzare i profili disponibili, vedere il file .databrickscfg.

Usare la CLI

Questa sezione illustra come ottenere la Guida di Databricks CLI legacy, analizzare l'output di Databricks CLI legacy e richiamare i comandi in ogni gruppo di comandi.

Visualizzare la guida del gruppo di comandi della CLI

È possibile elencare i sottocomandi per qualsiasi gruppo di comandi usando l'opzione --help o -h. Ad esempio, per elencare i sottocomandi dell'interfaccia della riga di comando di DBFS:

databricks fs -h

Visualizzare la Guida al sottocomando della CLI

È possibile elencare la guida per un sottocomando usando l'opzione --help o -h. Ad esempio, per elencare la guida per il sottocomando di copia dei file DBFS:

databricks fs cp -h

Definire un alias per i gruppi di comandi

In alcuni casi può risultare scomodo anteporre il nome di un gruppo di comandi a ogni chiamata della CLI legacy di Databricks, ad esempio databricks workspace ls nella CLI legacy di Databricks. Per semplificare l'uso della CLI legacy di Databricks, è possibile definire un alias per i gruppi di comandi in modo da abbreviare i comandi. Ad esempio, per abbreviare il comando databricks workspace lsdw ls nella shell bash (Bourne Again Shell), è possibile aggiungere alias dw="databricks workspace" al profilo bash appropriato. Questo file si trova in genere in ~/.bash_profile.

Suggerimento

La CLI legacy di Databricks ha già un alias di databricks fs per dbfs; databricks fs ls e dbfs ls sono equivalenti.

Usare jq per analizzare l'output della CLI

Alcuni comandi della CLI legacy di Databricks visualizzano la risposta JSON restituita dall'endpoint API. In alcuni casi può essere utile analizzare parti del codice JSON per inviare tramite pipe altri comandi. Ad esempio, per copiare una definizione di job, è necessario prendere il campo settings di un comando get-job e usarlo come argomento per il comando create-job. In questi casi, è consigliabile usare l'utilità jq.

Ad esempio, il seguente comando stampa le impostazioni del processo con l'ID 233.

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

Output:

{
  "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
}

Come altro esempio, il seguente comando stampa solo i nomi e gli ID di tutti i cluster disponibili nell'area di lavoro:

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

Output:

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

È possibile installare jq ad esempio su macOS usando Homebrew con brew install jq o su Windows usando Chocolatey con choco install jq. Per altre informazioni su jq, vedere il manuale di jq.

Parametri di stringa JSON

I parametri stringa vengono gestiti in modo diverso a seconda del sistema operativo:

Linux o macOS

È necessario racchiudere i parametri di stringa JSON tra virgolette singole. Ad esempio:

'["20180505", "alantest"]'

Windows

È necessario racchiudere i parametri di stringa JSON tra virgolette doppie e i caratteri virgolette all'interno della stringa devono essere preceduti da \. Ad esempio:

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

Risoluzione dei problemi

Nella seguenti sezioni vengono forniti suggerimenti per la risoluzione dei problemi comuni con la CLI legacy di Databricks.

Usare EOF insieme a databricks configure non funziona

Per l'interfaccia della riga di comando di Databricks 0.12.0 e versioni successive, l'uso della sequenza di fine del file (EOF) in uno script per passare i parametri al comando databricks configure non funziona. Ad esempio, lo script seguente fa sì che l'interfaccia della riga di comando di Databricks ignori i parametri e non venga generato alcun messaggio di errore:

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

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

Per risolvere il problema, eseguire una di queste operazioni:

  • Usare una delle altre opzioni di configurazione a livello di codice come descritto in Configurare l'autenticazione.
  • Aggiungere manualmente i valori di host e token al file di .databrickscfg come descritto in Configurare l'autenticazione.
  • Effettuare il downgrade dell'installazione della CLI di Databricks alla versione 0.11.0 o precedente ed eseguire di nuovo lo script.

Comandi della CLI