Condividi tramite

Interfaccia della riga di comando di Databricks (legacy)

  • Articolo

Importante

Questa documentazione è stata ritirata e potrebbe non essere aggiornata.

Databricks consiglia di usare l'interfaccia della riga di comando di Databricks versione 0.205 o successiva anziché l'interfaccia della riga di comando legacy di Databricks versione 0.18 o successiva. L'interfaccia della riga di comando di Databricks versione 0.18 o successiva non è supportata da Databricks. Per informazioni sull'interfaccia della riga di comando di Databricks 0.205 e versioni successive, vedere Che cos'è l'interfaccia della riga di comando di Databricks?.

Per eseguire la migrazione dall'interfaccia della riga di comando di Databricks versione 0.18 o successiva all'interfaccia della riga di comando di Databricks versione 0.205 o successiva, vedere Migrazione dell'interfaccia della riga di comando di Databricks.

L'interfaccia della riga di comando legacy di Databricks si trova in uno stato sperimentale . Databricks non pianifica attualmente alcuna nuova funzionalità per l'interfaccia della riga di comando di Databricks legacy.

L'interfaccia della riga di comando 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 nell'interfaccia della riga di comando per il repository Databricks in GitHub.

L'interfaccia della riga di comando legacy di Databricks (nota anche come interfaccia della riga di comando 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 e l'esecuzione dell'interfaccia della riga di comando di Databricks legacy con questa installazione python genera 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 dell'interfaccia della riga di comando di Databricks legacy 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 l'interfaccia della riga di comando di Databricks legacy.

Installare o aggiornare l'interfaccia della riga di comando

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

Installare l'interfaccia della riga di comando

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

pip install databricks-cli

Aggiornare l'interfaccia della riga di comando

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

pip install databricks-cli --upgrade

Per elencare la versione dell'interfaccia della riga di comando di Databricks legacy 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 l'interfaccia della riga di comando di Databricks legacy, è possibile usare un token di accesso personale di Databricks o un token 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, vedere Gestire i token per un'entità servizio.

Configurare l'autenticazione usando un token microsoft Entra ID (in precedenza Azure Active Directory)

Per configurare l'interfaccia della riga di comando legacy di Databricks usando un token ID Microsoft Entra, generare il token Microsoft Entra ID (in precedenza Azure Active Directory) e archiviarlo nella variabile DATABRICKS_AAD_TOKENdi ambiente .

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 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 .databrickscfg file esiste già, il profilo di configurazione del DEFAULT file viene sovrascritto con i nuovi dati. Per creare un profilo di configurazione con un nome diverso, vedere Profili di connessione.

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

Per configurare l'interfaccia della riga di comando di Databricks legacy per l'uso di un token di accesso personale, eseguire il comando seguente:

databricks configure --token

Il comando inizia eseguendo il prompt:

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 eseguendo il prompt 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 .databrickscfg file esiste già, il profilo di configurazione del DEFAULT file viene sovrascritto con i nuovi dati. Per creare un profilo di configurazione con un nome diverso, vedere Profili di connessione.

Per l'interfaccia della riga di comando 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>
Finestre
setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

Importante

A partire dall'interfaccia della riga di comando 0.17.2, l'interfaccia della riga di comando non funziona con un file .netrc. È possibile avere un .netrc file nell'ambiente per altri scopi, ma l'interfaccia della riga di comando non userà tale .netrc file.

L'interfaccia della riga di comando 0.8.0 e versioni successive supporta le variabili di ambiente di Azure Databricks seguenti:

  • 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 nella radice DBFS dell'area di lavoro associata al DEFAULT profilo.

Profili di connessione

La configurazione legacy dell'interfaccia della riga di comando di Databricks supporta più profili di connessione. La stessa installazione dell'interfaccia della riga di comando di Databricks legacy può essere usata per effettuare chiamate API in 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 .databrickscfg file 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 utilizzato il profilo predefinito. Se non viene trovato un profilo predefinito, viene richiesto di configurare l'interfaccia della riga di comando con un profilo predefinito.

Testare i profili di connessione

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 nella radice 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 .databrickscfg file.

Usare l'interfaccia della riga di comando

Questa sezione illustra come ottenere la Guida dell'interfaccia della riga di comando di Databricks legacy, analizzare l'output dell'interfaccia della riga di comando di Databricks legacy e richiamare i comandi in ogni gruppo di comandi.

Visualizzare la guida del gruppo di comandi dell'interfaccia della riga di comando

È 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 sottocomando dell'interfaccia della riga di comando

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

databricks fs cp -h

Gruppi di comandi alias

A volte può risultare scomodo anteporre ogni chiamata dell'interfaccia della riga di comando di Databricks legacy con il nome di un gruppo di comandi, ad esempio databricks workspace ls nell'interfaccia della riga di comando legacy di Databricks. Per semplificare l'uso dell'interfaccia della riga di comando di Databricks legacy, è possibile eseguire l'alias dei gruppi di comandi ai comandi più brevi. Ad esempio, per abbreviare databricks workspace ls dw ls a nella shell di Bourne, è possibile aggiungere alias dw="databricks workspace" al profilo Bash appropriato. Questo file si trova in genere in ~/.bash_profile.

Suggerimento

L'interfaccia della riga di comando di Databricks legacy ha già alias a dbfsdatabricks fs ls e dbfs ls sono equivalentidatabricks fs.

Usare jq per analizzare l'output dell'interfaccia della riga di comando

Alcuni comandi legacy dell'interfaccia della riga di comando di Databricks generano la risposta JSON 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 processo, è necessario accettare il settings campo 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 comando seguente 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 comando seguente 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 in macOS usando Homebrew con brew install jq o in 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

Le sezioni seguenti forniscono suggerimenti per la risoluzione dei problemi comuni relativi all'interfaccia della riga di comando di Databricks legacy.

L'uso di EOF con 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 databricks configure comando 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 host valori e token al .databrickscfg file come descritto in Configurare l'autenticazione.
  • Effettuare il downgrade dell'installazione dell'interfaccia della riga di comando di Databricks alla versione 0.11.0 o successiva ed eseguire di nuovo lo script.

Comandi dell'interfaccia della riga di comando