Migrazione dell'interfaccia della riga di comando di Databricks
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:
- Interfaccia della riga di comando di Databricks (legacy) per l'interfaccia della riga di comando legacy.
- Che cos'è l'interfaccia della riga di comando di Databricks? per la nuova interfaccia della riga di comando.
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
PATHoperativo 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 .
PATHSi 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
Elencare i percorsi in cui
databricksè installato eseguendo uno dei comandi seguenti:which -a databricks # Or: where databricksOttenere 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 -vPer inserire il percorso dell'installazione che si vuole usare per primo in
PATH, eseguire il comando seguente, sostituendo/usr/local/bincon il percorso che si vuole usare. Non aggiungeredatabricksalla fine di questo percorso. Ad esempio:export PATH="/usr/local/bin:$PATH"Per verificare che sia
PATHstato impostato correttamente per la sessione del terminale corrente, eseguire seguitodatabricksda-ve controllare il numero di versione:databricks -vPer impostare
PATHin 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.Dopo aver aggiornato il file di inizializzazione della shell, è necessario riavviare il terminale per applicare il valore aggiornato
PATH.
Finestre
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
databrickscomando.Fare clic su Apri percorso file.
Si noti il percorso di
databricks, ad esempioC:\Windows.Nel menu Start cercare Variabili di ambiente.
Fare clic su Modifica variabili di ambiente per l'account.
Selezionare la variabile Path nella sezione Variabili utente.
<username>Fare clic su Modifica.
Fai clic su Nuovo.
Immettere il percorso da aggiungere, senza
databricks.exe(ad esempioC:\Windows).Usare il pulsante Sposta su per spostare il percorso appena aggiunto all'inizio dell'elenco.
Fare clic su OK.
Per verificare che sia
PATHstato impostato correttamente, aprire un nuovo prompt dei comandi, eseguire seguitodatabricksda-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 |
Diverso. 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 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-fileSe si specifica senza specificare--log-levelanche, non vengono scritte informazioni di log nel file. - Utilizzare
--log-format <type>per specificare il formato delle informazioni registrate.<type>può esseretext(impostazione predefinita, se non specificata) ojson. - Usare
--log-level <format>per specificare il livello di informazioni registrate. I valori consentiti sonodisabled(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: