Installationsdokumentation & för Databricks CLI

Databricks kommandoradsgränssnitt (CLI) är ett lättanvänt gränssnitt till Azure Databricks-plattformen. Projektet med öppen källkod finns på GitHub. CLI bygger på Databricks REST API och är indelat i kommandogrupper baserat på primära slutpunkter.

Du kan använda Databricks CLI för att göra saker som:

  • Etablera beräkningsresurser i Azure Databricks-arbetsytor.
  • Kör databearbetnings- och dataanalysuppgifter.
  • Lista, importera och exportera anteckningsböcker och mappar på arbetsytor.

Viktigt

Denna CLI är under aktiv utveckling och släpps som en experimentell klient. Det innebär att gränssnitt fortfarande kan komma att ändras.

Konfigurera CLI

Det här avsnittet beskriver krav för CLI och hur du installerar och konfigurerar din miljö för att köra CLI.

Krav

  • Python 3 – 3.6 och senare

  • Python 2 – 2.7.9 och senare

    Viktigt

    På macOS implementerar inte standardinstallationen av Python 2 TLSv1_2-protokollet och om du kör CLI med den här Python-installationen resulterar det i felet: AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'. Använd Homebrew för att installera en version av Python som har ssl.PROTOCOL_TLSv1_2.

Begränsningar

Det går inte att använda Databricks CLI med brandväggsaktiverade lagringscontainrar. Databricks rekommenderar att du använder Databricks Connect eller az storage.

Installera CLI

Kör pip install databricks-cli med lämplig version av pip för Python-installationen:

pip install databricks-cli

Uppdatera CLI

Kör pip install databricks-cli --upgrade med lämplig version av pip för Python-installationen:

pip install databricks-cli --upgrade

Om du vill visa en lista över den version av CLI som är installerad kör databricks --version du (eller databricks -v):

databricks --version

# Or...

databricks -v

Konfigurera autentisering

Anteckning

När du autentiserar med automatiserade verktyg, system, skript och appar rekommenderar Databricks att du använder åtkomsttoken som tillhör tjänstens huvudnamn i stället för arbetsyteanvändare. Information om hur du skapar åtkomsttoken för tjänstens huvudnamn finns i Hantera åtkomsttoken för tjänstens huvudnamn.

Innan du kan köra CLI-kommandon måste du konfigurera autentisering. För att autentisera till CLI kan du använda en personlig Databricks-åtkomsttoken eller en Azure Active Directory-token (Azure AD).

Anteckning

Som standard skapar följande kommandon en konfigurationsprofilfil med namnet .databrickscfg med en konfigurationsprofil med namnet DEFAULT i den nya filen. .databrickscfg Om filen redan finns skrivs den filens konfigurationsprofil DEFAULT över med nya data. Information om hur du skapar en konfigurationsprofil med ett annat namn finns i Anslutningsprofiler.

Konfigurera autentisering med en Azure AD-token

Om du vill konfigurera CLI med hjälp av en Azure AD-token genererar du Azure AD-token och lagrar den i miljövariabeln DATABRICKS_AAD_TOKEN.

Kör följande kommando:

databricks configure --aad-token

Kommandot utfärdar prompten:

Databricks Host (should begin with https://):

Ange webbadressen per arbetsyta med formatet https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Information om hur du hämtar url:en per arbetsyta finns i URL per arbetsyta.

När du har slutfört prompten lagras dina autentiseringsuppgifter i filen ~/.databrickscfg på Unix, Linux eller macOS eller %USERPROFILE%\.databrickscfg i Windows. Filen innehåller en standardprofilpost:

[DEFAULT]
host = <workspace-URL>
token = <Azure-AD-token>

Konfigurera autentisering med hjälp av en personlig Databricks-åtkomsttoken

Kör följande kommando för att konfigurera CLI att använda en personlig åtkomsttoken:

databricks configure --token

Kommandot börjar med att utfärda prompten:

Databricks Host (should begin with https://):

Ange webbadressen per arbetsyta med formatet https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Information om hur du hämtar url:en per arbetsyta finns i URL per arbetsyta.

Kommandot fortsätter genom att utfärda prompten för att ange din personliga åtkomsttoken:

Token:

När du har slutfört prompterna lagras dina autentiseringsuppgifter i filen ~/.databrickscfg på Unix, Linux eller macOS eller %USERPROFILE%\.databrickscfg i Windows. Filen innehåller en standardprofilpost:

[DEFAULT]
host = <workspace-URL>
token = <personal-access-token>

För CLI 0.8.1 och senare kan du ändra sökvägen till den här filen genom att ange miljövariabeln DATABRICKS_CONFIG_FILE.

Unix, linux, macos

export DATABRICKS_CONFIG_FILE=<path-to-file>

Windows

setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

Viktigt

Från och med CLI 0.17.2 fungerar inte CLI med en .netrc-fil. Du kan ha en .netrc fil i din miljö för andra ändamål, men CLI använder inte den .netrc filen.

CLI 0.8.0 och senare stöder följande Azure Databricks-miljövariabler:

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN

En miljövariabelinställning har företräde framför inställningen i konfigurationsfilen.

Testa autentiseringskonfigurationen

Om du vill kontrollera om du konfigurerar autentisering på rätt sätt kan du köra ett kommando som följande och ersätta <someone@example.com> med ditt användarnamn för Azure Databricks-arbetsytan:

databricks workspace ls /Users/<someone@example.com>

Om det lyckas visar det här kommandot objekten i den angivna arbetsytesökvägen.

Anslutningsprofiler

Databricks CLI-konfiguration stöder flera anslutningsprofiler. Samma installation av Databricks CLI kan användas för att skapa API-anrop på flera Azure Databricks-arbetsytor.

Om du vill lägga till en anslutningsprofil anger du ett unikt namn för profilen:

databricks configure [--token | --aad-token] --profile <profile-name>

Filen .databrickscfg innehåller en corresonding-profilpost:

[<profile-name>]
host = <workspace-URL>
token = <token>

För att använda anslutningsprofilen:

databricks <group> <command> --profile <profile-name>

Om --profile <profile-name> inte anges används standardprofilen. Om en standardprofil inte hittas uppmanas du att konfigurera CLI med en standardprofil.

Testa dina anslutningsprofiler

Om du vill kontrollera om du konfigurerar anslutningsprofilerna korrekt kan du köra ett kommando som följande. Ersätt <someone@example.com> med användarnamnet för din Azure Databricks-arbetsyta och <DEFAULT> med ett av anslutningsprofilnamnen:

databricks workspace ls /Users/<someone@example.com> --profile <DEFAULT>

Om det här kommandot lyckas visas objekten i den angivna arbetsytesökvägen i arbetsytan för den angivna anslutningsprofilen. Kör det här kommandot för varje anslutningsprofil som du vill testa.

Alias för kommandogrupper

Ibland kan det vara opraktiskt att sätta ett prefix på varje CLI-anrop i form av namnet på en kommandogrupp, som databricks workspace ls. Om du vill göra CLI:n enklare att använda kan du skapa alias för kommandogrupper för kortare kommandon. Om du till exempel vill förkorta databricks workspace ls till dw ls i gränssnittet Bourne igen kan du lägga till alias dw="databricks workspace" i lämplig bash-profil. Den här filen finns normalt på ~/.bash_profile.

Tips

Azure Databricks har redan alias databricks fs till dbfsoch databricks fs lsdbfs ls är likvärdiga.

Använda CLI

Det här avsnittet visar hur du kan få hjälp med CLI, parsa CLI-utdata och anropa kommandon i varje kommandogrupp.

Visa hjälp för CLI-kommandogrupper

Du listar underkommandona för alla kommandogrupper genom att köra databricks <group> --help (eller databricks <group> -h). Du kan till exempel visa en lista över DBFS CLI-underkommandon genom att köra databricks fs -h:

databricks fs -h

Visa underkommandohjälp för CLI

Du listar hjälpen för en underkommando genom att köra databricks <group> <subcommand> --help (eller databricks <group> <subcommand> -h). Du kan till exempel visa hjälpen för underkommandot för DBFS-kopieringsfiler genom att köra databricks fs cp -h:

databricks fs cp -h

Använda jq för att parsa CLI-utdata

Vissa Databricks CLI-kommandon matar ut JSON-svaret från API-slutpunkten. Ibland kan det vara användbart att parsa ut delar av JSON för att ansluta till andra kommandon. Om du till exempel vill kopiera en jobbdefinition måste du ta fältet i settings ett databricks jobs get kommando och använda det som ett argument till databricks jobs create kommandot. I de här fallen rekommenderar vi att du använder jq-verktyget.

Följande kommando skriver till exempel ut inställningarna för jobbet med ID:t 233.

databricks jobs list --output JSON | jq '.jobs[] | select(.job_id == 233) | .settings'
{
  "name": "Quickstart",
  "new_cluster": {
    "spark_version": "7.5.x-scala2.12",
    "spark_env_vars": {
      "PYSPARK_PYTHON": "/databricks/python3/bin/python3"
    },
    "num_workers": 8,
    ...
  },
  "email_notifications": {},
  "timeout_seconds": 0,
  "notebook_task": {
    "notebook_path": "/Quickstart"
  },
  "max_concurrent_runs": 1
}

Som ett annat exempel skriver följande kommando ut namnen och ID:na för alla tillgängliga kluster på arbetsytan:

databricks clusters list --output JSON | jq '[ .clusters[] | { name: .cluster_name, id: .cluster_id } ]'
[
  {
    "name": "My Cluster 1",
    "id": "1234-567890-grip123"
  },
  {
    "name": "My Cluster 2",
    "id": "2345-678901-patch234"
  }
]

Du kan till exempel installera jq på macOS med Homebrew med brew install jq eller i Windows med chocolatey med choco install jq. Mer information om jq finns i jq-användarhandboken.

JSON-strängparametrar

Strängparametrar hanteras på olika sätt beroende på operativsystemet:

Unix, linux, macos

Du måste omge JSON-strängparametrar med enkla citattecken. Exempel:

databricks jobs run-now --job-id 9 --jar-params '["20180505", "alantest"]'

Windows

Du måste omge JSON-strängparametrar med dubbla citattecken, och citattecknen i strängen måste föregås av \. Exempel:

databricks jobs run-now --job-id 9 --jar-params "[\"20180505\", \"alantest\"]"

Felsökning

Följande avsnitt innehåller tips för felsökning av vanliga problem med Databricks CLI.

Det går inte att använda EOF med databricks configure

För Databricks CLI 0.12.0 och senare fungerar inte att använda filslutsekvensen (EOF) i ett skript för att skicka parametrar till databricks configure kommandot. Följande skript gör till exempel att Databricks CLI ignorerar parametrarna och inget felmeddelande genereras:

# Do not do this.
databricksUrl=<per-workspace-url>
databricksToken=<personal-access-token-or-Azure-AD-token>

databricks configure --token << EOF
$databricksUrl
$databricksToken
EOF

Åtgärda problemet genom att göra något av följande:

  • Använd något av de andra programmässiga konfigurationsalternativen enligt beskrivningen i Konfigurera autentisering.
  • Lägg till host värdena och token i filen manuellt enligt beskrivningen .databrickscfg i Konfigurera autentisering.
  • Nedgradera installationen av Databricks CLI till 0.11.0 eller senare och kör skriptet igen.

CLI-kommandon