CLI di Databricks (legacy)

Articolo
10/03/2024

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 la CLI

Questa sezione descrive come configurare la CLI legacy di Databricks.

Installare o aggiornare la CLI

Questa sezione descrive come installare o aggiornare il computer di sviluppo per eseguire la CLI legacy di Databricks.

Installare la CLI

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

pip install databricks-cli

Aggiornare la 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 della CLI legacy di Databricks, è necessario configurare l'autenticazione tra la CLI legacy di Databricks e Azure Databricks. Questa sezione descrive come configurare l'autenticazione per la CLI legacy di Databricks.

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 con l'uso di un token di Microsoft Entra ID

Per configurare la CLI legacy di Databricks usando un token di Microsoft Entra ID, generare il token di Microsoft Entra ID (in precedenza Azure Active Directory) e archiviarlo 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 per area di lavoro, vedere URL per area di lavoro.

Dopo aver completato la richiesta, le credenziali di accesso vengono archiviate nel file ~/.databrickscfg su Linux o macOS o in %USERPROFILE%\.databrickscfg su 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 con l'uso di 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 su Linux o macOS o in %USERPROFILE%\.databrickscfg su Windows. Il file contiene una voce del profilo predefinita:

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

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 i profili di connessione sono stati configurati correttamente, è possibile eseguire un comando come il seguente con il nome di uno dei profili 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 visualizzare la guida della CLI legacy di Databricks, analizzare l'output della CLI legacy di Databricks 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 visualizzare l'elenco dei sottocomandi della CLI di DBFS, eseguire:

databricks fs -h

Visualizzare la Guida al sottocomando della CLI

Per elencare la Guida per un sottocomando si usa l'opzione --help o -h. Ad esempio, per elencare la Guida per il sottocomando dei file di copia 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 ls dw 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 del processo, è necessario accettare il campo settings di un comando ottieni processo e usarlo come argomento del comando crea processo. 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 della stringa JSON

I parametri di 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"]'

Finestre

è necessario racchiudere i parametri di stringa JSON tra virgolette doppie e le virgolette all'interno della stringa devono essere precedute 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 la CLI 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, il seguente script fa sì che la CLI 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 host e token al file .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.

Condividi tramite

CLI di Databricks (legacy)

Requisiti

Limiti

Configurare la CLI

Installare o aggiornare la CLI

Installare la CLI

Aggiornare la CLI

Configurare l'autenticazione

Configurare l'autenticazione con l'uso di un token di Microsoft Entra ID

Configurare l'autenticazione con l'uso di un token di accesso personale di Databricks

Linux o macOS

Windows

Testare la configurazione dell'autenticazione

Profili di connessione

Testare la connessione dei profili

Usare la CLI

Visualizzare la guida del gruppo di comandi della CLI

Visualizzare la Guida al sottocomando della CLI

Definire un alias per i gruppi di comandi

Usare `jq` per analizzare l'output della CLI

Parametri della stringa JSON

Linux o macOS

Finestre

Risoluzione dei problemi

Usare EOF insieme a `databricks configure` non funziona

Comandi della CLI

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

CLI di Databricks (legacy)

Requisiti

Limiti

Configurare la CLI

Installare o aggiornare la CLI

Installare la CLI

Aggiornare la CLI

Configurare l'autenticazione

Configurare l'autenticazione con l'uso di un token di Microsoft Entra ID

Configurare l'autenticazione con l'uso di un token di accesso personale di Databricks

Linux o macOS

Windows

Testare la configurazione dell'autenticazione

Profili di connessione

Testare la connessione dei profili

Usare la CLI

Visualizzare la guida del gruppo di comandi della CLI

Visualizzare la Guida al sottocomando della CLI

Definire un alias per i gruppi di comandi

Usare jq per analizzare l'output della CLI

Parametri della stringa JSON

Linux o macOS

Finestre

Risoluzione dei problemi

Usare EOF insieme a databricks configure non funziona

Comandi della CLI

Commenti e suggerimenti

Risorse aggiuntive

Usare `jq` per analizzare l'output della CLI

Usare EOF insieme a `databricks configure` non funziona