Databricks CLI-migrering

Artikel
04/24/2024

Den här artikeln beskriver hur du migrerar från Databricks CLI version 0.18 eller senare till Databricks CLI version 0.205 eller senare. Databricks CLI-versionerna 0.205 och senare finns i offentlig förhandsversion.

För korthet refererar den här artikeln till Databricks CLI-versionerna 0.18 och nedan som "äldre" CLI och Databricks CLI-versionerna 0.205 och senare som "nya" CLI.

Mer information om äldre och nya CLI:er finns i:

Databricks CLI (äldre) för äldre CLI.
Vad är Databricks CLI? för det nya CLI.

Avinstallera det äldre CLI

Om du har installerat det äldre CLI:et uninstall och vill avinstallera det använder pip du (eller pip3, beroende på din version av Python) för att köra kommandot enligt följande:

pip uninstall databricks-cli

Installera det nya CLI

Information om hur du installerar det nya CLI finns i Installera eller uppdatera Databricks CLI.

Verifiera CLI-installationen

Om du inte är säker på om du använder det nya CLI följer du anvisningarna i det här avsnittet för att verifiera och justera efter behov. Innan du följer dessa instruktioner måste du avsluta alla virtuella Python-miljöer, conda miljöer eller liknande miljöer.

Kör följande kommando för att kontrollera versionen av din standardinstallation av CLI:

databricks -v

Om versionsnumret inte är det du förväntar dig gör du något av följande:

Om du bara vill använda en version av CLI: avinstallera alla tidigare versioner av CLI som du inte längre vill använda. Du kan behöva uppdatera dina driftssytem så PATH att sökvägen till den återstående versionen av CLI som du vill använda visas.
Om du vill fortsätta använda flera versioner av CLI: förbered den fullständiga sökvägen till den version av CLI som du vill använda för varje anrop till CLI.
Om du vill fortsätta använda flera versioner av CLI, men inte vill fortsätta att vänta på den fullständiga sökvägen till den version av CLI som du använder oftast: kontrollera att den fullständiga sökvägen till den versionen visas först i operativsystemets PATH. Observera att du fortfarande måste förbereda den fullständiga sökvägen till versioner av CLI som inte visas först i operativsystemets PATH.

Gör följande för att uppdatera operativsystemets PATH:

Macos eller Linux

Visa en lista över sökvägarna där databricks installeras genom att köra något av följande kommandon:
```
which -a databricks

# Or:
where databricks
```
Hämta sökvägen till den installation som du vill använda utan att lägga till den fullständiga sökvägen till varje anrop till CLI. Om du inte är säker på vilken sökväg det här är kör du den fullständiga sökvägen till varje plats följt av -v, till exempel:
```
/usr/local/bin/databricks -v
```
Om du vill placera sökvägen till den installation som du vill använda först i PATHkör du följande kommando och ersätter /usr/local/bin med den sökväg som du vill använda. Lägg inte till databricks i slutet av den här sökvägen. Till exempel:
```
export PATH="/usr/local/bin:$PATH"
```
Kontrollera att den PATH har angetts korrekt för den aktuella terminalsessionen genom att köra databricks följt av -v och kontrollera versionsnumret:
```
databricks -v
```
Om du vill ha inställningen PATH på det här sättet varje gång du startar om terminalen lägger du till kommandot från steg 3 i initieringsfilen för gränssnittet. För Zshell finns den här filen till exempel vanligtvis på ~/.zshrc. För Bash finns den här filen vanligtvis på ~/.bashrc. Andra gränssnitt finns i dokumentationen för din shell-provider.
När du har uppdaterat initieringsfilen för gränssnittet måste du starta om terminalen för att tillämpa det uppdaterade PATH värdet.

Windows

Högerklicka på installationen av databricks som du vill använda utan att lägga till den fullständiga sökvägen till varje anrop till CLI.
Klicka på Öppna filplats.
Observera sökvägen till , till databricksexempel C:\Windows.
Sök efter miljövariabler på Start-menyn.
Klicka på Redigera miljövariabler för ditt konto.
Välj variabeln Sökväg i avsnittet Användarvariabler för<username>.
Klicka på Redigera.
Klicka på Ny.
Ange den sökväg som du vill lägga till, utan databricks.exe (till exempel C:\Windows).
Använd knappen Flytta upp för att flytta sökvägen som du precis lade till i början av listan.
Klicka på OK.
Om du vill kontrollera att har PATH angetts korrekt öppnar du en ny kommandotolk, kör databricks följt av -voch kontrollerar versionsnumret:
```
databricks -v
```

Använda ytterligare autentiseringstyper

Både det äldre CLI:et och det nya CLI:et har stöd för personlig åtkomsttokenautentisering i Azure Databricks. Databricks rekommenderar dock att du använder andra Azure Databricks-autentiseringstyper om möjligt, vilket endast det nya CLI stöder.

Om du måste använda autentisering med personlig åtkomsttoken i Azure Databricks rekommenderar Databricks att du använder en som är associerad med ett huvudnamn för tjänsten i stället för ett Azure Databricks-konto eller en arbetsyteanvändare. Läs mer i Hantera tjänstens huvudnamn.

Det nya CLI stöder Microsoft Entra ID-token utöver personliga åtkomsttoken för Azure Databricks. Dessa ytterligare token är säkrare eftersom de vanligtvis upphör att gälla om en timme, medan personliga åtkomsttoken för Azure Databricks kan vara giltiga från en dag upp till obestämd tid. Detta är särskilt viktigt om en token av misstag checkas in i versionskontrollsystem som kan nås av andra. Det nya CLI kan också automatiskt uppdatera dessa ytterligare token när de upphör att gälla, medan uppdatering av personliga åtkomsttoken för Azure Databricks antingen är en manuell process eller kan vara svår att automatisera.

Mer information finns i Autentisering för Databricks CLI.

Jämförelse av kommandogrupper och kommandon

I följande tabell visas de äldre CLI-kommandogrupperna och deras nya CLI-kommandogruppsekvivalenter. Om det finns betydande skillnader mellan CLIs listar ytterligare tabeller äldre CLI-kommandon eller alternativ och deras nya CLI-kommando eller alternativmotsvarigheter.

Kommandogrupper

Äldre kommandogrupp	Ny kommandogrupp
`cluster-policies`	`cluster-policies`. Alla kommandonamn är desamma.
`clusters`	`clusters`. Alla kommandonamn är desamma.
`configure`	`configure`. Se Konfigurera alternativ.
`fs`	`fs`. Se fs-kommandon.
`groups`	`groups`. Se gruppkommandon.
`instance-pools`	`instance-pools`. Alla kommandonamn är desamma.
`jobs`	`jobs`. Alla kommandonamn är desamma.
`libraries`	`libraries`. Alla kommandonamn är samma förutom `list`. Kommandot `list` är inte längre tillgängligt. Använd kommandona `all-cluster-statuses` eller `cluster-status` i stället.
`pipelines`	`pipelines`. Se pipelinekommandon.
`repos`	`repos`. Alla kommandonamn är desamma.
`runs`	`jobs`. Se körningskommandon.
`secrets`	`secrets`. Se kommandon för hemligheter.
`stack`	Inte tillgängligt i det nya CLI. Databricks rekommenderar att du använder Databricks Terraform-providern i stället.
`tokens`	`tokens`. Se tokenkommandon.
`unity-catalog`	Olika. Se kommandogrupper för unity-catalog.
`workspace`	`workspace`. Se kommandon för arbetsytor.

`configure` Alternativ

Äldre alternativ	Nytt alternativ
`-o`	Det äldre CLI använder `-o` för OAuth-autentisering. De nya CLI-repurposen `-o` för att ange om CLI-utdata är i text- eller JSON-format. Gäller inte för Azure Databricks.
`--oauth`	Gäller inte för Azure Databricks.
`-s` eller `--scope`	Gäller inte för Azure Databricks.
`-t` eller `--token`	`-t` eller `--token` (samma)
`-f` eller `--token-file`	Inte tillgängligt i det nya CLI.
`--host`	`--host` (samma)
`--aad-token`	Använd `--host` och ange en Microsoft Entra ID-token (tidigare Azure Active Directory) när du uppmanas att göra det i stället för en personlig åtkomsttoken för Azure Databricks.
`--insecure`	Inte tillgängligt i det nya CLI.
`--jobs-api-version`	Inte tillgängligt i det nya CLI. Det nya CLI använder endast jobb-API 2.1. Om du vill anropa det äldre jobb-API:et 2.0 använder du det äldre CLI:et och läser Jobb CLI (äldre).
`--debug`	Information om felsökning och loggning i det nya CLI finns i Felsökningsläge.
`--profile`	`--profile` (samma) eller `-p`
`-h` eller `--help`	`-h` eller `--help` (samma)

`fs` Kommandon

Alla fs kommandon i det äldre CLI:et är desamma i det nya CLI, förutom fs mv att de inte är tillgängliga i det nya CLI.

Äldre kommando	Nytt kommando
`fs cat`	`fs cat` (samma)
`fs cp`	`fs cp` (samma)
`fs ls`	`fs ls` (samma)
`fs mkdirs`	`fs mkdir`
`fs mv`	Inte tillgängligt i det nya CLI.
`fs rm`	`fs rm` (samma)

`groups` Kommandon

Äldre kommando	Nytt kommando
`groups add-member`	`groups patch`
`groups create`	`groups create` (samma)
`groups delete`	`groups delete` (samma)
`groups list`	`groups list` (samma)
`groups list-members`	`groups list`
`groups list-parents`	`groups list`
`groups remove-member`	`groups patch`

`pipelines` Kommandon

Äldre kommando	Nytt kommando
`pipelines create`	`pipelines create` (samma)
`pipelines delete`	`pipelines delete` (samma)
`pipelines deploy`	`pipelines create`
`pipelines edit`	`pipelines update`
`pipelines get`	`pipelines get` (samma)
`pipelines list`	`pipelines list-pipeline-events`eller `pipelines list-pipelinespipelines list-updates`
`pipelines reset`	`pipelines reset` (samma)
`pipelines start`	`pipelines start update`
`pipelines stop`	`pipelines stop` (samma)
`pipelines update`	`pipelines update` (samma)

`runs` Kommandon

Äldre kommando	Nytt kommando
`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`

`secrets` Kommandon

Äldre kommando	Nytt kommando
`secrets create-scope`	`secrets create-scope` (samma)
`secrets delete`	`secrets delete-secret`
`secrets delete-acl`	`secrets delete-acl` (samma)
`secrets delete-scope`	`secrets delete-scope` (samma)
`secrets get-acl`	`secrets get-acl` (samma)
`secrets list`	`secrets list-secrets`
`secrets list-acls`	`secrets list-acls` (samma)
`secrets list-scopes`	`secrets list-scopes` (samma)
`secrets put`	`secrets put-secret`
`secrets put-acl`	`secrets put-acl` (samma)
`secrets write`	`secrets put-secret`
`secrets write-acl`	`secrets put-acl`

`tokens` Kommandon

Äldre kommando	Nytt kommando
`tokens create`	`tokens create` (samma)
`tokens list`	`tokens list` (samma)
`tokens revoke`	`tokens delete`

`unity-catalog` kommandogrupper

unity-catalog <command> i det äldre CLI blir bara <command> i det nya CLI.

Äldre kommandogrupp	Ny kommandogrupp
`unity-catalog catalogs`	`catalogs` (samma men släpp `unity-catalog`)
`unity-catalog external-locations`	`external-locations` (samma men släpp `unity-catalog`)
`unity-catalog lineage`	Inte tillgängligt i det nya CLI. Se API för data härkomst.
`unity-catalog metastores`	`metastores` (samma men släpp `unity-catalog`)
`unity-catalog permissions`	`grants`
`unity-catalog providers`	`providers` (samma men släpp `unity-catalog`)
`unity-catalog recipients`	`recipients` (samma men släpp `unity-catalog`)
`unity-catalog schemas`	`schemas` (samma men släpp `unity-catalog`)
`unity-catalog shares`	`shares` (samma men släpp `unity-catalog`)
`unity-catalog storage-credentials`	`storage-credentials` (samma men släpp `unity-catalog`)
`unity-catalog tables`	`tables` (samma men släpp `unity-catalog`)

`workspace` Kommandon

Äldre kommando	Nytt kommando
`workspace delete`	`workspace delete` (samma)
`workspace export`	`workspace export` (samma)
`workspace export-dir`	`workspace export`
`workspace import`	`workspace import` (samma)
`workspace import-dir`	`workspace import`
`workspace list`	`workspace list` (samma)
`workspace ls`	`workspace list`
`workspace mkdirs`	`workspace mkdirs` (samma)
`workspace rm`	`workspace delete`

Standard- och positionsargument

De flesta av de nya CLI-kommandona har minst ett standardargument som inte har något tillhörande alternativ. Vissa nya CLI-kommandon har två eller flera positionsargument som måste anges i en viss ordning och som inte har tillhörande alternativ. Detta skiljer sig från det äldre CLI, där de flesta kommandon kräver att alternativ anges för alla argument. Det nya CLI-kommandot clusters get tar till exempel ett kluster-ID som standardargument. Det äldre CLI-kommandot clusers get kräver dock att du anger ett --cluster-id alternativ tillsammans med kluster-ID:t. Till exempel:

För det äldre CLI:

# 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

För det nya CLI:

# 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

Som ett annat exempel tar det nya CLI-kommandot grants get två standardargument: den skyddsbara typen följt av det fullständiga namnet på skyddsbara filen. Det äldre CLI-kommandot unity-catalog permissions get kräver dock att du anger ett --<securable-type> alternativ tillsammans med det fullständiga namnet på skyddsbara objektet. Till exempel:

För det äldre CLI:

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

För det nya CLI:

# 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

Felsökningsläge

Det äldre CLI ger ett --debug alternativ för att visa fullständig stackspårning vid fel. För det nya CLI känns inte alternativet --debug igen. Använd i stället följande alternativ:

Använd --log-file <path> för att skriva logginformation till filen som anges i <path>. Om det här alternativet inte anges matas logginformationen ut till stderr. Ange --log-file utan att --log-level även ange resultat i ingen logginformation som skrivs till filen.
Använd --log-format <type> för att ange formatet för den information som loggas. <type> kan vara text (standardvärdet, om det inte anges) eller json.
Använd --log-level <format> för att ange den informationsnivå som loggas. Tillåtna värden är disabled (standardvärdet, om det inte anges), trace, , debuginfo, warnoch error.

För det äldre CLI visar följande exempel den fullständiga stackspårningen vid fel:

databricks fs ls / --debug

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

För det nya CLI loggar följande exempel den fullständiga stackspårningen till en fil med namnet new-cli-errors.log i den aktuella arbetskatalogen. Stackspårningen skrivs till filen i JSON-format:

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.)

Vanliga frågor

Det här avsnittet innehåller vanliga frågor om att migrera från det äldre till det nya CLI.

Vad händer med det äldre CLI?

Det äldre CLI är fortfarande tillgängligt men tar inte emot några icke-kritiska uppdateringar. Den äldre CLI-dokumentationen återspeglar detta. Databricks rekommenderar att användarna migrerar till det nya CLI så snart som möjligt.

Det äldre CLI har alltid varit i ett experimentellt tillstånd med en ansvarsfriskrivning om att Databricks inte planerar något nytt funktionsarbete för det äldre CLI, och det äldre CLI stöds inte via Databricks-stödkanaler.

När kommer det äldre CLI att bli inaktuellt?

Databricks har inte fastställt något datum eller någon tidslinje för inaktuellt äldre CLI. Databricks rekommenderar dock att användarna migrerar till det nya CLI så snart som möjligt.

När kommer det nya CLI att släppas som allmänt tillgängligt ??

Ett lanseringsdatum eller en tidslinje för att släppa det nya CLI som GA har inte upprättats. Detta beror på feedback som Databricks tar emot från användare under den offentliga förhandsversionen.

Vilka är de viktigaste skillnaderna mellan äldre och nya CLIs?

Det äldre CLI släpptes som ett Python-paket. Det nya CLI släpps som en fristående körbar fil och behöver inga körningsberoenden installerade.
Det nya CLI:et har fullständig täckning av Databricks REST-API:er. Det äldre CLI:et gör det inte.
Det nya CLI är tillgängligt som en offentlig förhandsversion. Det äldre CLI förblir i ett experimentellt tillstånd.

Har det nya CLI fullständig funktionsparitet med det äldre CLI?

Det nya CLI:et har täckning för nästan alla kommandon från det äldre CLI. Särskilt frånvarande från det nya CLI är stacks dock kommandogruppen i det äldre CLI. Dessutom har några äldre CLI-kommandogrupper som unity-catalog och runs omstrukturerats till nya kommandogrupper i det nya CLI. Information om migrering finns i informationen som angavs tidigare i den här artikeln.

Hur gör jag för att migrera från det äldre till det nya CLI?

Information om migrering finns i informationen som angavs tidigare i den här artikeln. Observera att det nya CLI inte är en drop-in-ersättning för det äldre CLI och kräver en viss konfiguration för att gå från det äldre till det nya CLI.

Kan installationer av äldre och nya CLIs finnas på samma dator?

Ja. Installationer av äldre och nya CLIs kan finnas på samma dator, men de måste finnas i olika kataloger. Eftersom båda körbara objekten heter databricksmåste du styra vilken körbar fil som körs som standard genom att konfigurera datorns PATH. Om du vill köra det nya CLI men på något sätt av misstag kör det äldre CLI:et i stället kör det äldre CLI som standard det nya CLI:et med samma argument och visar följande varningsmeddelande:

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>

Som du ser i föregående varningsmeddelande kan du ange DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION miljövariabeln till för att 1 inaktivera det här beteendet och köra det äldre CLI:et i stället.

Få hjälp

Information om hur du migrerar från det äldre CLI till det nya CLI finns i följande resurser: