Delen via

Databricks CLI-migratie

  • Artikel

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:

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

Zie De Databricks CLI installeren of bijwerken voor meer informatie over het installeren van de nieuwe CLI.

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 PATH bijwerken, 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 besturingssysteem PATH.

Ga als volgt te werk om de onderdelen van PATHuw besturingssysteem bij te werken:

MacOS of Linux

  1. Vermeld de paden waar databricks is geïnstalleerd door een van de volgende opdrachten uit te voeren:

    which -a databricks

# Or:
where databricks

  2. Haal 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 -v

  3. Als 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/bin u het pad dat u wilt gebruiken. Voeg niet toe databricks aan het einde van dit pad. Voorbeeld:

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

  4. Als u wilt controleren of de PATH versie juist is ingesteld voor de huidige terminalsessie, voert u deze uit databricks en -v controleert u het versienummer:

    databricks -v

  5. Als u deze PATH optie 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.

  6. Nadat u het shell-initialisatiebestand hebt bijgewerkt, moet u de terminal opnieuw starten om de bijgewerkte PATH waarde toe te passen.

Windows

  1. Klik met de rechtermuisknop op de installatie van databricks die u wilt gebruiken zonder het volledige pad naar elke aanroep naar de CLI toe te passen.

  2. Klik op Bestandslocatie openen.

  3. Let op het pad naar databricks, bijvoorbeeld C:\Windows.

  4. Zoek in het menu Start naar Omgevingsvariabelen.

  5. Klik op Omgevingsvariabelen bewerken voor uw account.

  6. Selecteer de padvariabele in de gebruikersvariabelen voor <username> de sectie.

  7. Klik op Bewerken.

  8. Klik op Nieuw.

  9. Voer het pad in dat u wilt toevoegen, zonder databricks.exe (zoals C:\Windows).

  10. Gebruik de knop Omhoog verplaatsen om het pad te verplaatsen dat u zojuist hebt toegevoegd aan het begin van de lijst.

  11. Klik op OK.

  12. Als u wilt controleren of de PATH set correct is ingesteld, opent u een nieuwe opdrachtprompt, voert u de opdracht uit databricks gevolgd 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 (voorheen Azure Active Directory) op wanneer u 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-file Opgeven zonder ook resultaten op te geven --log-level in geen logboekgegevens die naar het bestand worden geschreven.
  • Hiermee --log-format <type> geeft u de notatie op van de gegevens die zijn vastgelegd. <type>text kan (de standaardinstelling, indien niet opgegeven) of json.
  • Hiermee --log-level <format> geeft u het gegevensniveau op dat is geregistreerd. Toegestane waarden zijn disabled (de standaardwaarde, indien niet opgegeven), trace, debug, info, en warnerror.

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: