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:

• Legacy Databricks CLI voor de oude 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 u pip (of pip3, afhankelijk van uw versie van Python) om de opdracht uninstall uit te voeren, als volgt:

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 ervoor zorgen dat u alle Python virtuele omgevingen, conda omgevingen of vergelijkbare omgevingen afsluit.

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 het besturingssysteem bijwerken PATH 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 PATH het 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 aan elke aanroep van de CLI toe te voegen. 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 naar de installatie die u als eerste wilt gebruiken in uw PATH wilt plaatsen, voert u de volgende opdracht uit en vervangt u /usr/local/bin door 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 juist is ingesteld voor de huidige terminalsessie, voert u databricks uit, gevolgd door -v en controleert u het versienummer:

   databricks -v
   

5. Als u de PATH op deze manier 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 uw 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 sectie gebruikersvariabelen voor <username>.

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 dat u zojuist hebt toegevoegd naar het begin van de lijst te verplaatsen.

11. Klik op OK.

12. Als u wilt controleren of de PATH juist is ingesteld, opent u een nieuwe opdrachtprompt, voert u databricks uit gevolgd door -ven controleert u het versienummer:

    databricks -v
    

Aanvullende verificatietypen gebruiken

De verouderde CLI en de nieuwe CLI ondersteunen beide Azure Databricks persoonlijke toegangstokenverificatie. Databricks raadt u echter aan andere Azure Databricks verificatietypen te gebruiken, indien mogelijk, die alleen door de nieuwe CLI worden ondersteund.

Als u Azure Databricks persoonlijke toegangstokenverificatie 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.

De nieuwe CLI ondersteunt naast Azure Databricks persoonlijke toegangstokens Microsoft Entra ID tokens. Deze extra tokens zijn veiliger omdat ze doorgaans over één uur verlopen, terwijl Azure Databricks persoonlijke toegangstokens van één dag tot onbepaalde tijd geldig kunnen 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 Azure Databricks persoonlijke toegangstokens een handmatig proces is of moeilijk te automatiseren kan zijn.

Zie Verificatie voor de Databricks CLI voor meer informatie.

Opdrachtgroepen 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

configure Opties

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.

groups Opdrachten

pipelines Opdrachten

runs Opdrachten

secrets Opdrachten

tokens Opdrachten

unity-catalog opdrachtgroepen

unity-catalog <command> in de verouderde CLI wordt alleen <command> in de nieuwe CLI.

workspace Opdrachten

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 clusters 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 --log-level te specificeren resulteert 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, warnen error.

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 stacktrace wordt naar het bestand geschreven in JSON-formaat.

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 doet dat 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 omgevingsvariabele DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION instellen op 1 om dit gedrag uit te schakelen en in plaats daarvan de verouderde CLI uit te voeren.

Hulp krijgen

Zie de volgende bronnen voor hulp bij het migreren van de verouderde CLI naar de nieuwe CLI:

• Helpcentrum voor Databricks