Condividi tramite

Migrazione dell'interfaccia della riga di comando di Databricks

  • Articolo

Questo articolo descrive come 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. Le versioni dell'interfaccia della riga di comando di Databricks 0.205 e successive sono disponibili in anteprima pubblica.

Per brevità, questo articolo si riferisce all'interfaccia della riga di comando di Databricks 0.18 e di seguito come interfaccia della riga di comando "legacy" e all'interfaccia della riga di comando di Databricks 0.205 e versioni successive come interfaccia della riga di comando "nuova".

Per altre informazioni sulla versione legacy e sulle nuove interfacce di riga, vedere:

Disinstallare l'interfaccia della riga di comando legacy

Se è installata l'interfaccia della riga di comando legacy e si vuole disinstallarla, usare pip (o pip3, a seconda della versione di Python) per eseguire il uninstall comando, come indicato di seguito:

pip uninstall databricks-cli

Installare la nuova interfaccia della riga di comando

Per informazioni su come installare la nuova interfaccia della riga di comando, vedere Installare o aggiornare l'interfaccia della riga di comando di Databricks.

Verificare l'installazione dell'interfaccia della riga di comando

Se non si è certi di usare la nuova interfaccia della riga di comando, seguire le istruzioni riportate in questa sezione per verificare e modificare in base alle esigenze. Prima di seguire queste istruzioni, assicurarsi di uscire da ambienti virtuali, conda ambienti o ambienti simili python.

Per controllare la versione dell'installazione predefinita dell'interfaccia della riga di comando, eseguire il comando seguente:

databricks -v

Se il numero di versione non è quello previsto, eseguire una delle operazioni seguenti:

  • Se si vuole usare una sola versione dell'interfaccia della riga di comando: disinstallare tutta la versione precedente dell'interfaccia della riga di comando che non si vuole più usare. Potrebbe essere necessario aggiornare lo sytem PATH operativo in modo che sia elencato il percorso della versione rimanente dell'interfaccia della riga di comando che si vuole usare.
  • Per continuare a usare più versioni dell'interfaccia della riga di comando: anteporre il percorso completo alla versione dell'interfaccia della riga di comando che si vuole usare per ogni chiamata all'interfaccia della riga di comando.
  • Se si vogliono continuare a usare più versioni dell'interfaccia della riga di comando, ma non si vuole mantenere in sospeso il percorso completo della versione dell'interfaccia della riga di comando usata più spesso: assicurarsi che il percorso completo di tale versione sia elencato per primo nel sistema operativo .PATH Si noti che è comunque necessario anteporre il percorso completo alle versioni dell'interfaccia della riga di comando che non sono elencate per prime nel sistema operativo .PATH

Per aggiornare il sistema operativo, PATHeseguire le operazioni seguenti:

Macos o Linux

  1. Elencare i percorsi in cui databricks è installato eseguendo uno dei comandi seguenti:

    which -a databricks

# Or:
where databricks

  2. Ottenere il percorso dell'installazione che si vuole usare senza anteporre il percorso completo a ogni chiamata all'interfaccia della riga di comando. Se non si è certi del percorso, eseguire il percorso completo di ogni posizione, seguito da -v, ad esempio:

    /usr/local/bin/databricks -v

  3. Per inserire il percorso dell'installazione che si vuole usare per primo in PATH, eseguire il comando seguente, sostituendo /usr/local/bin con il percorso che si vuole usare. Non aggiungere databricks alla fine di questo percorso. Ad esempio:

    export PATH="/usr/local/bin:$PATH"

  4. Per verificare che sia PATH stato impostato correttamente per la sessione del terminale corrente, eseguire seguito databricks da -v e controllare il numero di versione:

    databricks -v

  5. Per impostare PATH in questo modo ogni volta che si riavvia il terminale, aggiungere il comando dal passaggio 3 al file di inizializzazione della shell. Ad esempio, per Zshell, questo file si trova in genere in ~/.zshrc. Per Bash, questo file si trova in genere in ~/.bashrc. Per altre shell, vedere la documentazione del provider della shell.

  6. Dopo aver aggiornato il file di inizializzazione della shell, è necessario riavviare il terminale per applicare il valore aggiornato PATH .

Windows

  1. Fare clic con il pulsante destro del mouse sull'installazione di che si vuole usare senza anteporre il percorso completo a ogni chiamata all'interfaccia della riga di databricks comando.

  2. Fare clic su Apri percorso file.

  3. Si noti il percorso di databricks, ad esempio C:\Windows.

  4. Nel menu Start cercare Variabili di ambiente.

  5. Fare clic su Modifica variabili di ambiente per l'account.

  6. Selezionare la variabile Path nella sezione Variabili utente.<username>

  7. Fare clic su Modifica.

  8. Fai clic su Nuovo.

  9. Immettere il percorso da aggiungere, senza databricks.exe (ad esempio C:\Windows).

  10. Usare il pulsante Sposta su per spostare il percorso appena aggiunto all'inizio dell'elenco.

  11. Fare clic su OK.

  12. Per verificare che sia PATH stato impostato correttamente, aprire un nuovo prompt dei comandi, eseguire seguito databricks da -ve controllare il numero di versione:

    databricks -v

Usare tipi di autenticazione aggiuntivi

L'interfaccia della riga di comando legacy e la nuova interfaccia della riga di comando supportano sia l'autenticazione del token di accesso personale di Azure Databricks. Tuttavia, Databricks consiglia di usare altri tipi di autenticazione di Azure Databricks, se possibile, che supportano solo la nuova interfaccia della riga di comando.

Se è necessario usare l'autenticazione del token di accesso personale di Azure Databricks, Databricks consiglia di usare un account o un utente dell'area di lavoro di Azure Databricks associato a un'entità servizio. Vedere Gestire le entità servizio.

La nuova interfaccia della riga di comando supporta i token ID di Microsoft Entra oltre ai token di accesso personali di Azure Databricks. Questi token aggiuntivi sono più sicuri perché in genere scadono in un'ora, mentre i token di accesso personale di Azure Databricks possono essere validi da un giorno fino a un periodo illimitato. Ciò è particolarmente importante se un token viene accidentalmente controllato nei sistemi di controllo della versione a cui è possibile accedere da altri utenti. Inoltre, la nuova interfaccia della riga di comando può aggiornare automaticamente questi token aggiuntivi alla scadenza, mentre l'aggiornamento dei token di accesso personale di Azure Databricks è un processo manuale o può essere difficile da automatizzare.

Per altre informazioni, vedere Autenticazione per l'interfaccia della riga di comando di Databricks.

Confronti tra gruppi di comandi e comandi

La tabella seguente elenca i gruppi di comandi dell'interfaccia della riga di comando legacy e i nuovi equivalenti del gruppo di comandi dell'interfaccia della riga di comando. Dove esistono differenze significative tra cli, tabelle aggiuntive elencano comandi o opzioni legacy dell'interfaccia della riga di comando e i nuovi comandi o equivalenti di opzioni dell'interfaccia della riga di comando.

Gruppi di comandi

Gruppo di comandi legacy Nuovo gruppo di comandi
cluster-policies cluster-policies. Tutti i nomi dei comandi sono gli stessi.
clusters clusters. Tutti i nomi dei comandi sono gli stessi.
configure configure. Vedere Configurare le opzioni.
fs fs. Vedere comandi fs.
groups groups. Vedere i comandi dei gruppi.
instance-pools instance-pools. Tutti i nomi dei comandi sono gli stessi.
jobs jobs. Tutti i nomi dei comandi sono gli stessi.
libraries libraries. Tutti i nomi dei comandi sono uguali, ad eccezione di list. Il list comando non è più disponibile. Usare invece i all-cluster-statuses comandi o cluster-status .
pipelines pipelines. Vedere i comandi delle pipeline.
repos repos. Tutti i nomi dei comandi sono gli stessi.
runs jobs. Vedere Eseguire i comandi.
secrets secrets. Vedere i comandi dei segreti.
stack Non disponibile nella nuova interfaccia della riga di comando. Databricks consiglia di usare invece il provider Databricks Terraform.
tokens tokens. Vedere i comandi dei token.
unity-catalog Vari. Vedere i gruppi di comandi di unity-catalog.
workspace workspace. Vedere Comandi dell'area di lavoro.

Opzioni configure

Opzione legacy Nuova opzione
-o L'interfaccia della riga di comando legacy usa -o per l'autenticazione OAuth. La nuova interfaccia della riga di comando viene riutilizzata -o per specificare se l'output dell'interfaccia della riga di comando è in formato testo o JSON. Non applicabile ad Azure Databricks.
--oauth Non applicabile ad Azure Databricks.
-s oppure --scope Non applicabile ad Azure Databricks.
-t oppure --token -t o --token (stesso)
-f oppure --token-file Non disponibile nella nuova interfaccia della riga di comando.
--host --host (stesso)
--aad-token Usare --host e specificare un token microsoft Entra ID (in precedenza Azure Active Directory) quando richiesto anziché un token di accesso personale di Azure Databricks.
--insecure Non disponibile nella nuova interfaccia della riga di comando.
--jobs-api-version Non disponibile nella nuova interfaccia della riga di comando. La nuova interfaccia della riga di comando usa solo l'API Jobs 2.1. Per chiamare l'API Processi legacy 2.0, usare l'interfaccia della riga di comando legacy e vedere Interfaccia della riga di comando dei processi (legacy).
--debug Per il debug e la registrazione nella nuova interfaccia della riga di comando, vedere Modalità di debug.
--profile --profile (stesso) o -p
-h oppure --help -h o --help (stesso)

Comandi di fs

Tutti i fs comandi nell'interfaccia della riga di comando legacy sono gli stessi nella nuova interfaccia della riga di comando, ad eccezione fs mv del quale non è disponibile nella nuova interfaccia della riga di comando.

Comando legacy Nuovo comando
fs cat fs cat (stesso)
fs cp fs cp (stesso)
fs ls fs ls (stesso)
fs mkdirs fs mkdir
fs mv Non disponibile nella nuova interfaccia della riga di comando.
fs rm fs rm (stesso)

Comandi di groups

Comando legacy Nuovo comando
groups add-member groups patch
groups create groups create (stesso)
groups delete groups delete (stesso)
groups list groups list (stesso)
groups list-members groups list
groups list-parents groups list
groups remove-member groups patch

Comandi di pipelines

Comando legacy Nuovo comando
pipelines create pipelines create (stesso)
pipelines delete pipelines delete (stesso)
pipelines deploy pipelines create
pipelines edit pipelines update
pipelines get pipelines get (stesso)
pipelines list pipelines list-pipeline-events o pipelines list-pipelines o pipelines list-updates
pipelines reset pipelines reset (stesso)
pipelines start pipelines start update
pipelines stop pipelines stop (stesso)
pipelines update pipelines update (stesso)

Comandi di runs

Comando legacy Nuovo comando
runs cancel jobs cancel-run
runs get jobs get-run
runs get-output jobs get-run-output
runs list jobs list-runs
runs submit jobs submit

Comandi di secrets

Comando legacy Nuovo comando
secrets create-scope secrets create-scope (stesso)
secrets delete secrets delete-secret
secrets delete-acl secrets delete-acl (stesso)
secrets delete-scope secrets delete-scope (stesso)
secrets get-acl secrets get-acl (stesso)
secrets list secrets list-secrets
secrets list-acls secrets list-acls (stesso)
secrets list-scopes secrets list-scopes (stesso)
secrets put secrets put-secret
secrets put-acl secrets put-acl (stesso)
secrets write secrets put-secret
secrets write-acl secrets put-acl

Comandi di tokens

Comando legacy Nuovo comando
tokens create tokens create (stesso)
tokens list tokens list (stesso)
tokens revoke tokens delete

unity-catalog gruppi di comandi

unity-catalog <command> nell'interfaccia della riga di comando legacy diventa solo <command> nella nuova interfaccia della riga di comando.

Gruppo di comandi legacy Nuovo gruppo di comandi
unity-catalog catalogs catalogs (stesso ma rilasciare unity-catalog)
unity-catalog external-locations external-locations (stesso ma rilasciare unity-catalog)
unity-catalog lineage Non disponibile nella nuova interfaccia della riga di comando. Vedere Recuperare la derivazione usando l'API REST Derivazione dati.
unity-catalog metastores metastores (stesso ma rilasciare unity-catalog)
unity-catalog permissions grants
unity-catalog providers providers (stesso ma rilasciare unity-catalog)
unity-catalog recipients recipients (stesso ma rilasciare unity-catalog)
unity-catalog schemas schemas (stesso ma rilasciare unity-catalog)
unity-catalog shares shares (stesso ma rilasciare unity-catalog)
unity-catalog storage-credentials storage-credentials (stesso ma rilasciare unity-catalog)
unity-catalog tables tables (stesso ma rilasciare unity-catalog)

Comandi di workspace

Comando legacy Nuovo comando
workspace delete workspace delete (stesso)
workspace export workspace export (stesso)
workspace export-dir workspace export
workspace import workspace import (stesso)
workspace import-dir workspace import
workspace list workspace list (stesso)
workspace ls workspace list
workspace mkdirs workspace mkdirs (stesso)
workspace rm workspace delete

Argomenti predefiniti e posizionali

La maggior parte dei nuovi comandi dell'interfaccia della riga di comando ha almeno un argomento predefinito che non ha un'opzione associata. Alcuni nuovi comandi dell'interfaccia della riga di comando hanno due o più argomenti posizionali che devono essere specificati in un ordine specifico e che non dispongono di opzioni di accompagnamento. Questo è diverso dall'interfaccia della riga di comando legacy, in cui la maggior parte dei comandi richiede l'impostazione delle opzioni per tutti gli argomenti. Ad esempio, il comando della nuova interfaccia della riga di clusters get comando accetta un ID cluster come argomento predefinito. Tuttavia, il comando dell'interfaccia della riga di clusers get comando legacy richiede di specificare un'opzione --cluster-id insieme all'ID cluster. Ad esempio:

Per l'interfaccia della riga di comando legacy:

# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d

# This does **not** work with the legacy CLI - "Error:
#   Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d

Per la nuova interfaccia della riga di comando:

# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d

# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d

Come altro esempio, il comando della nuova interfaccia della riga di grants get comando accetta due argomenti predefiniti: il tipo a protezione diretta seguito dal nome completo dell'entità a protezione diretta. Tuttavia, il comando dell'interfaccia della riga di unity-catalog permissions get comando legacy richiede di specificare un'opzione --<securable-type> insieme al nome completo dell'entità a protezione diretta. Ad esempio:

Per l'interfaccia della riga di comando legacy:

databricks unity-catalog permissions get --schema main.default

Per la nuova interfaccia della riga di comando:

# This works with the new CLI.
databricks grants get schema main.default

# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default

Modalità di debug

L'interfaccia della riga di comando legacy offre un'opzione --debug per visualizzare l'analisi completa dello stack in caso di errore. Per la nuova interfaccia della riga di comando, l'opzione --debug non viene riconosciuta. Usare invece le opzioni seguenti:

  • Usare --log-file <path> per scrivere informazioni di log nel file specificato in <path>. Se questa opzione non viene specificata, le informazioni di log vengono restituite a stderr. --log-file Se si specifica senza specificare --log-level anche, non vengono scritte informazioni di log nel file.
  • Utilizzare --log-format <type> per specificare il formato delle informazioni registrate. <type> può essere text (impostazione predefinita, se non specificata) o json.
  • Usare --log-level <format> per specificare il livello di informazioni registrate. I valori consentiti sono disabled (impostazione predefinita, se non specificata), trace, warndebuginfo, , e .error

Per l'interfaccia della riga di comando legacy, l'esempio seguente mostra l'analisi completa dello stack in caso di errore:

databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

Per la nuova interfaccia della riga di comando, l'esempio seguente registra l'analisi dello stack completo in un file denominato new-cli-errors.log nella directory di lavoro corrente. L'analisi dello stack viene scritta nel file in formato JSON:

databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace

# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)

Domande frequenti

Questa sezione elenca le domande comuni sulla migrazione dalla versione legacy alla nuova interfaccia della riga di comando.

Che cosa accade all'interfaccia della riga di comando legacy?

L'interfaccia della riga di comando legacy è ancora disponibile ma non riceve aggiornamenti non critici. La documentazione dell'interfaccia della riga di comando legacy riflette questo aspetto. Databricks consiglia agli utenti di eseguire la migrazione alla nuova interfaccia della riga di comando il prima possibile.

L'interfaccia della riga di comando legacy è sempre stata in uno stato sperimentale con una dichiarazione di non responsabilità che Databricks non pianifica alcuna nuova funzionalità per l'interfaccia della riga di comando legacy e l'interfaccia della riga di comando legacy non è supportata tramite i canali di supporto di Databricks.

Quando verrà deprecata l'interfaccia della riga di comando legacy?

L'interfaccia della riga di comando legacy è sempre stata in uno stato sperimentale con una dichiarazione di non responsabilità che Databricks non pianifica alcuna nuova funzionalità per l'interfaccia della riga di comando legacy e l'interfaccia della riga di comando legacy non è supportata tramite i canali di supporto di Databricks.

Databricks non ha stabilito una data o una sequenza temporale per deprecare l'interfaccia della riga di comando legacy. Tuttavia, Databricks consiglia agli utenti di eseguire la migrazione al nuovo interfaccia della riga di comando il prima possibile.

Quando verrà rilasciata la nuova interfaccia della riga di comando come disponibile a livello generale?

Non è stata stabilita una data di rilascio o una sequenza temporale per il rilascio della nuova interfaccia della riga di comando perché la disponibilità generale non è stata stabilita. Questo dipenderà dal feedback ricevuto dagli utenti durante l'anteprima pubblica di Databricks.

Quali sono le differenze principali tra le interfacce cli legacy e le nuove interfacce della riga di comando?

  • L'interfaccia della riga di comando legacy è stata rilasciata come pacchetto Python. La nuova interfaccia della riga di comando viene rilasciata come eseguibile autonomo e non richiede alcuna dipendenza di runtime installata.
  • La nuova interfaccia della riga di comando ha una copertura completa delle API REST di Databricks. L'interfaccia della riga di comando legacy non è disponibile.
  • La nuova interfaccia della riga di comando è disponibile come anteprima pubblica. L'interfaccia della riga di comando legacy rimane in uno stato sperimentale.

La nuova interfaccia della riga di comando ha parità di funzionalità completa con l'interfaccia della riga di comando legacy?

La nuova interfaccia della riga di comando ha copertura per quasi tutti i comandi dell'interfaccia della riga di comando legacy. Tuttavia, in particolare assente dalla nuova interfaccia della riga di comando è il stacks gruppo di comandi nell'interfaccia della riga di comando legacy. Inoltre, alcuni gruppi di comandi legacy dell'interfaccia della riga di comando, ad unity-catalog esempio e runs sono stati sottoposti a refactoring in nuovi gruppi di comandi nella nuova interfaccia della riga di comando. Per indicazioni sulla migrazione, vedere le informazioni fornite in precedenza in questo articolo.

Ricerca per categorie eseguire la migrazione dalla versione legacy alla nuova interfaccia della riga di comando?

Per indicazioni sulla migrazione, vedere le informazioni fornite in precedenza in questo articolo. Si noti che la nuova interfaccia della riga di comando non è una sostituzione dell'interfaccia della riga di comando legacy e richiede una configurazione per passare dalla versione legacy alla nuova interfaccia della riga di comando.

Le installazioni delle interfacce di riga legacy e nuove possono esistere nello stesso computer?

Sì. Le installazioni di clI legacy e nuove possono esistere nello stesso computer, ma devono trovarsi in directory diverse. Poiché i file eseguibili sono entrambi denominati databricks, è necessario controllare quale eseguibile viene eseguito per impostazione predefinita configurando il computer .PATH Se si vuole eseguire la nuova interfaccia della riga di comando ma in qualche modo si esegue accidentalmente l'interfaccia della riga di comando legacy, per impostazione predefinita l'interfaccia della riga di comando legacy eseguirà la nuova interfaccia della riga di comando con gli stessi argomenti e visualizzerà il messaggio di avviso seguente:

Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>

Because both are installed and available in PATH,
I assume you are trying to run the newer version.

If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>

Come illustrato nel messaggio di avviso precedente, è possibile impostare la DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION variabile di ambiente su 1 per disabilitare questo comportamento ed eseguire invece l'interfaccia della riga di comando legacy.

Come ottenere assistenza

Per ottenere informazioni sulla migrazione dall'interfaccia della riga di comando legacy alla nuova interfaccia della riga di comando, vedere le risorse seguenti: