Databricks CLI-migratie
In dit artikel wordt beschreven hoe u migreert van Databricks CLI versie 0.18 of lager naar Databricks CLI versie 0.205 of hoger. Databricks CLI-versies 0.205 en hoger bevinden zich in openbare preview.
Ter beknoptheid verwijst dit artikel naar Databricks CLI-versies 0.18 en lager als de verouderde CLI en Databricks CLI-versies 0.205 en hoger als de 'nieuwe' CLI.
Zie voor meer informatie over de verouderde en nieuwe CDI's:
- Databricks CLI (verouderd) voor de verouderde CLI.
- Wat is de Databricks CLI? voor de nieuwe CLI.
De verouderde CLI verwijderen
Als u de verouderde CLI hebt geïnstalleerd en u deze wilt verwijderen, gebruikt pip u deze (of pip3, afhankelijk van uw versie van Python) om de uninstall opdracht als volgt uit te voeren:
pip uninstall databricks-cli
De nieuwe CLI installeren
Uw CLI-installatie controleren
Als u niet zeker weet of u de nieuwe CLI gebruikt, volgt u de instructies in deze sectie om indien nodig te controleren en aan te passen. Voordat u deze instructies volgt, moet u alle virtuele Python-omgevingen, conda omgevingen of vergelijkbare omgevingen afsluiten.
Voer de volgende opdracht uit om de versie van de standaardinstallatie van de CLI te controleren:
databricks -v
Als het versienummer niet is wat u verwacht, voert u een van de volgende handelingen uit:
- Als u slechts één versie van de CLI wilt gebruiken: verwijder alle vorige versie van de CLI die u niet meer wilt gebruiken. Mogelijk moet u de bedrijfssytems
PATHbijwerken, zodat het pad naar de resterende versie van de CLI die u wilt gebruiken, wordt vermeld. - Als u meerdere versies van de CLI wilt blijven gebruiken: het volledige pad vooraf laten gaan naar de versie van de CLI die u wilt gebruiken voor elke aanroep naar de CLI.
- Als u meerdere versies van de CLI wilt blijven gebruiken, maar u niet het volledige pad wilt behouden naar de versie van de CLI die u het vaakst gebruikt: zorg ervoor dat het volledige pad naar die versie eerst wordt vermeld in de versie van
PATHuw besturingssysteem. Houd er rekening mee dat u nog steeds het volledige pad naar versies van de CLI moet voorbereiden die niet eerst worden vermeld in het besturingssysteemPATH.
Ga als volgt te werk om de onderdelen van PATHuw besturingssysteem bij te werken:
MacOS of Linux
Vermeld de paden waar
databricksis geïnstalleerd door een van de volgende opdrachten uit te voeren:which -a databricks # Or: where databricksHaal het pad op naar de installatie die u wilt gebruiken zonder het volledige pad naar elke aanroep naar de CLI toe te passen. Als u niet zeker weet welk pad dit is, voert u het volledige pad naar elke locatie uit, gevolgd door
-v, bijvoorbeeld:/usr/local/bin/databricks -vAls u het pad wilt plaatsen naar de installatie die u eerst wilt gebruiken in uw
PATH, voert u de volgende opdracht uit en vervangt/usr/local/binu het pad dat u wilt gebruiken. Voeg niet toedatabricksaan het einde van dit pad. Voorbeeld:export PATH="/usr/local/bin:$PATH"Als u wilt controleren of de
PATHversie juist is ingesteld voor de huidige terminalsessie, voert u deze uitdatabricksen-vcontroleert u het versienummer:databricks -vAls u deze
PATHoptie wilt instellen telkens wanneer u de terminal opnieuw start, voegt u de opdracht van stap 3 toe aan uw shell-initialisatiebestand. Voor Zshell bevindt dit bestand zich meestal op~/.zshrc. Voor Bash bevindt dit bestand zich meestal op~/.bashrc. Zie de documentatie van uw shellprovider voor andere shells.Nadat u het shell-initialisatiebestand hebt bijgewerkt, moet u de terminal opnieuw starten om de bijgewerkte
PATHwaarde toe te passen.
Windows
Klik met de rechtermuisknop op de installatie van
databricksdie u wilt gebruiken zonder het volledige pad naar elke aanroep naar de CLI toe te passen.Klik op Bestandslocatie openen.
Let op het pad naar
databricks, bijvoorbeeldC:\Windows.Zoek in het menu Start naar Omgevingsvariabelen.
Klik op Omgevingsvariabelen bewerken voor uw account.
Selecteer de padvariabele in de gebruikersvariabelen voor
<username>de sectie.Klik op Bewerken.
Klik op Nieuw.
Voer het pad in dat u wilt toevoegen, zonder
databricks.exe(zoalsC:\Windows).Gebruik de knop Omhoog verplaatsen om het pad te verplaatsen dat u zojuist hebt toegevoegd aan het begin van de lijst.
Klik op OK.
Als u wilt controleren of de
PATHset correct is ingesteld, opent u een nieuwe opdrachtprompt, voert u de opdracht uitdatabricksgevolgd door-ven controleert u het versienummer:databricks -v
Aanvullende verificatietypen gebruiken
De verouderde CLI en de nieuwe CLI bieden beide ondersteuning voor verificatie van persoonlijke toegangstokens van Azure Databricks. Databricks raadt u echter aan andere Azure Databricks-verificatietypen te gebruiken, indien mogelijk, die alleen door de nieuwe CLI worden ondersteund.
Als u persoonlijke toegangstokenverificatie van Azure Databricks moet gebruiken, raadt Databricks u aan om er een te gebruiken die is gekoppeld aan een service-principal in plaats van een Azure Databricks-account of werkruimtegebruiker. Zie Service-principals beheren.
De nieuwe CLI biedt ondersteuning voor Microsoft Entra ID-tokens, naast persoonlijke toegangstokens van Azure Databricks. Deze extra tokens zijn veiliger omdat ze doorgaans over één uur verlopen, terwijl persoonlijke toegangstokens van Azure Databricks van één dag tot onbepaalde tijd geldig zijn. Dit is vooral belangrijk als een token per ongeluk wordt ingecheckt in versiebeheersystemen die toegankelijk zijn voor anderen. Bovendien kan de nieuwe CLI deze extra tokens automatisch vernieuwen wanneer ze verlopen, terwijl het vernieuwen van persoonlijke toegangstokens van Azure Databricks een handmatig proces is of moeilijk te automatiseren kan zijn.
Zie Verificatie voor de Databricks CLI voor meer informatie.
Opdrachtgroep- en opdrachtvergelijkingen
De volgende tabel bevat de verouderde CLI-opdrachtgroepen en de bijbehorende nieuwe CLI-opdrachtgroep-equivalenten. Als er aanzienlijke verschillen bestaan tussen CDI's, bevatten aanvullende tabellen verouderde CLI-opdrachten of -opties en hun nieuwe CLI-opdracht- of optie-equivalenten.
Opdrachtgroepen
| Verouderde opdrachtgroep | Nieuwe opdrachtgroep |
|---|---|
cluster-policies |
cluster-policies. Alle opdrachtnamen zijn hetzelfde. |
clusters |
clusters. Alle opdrachtnamen zijn hetzelfde. |
configure |
configure. Zie configuratieopties. |
fs |
fs. Zie fs-opdrachten. |
groups |
groups. Zie groepsopdrachten. |
instance-pools |
instance-pools. Alle opdrachtnamen zijn hetzelfde. |
jobs |
jobs. Alle opdrachtnamen zijn hetzelfde. |
libraries |
libraries. Alle opdrachtnamen zijn hetzelfde, met uitzondering van list. De list opdracht is niet meer beschikbaar. Gebruik in plaats daarvan de all-cluster-statuses of cluster-status opdrachten. |
pipelines |
pipelines. Zie opdrachten voor pijplijnen. |
repos |
repos. Alle opdrachtnamen zijn hetzelfde. |
runs |
jobs. Zie opdrachten voor uitvoeringen. |
secrets |
secrets. Zie geheimenopdrachten. |
stack |
Niet beschikbaar in de nieuwe CLI. Databricks raadt u aan in plaats daarvan de Databricks Terraform-provider te gebruiken. |
tokens |
tokens. Zie tokens-opdrachten. |
unity-catalog |
Verschillend. Zie unity-catalog-opdrachtgroepen. |
workspace |
workspace. Zie werkruimteopdrachten. |
configure Opties
| Verouderde optie | Nieuwe optie |
|---|---|
-o |
De verouderde CLI gebruikt -o voor OAuth-verificatie. De nieuwe CLI-bestemming -o om op te geven of de CLI-uitvoer een tekst- of JSON-indeling heeft. Niet van toepassing op Azure Databricks. |
--oauth |
Niet van toepassing op Azure Databricks. |
-s of --scope |
Niet van toepassing op Azure Databricks. |
-t of --token |
-t of --token (hetzelfde) |
-f of --token-file |
Niet beschikbaar in de nieuwe CLI. |
--host |
--host (zelfde) |
--aad-token |
Gebruik --host en geef een Microsoft Entra ID-token op wanneer hierom wordt gevraagd in plaats van een persoonlijk toegangstoken van Azure Databricks. |
--insecure |
Niet beschikbaar in de nieuwe CLI. |
--jobs-api-version |
Niet beschikbaar in de nieuwe CLI. De nieuwe CLI maakt alleen gebruik van de Taken-API 2.1. Als u de verouderde Taken-API 2.0 wilt aanroepen, gebruikt u de verouderde CLI en raadpleegt u jobs CLI (verouderd). |
--debug |
Zie de foutopsporingsmodus voor foutopsporing en logboekregistratie in de nieuwe CLI. |
--profile |
--profile (zelfde) of -p |
-h of --help |
-h of --help (hetzelfde) |
fs Opdrachten
Alle fs opdrachten in de verouderde CLI zijn hetzelfde in de nieuwe CLI, behalve fs mv waarvoor niet beschikbaar is in de nieuwe CLI.
| Verouderde opdracht | Nieuwe opdracht |
|---|---|
fs cat |
fs cat (zelfde) |
fs cp |
fs cp (zelfde) |
fs ls |
fs ls (zelfde) |
fs mkdirs |
fs mkdir |
fs mv |
Niet beschikbaar in de nieuwe CLI. |
fs rm |
fs rm (zelfde) |
groups Opdrachten
| Verouderde opdracht | Nieuwe opdracht |
|---|---|
groups add-member |
groups patch |
groups create |
groups create (zelfde) |
groups delete |
groups delete (zelfde) |
groups list |
groups list (zelfde) |
groups list-members |
groups list |
groups list-parents |
groups list |
groups remove-member |
groups patch |
pipelines Opdrachten
| Verouderde opdracht | Nieuwe opdracht |
|---|---|
pipelines create |
pipelines create (zelfde) |
pipelines delete |
pipelines delete (zelfde) |
pipelines deploy |
pipelines create |
pipelines edit |
pipelines update |
pipelines get |
pipelines get (zelfde) |
pipelines list |
pipelines list-pipeline-eventsof pipelines list-pipelinespipelines list-updates |
pipelines reset |
pipelines reset (zelfde) |
pipelines start |
pipelines start update |
pipelines stop |
pipelines stop (zelfde) |
pipelines update |
pipelines update (zelfde) |
runs Opdrachten
| Verouderde opdracht | Nieuwe opdracht |
|---|---|
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 Opdrachten
| Verouderde opdracht | Nieuwe opdracht |
|---|---|
secrets create-scope |
secrets create-scope (zelfde) |
secrets delete |
secrets delete-secret |
secrets delete-acl |
secrets delete-acl (zelfde) |
secrets delete-scope |
secrets delete-scope (zelfde) |
secrets get-acl |
secrets get-acl (zelfde) |
secrets list |
secrets list-secrets |
secrets list-acls |
secrets list-acls (zelfde) |
secrets list-scopes |
secrets list-scopes (zelfde) |
secrets put |
secrets put-secret |
secrets put-acl |
secrets put-acl (zelfde) |
secrets write |
secrets put-secret |
secrets write-acl |
secrets put-acl |
tokens Opdrachten
| Verouderde opdracht | Nieuwe opdracht |
|---|---|
tokens create |
tokens create (zelfde) |
tokens list |
tokens list (zelfde) |
tokens revoke |
tokens delete |
unity-catalog opdrachtgroepen
unity-catalog <command> in de verouderde CLI wordt alleen <command> in de nieuwe CLI.
| Verouderde opdrachtgroep | Nieuwe opdrachtgroep |
|---|---|
unity-catalog catalogs |
catalogs (hetzelfde maar neerzetten unity-catalog) |
unity-catalog external-locations |
external-locations (hetzelfde maar neerzetten unity-catalog) |
unity-catalog lineage |
Niet beschikbaar in de nieuwe CLI. Zie Herkomst ophalen met behulp van de REST API voor gegevensherkomst. |
unity-catalog metastores |
metastores (hetzelfde maar neerzetten unity-catalog) |
unity-catalog permissions |
grants |
unity-catalog providers |
providers (hetzelfde maar neerzetten unity-catalog) |
unity-catalog recipients |
recipients (hetzelfde maar neerzetten unity-catalog) |
unity-catalog schemas |
schemas (hetzelfde maar neerzetten unity-catalog) |
unity-catalog shares |
shares (hetzelfde maar neerzetten unity-catalog) |
unity-catalog storage-credentials |
storage-credentials (hetzelfde maar neerzetten unity-catalog) |
unity-catalog tables |
tables (hetzelfde maar neerzetten unity-catalog) |
workspace Opdrachten
| Verouderde opdracht | Nieuwe opdracht |
|---|---|
workspace delete |
workspace delete (zelfde) |
workspace export |
workspace export (zelfde) |
workspace export-dir |
workspace export |
workspace import |
workspace import (zelfde) |
workspace import-dir |
workspace import |
workspace list |
workspace list (zelfde) |
workspace ls |
workspace list |
workspace mkdirs |
workspace mkdirs (zelfde) |
workspace rm |
workspace delete |
Standaard- en positieargumenten
De meeste nieuwe CLI-opdrachten hebben ten minste één standaardargument dat geen bijbehorende optie heeft. Sommige nieuwe CLI-opdrachten hebben twee of meer positionele argumenten die in een bepaalde volgorde moeten worden opgegeven en die geen bijbehorende opties hebben. Dit verschilt van de verouderde CLI, waarbij voor de meeste opdrachten opties moeten worden opgegeven voor alle argumenten. De opdracht van clusters get de nieuwe CLI gebruikt bijvoorbeeld een cluster-id als standaardargument. Voor de opdracht van clusers get de verouderde CLI moet u echter een --cluster-id optie opgeven, samen met de cluster-id. Voorbeeld:
Voor de verouderde 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
Voor de nieuwe 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
In een ander voorbeeld heeft de opdracht van grants get de nieuwe CLI twee standaardargumenten: het beveiligbare type gevolgd door de volledige naam van de beveiligbare. Voor de opdracht van unity-catalog permissions get de verouderde CLI moet u echter een --<securable-type> optie opgeven, samen met de volledige naam van de beveiligbare. Voorbeeld:
Voor de verouderde CLI:
databricks unity-catalog permissions get --schema main.default
Voor de nieuwe 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
Foutopsporingsmodus
De verouderde CLI biedt een --debug optie voor het weergeven van een volledige stack-trace op fout. Voor de nieuwe CLI wordt de --debug optie niet herkend. Gebruik in plaats daarvan de volgende opties:
- Hiermee
--log-file <path>schrijft u logboekgegevens naar het bestand dat is opgegeven in<path>. Als deze optie niet is opgegeven, wordt logboekinformatie uitgevoerd naar stderr.--log-fileOpgeven zonder ook resultaten op te geven--log-levelin geen logboekgegevens die naar het bestand worden geschreven. - Hiermee
--log-format <type>geeft u de notatie op van de gegevens die zijn vastgelegd.<type>textkan (de standaardinstelling, indien niet opgegeven) ofjson. - Hiermee
--log-level <format>geeft u het gegevensniveau op dat is geregistreerd. Toegestane waarden zijndisabled(de standaardwaarde, indien niet opgegeven),trace,debug,info, enwarnerror.
Voor de verouderde CLI toont het volgende voorbeeld de volledige stack-tracering bij fout:
databricks fs ls / --debug
# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"
Voor de nieuwe CLI registreert het volgende voorbeeld de volledige stacktracering naar een bestand met de naam new-cli-errors.log in de huidige werkmap. De stacktracering wordt naar het bestand geschreven in JSON-indeling:
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.)
Veelgestelde vragen
In deze sectie vindt u veelgestelde vragen over het migreren van de verouderde versie naar de nieuwe CLI.
Wat gebeurt er met de verouderde CLI?
De verouderde CLI is nog steeds beschikbaar, maar ontvangt geen niet-essentiële updates. De verouderde CLI-documentatie weerspiegelt dit. Databricks raadt gebruikers aan zo snel mogelijk naar de nieuwe CLI te migreren.
De verouderde CLI heeft altijd een experimentele status met een disclaimer dat Databricks geen nieuwe functie voor de verouderde CLI plant en de verouderde CLI niet wordt ondersteund via databricks-ondersteuningskanalen.
Wanneer wordt de verouderde CLI afgeschaft?
De verouderde CLI heeft altijd een experimentele status met een disclaimer dat Databricks geen nieuwe functie voor de verouderde CLI plant en de verouderde CLI niet wordt ondersteund via databricks-ondersteuningskanalen.
Databricks heeft geen datum of tijdlijn ingesteld voor het afschaven van de verouderde CLI. Databricks raadt echter aan dat gebruikers zo snel mogelijk migreren naar de nieuwe CLI.
Wanneer wordt de nieuwe CLI uitgebracht als algemeen beschikbaar (GA)?
Er is geen releasedatum of tijdlijn voor het vrijgeven van de nieuwe CLI, omdat er geen algemene beschikbaarheid is vastgesteld. Dit is afhankelijk van feedback die Databricks ontvangt van gebruikers tijdens de openbare preview.
Wat zijn de belangrijkste verschillen tussen de verouderde en nieuwe CDI's?
- De verouderde CLI is uitgebracht als een Python-pakket. De nieuwe CLI wordt uitgebracht als zelfstandig uitvoerbaar bestand en hoeft geen runtime-afhankelijkheden te worden geïnstalleerd.
- De nieuwe CLI heeft volledige dekking van de Databricks REST API's. De verouderde CLI niet.
- De nieuwe CLI is beschikbaar als openbare preview. De verouderde CLI blijft in een experimentele status.
Heeft de nieuwe CLI volledige functiepariteit met de verouderde CLI?
De nieuwe CLI heeft dekking voor bijna alle opdrachten van de verouderde CLI. Met name afwezig van de nieuwe CLI is echter de stacks opdrachtgroep in de verouderde CLI. Daarnaast zijn een aantal verouderde CLI-opdrachtgroepen, zoals unity-catalog en runs zijn geherstructureerd in nieuwe opdrachtgroepen in de nieuwe CLI. Zie de informatie die eerder in dit artikel is opgegeven voor migratierichtlijnen.
Hoe kan ik migreren van de verouderde versie naar de nieuwe CLI?
Zie de informatie die eerder in dit artikel is opgegeven voor migratierichtlijnen. Houd er rekening mee dat de nieuwe CLI geen vervanging is voor de verouderde CLI en dat er enige installatie moet worden uitgevoerd van de verouderde naar de nieuwe CLI.
Kunnen installaties van de verouderde en nieuwe CURI's op dezelfde computer aanwezig zijn?
Ja. Installaties van de verouderde en nieuwe CURI's kunnen op dezelfde computer aanwezig zijn, maar ze moeten zich in verschillende mappen bevinden. Omdat de uitvoerbare bestanden beide een naam databrickshebben, moet u bepalen welk uitvoerbaar bestand standaard wordt uitgevoerd door de computer te PATHconfigureren. Als u de nieuwe CLI wilt uitvoeren, maar op een of andere manier per ongeluk de verouderde CLI wilt uitvoeren, wordt de nieuwe CLI standaard uitgevoerd met dezelfde argumenten en wordt het volgende waarschuwingsbericht weergegeven:
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>
Zoals wordt weergegeven in het voorgaande waarschuwingsbericht, kunt u de DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION omgevingsvariabele instellen om dit gedrag uit te 1 schakelen en in plaats daarvan de verouderde CLI uit te voeren.
Hulp vragen
Zie de volgende bronnen voor hulp bij het migreren van de verouderde CLI naar de nieuwe CLI: