Databricks SDK för Python

Artikel
03/05/2024

I den här artikeln får du lära dig hur du automatiserar åtgärder i Azure Databricks-konton, arbetsytor och relaterade resurser med Databricks SDK för Python. Den här artikeln kompletterar Dokumentationen om Databricks SDK för Python på Read The Docs och kodexemplen i Databricks SDK för Python-lagringsplatsen i GitHub.

Kommentar

Den här funktionen är i Beta och är okej att använda i produktion.

Under betaperioden rekommenderar Databricks att du fäster ett beroende på den specifika delversionen av Databricks SDK för Python som koden är beroende av. Du kan till exempel fästa beroenden i filer som requirements.txt för venv, eller pyproject.toml och poetry.lock för Poesi. Mer information om hur du fäster beroenden finns i Virtual Environments and Packages for , or Installing dependencies for Poetry (Virtuella miljöer och paket för venv, eller Installera beroenden för poesi).

Innan du börjar

Du kan använda Databricks SDK för Python från en Notebook-fil i Azure Databricks eller från din lokala utvecklingsdator.

Om du vill använda Databricks SDK för Python inifrån en Azure Databricks-notebook-fil går du vidare till Använda Databricks SDK för Python från en Azure Databricks-notebook-fil.
Slutför stegen i det här avsnittet om du vill använda Databricks SDK för Python från din lokala utvecklingsdator.

Innan du börjar använda Databricks SDK för Python måste utvecklingsdatorn ha:

Azure Databricks-autentisering har konfigurerats.
Python 3.8 eller senare installerat. För att automatisera Azure Databricks-beräkningsresurser rekommenderar Databricks att du har de större och mindre versionerna av Python installerade som matchar den som är installerad på din Azure Databricks-målberäkningsresurs. Den här artikelns exempel förlitar sig på att automatisera kluster med Databricks Runtime 13.0, som har Python 3.10 installerat. Rätt version finns i Versionsanteckningar för Databricks Runtime och kompatibilitet för ditt klusters Databricks Runtime-version.
Databricks rekommenderar att du skapar och aktiverar en virtuell Python-miljö för varje Python-kodprojekt som du använder med Databricks SDK för Python. Virtuella Python-miljöer hjälper dig att se till att kodprojektet använder kompatibla versioner av Python- och Python-paket (i det här fallet Databricks SDK för Python-paketet). Den här artikeln beskriver hur du använder venv eller potetry för virtuella Python-miljöer.

Skapa en virtuell Python-miljö med `venv`

Kör följande kommando från terminaluppsättningen till rotkatalogen för Python-kodprojektet. Det här kommandot instruerar venv dig att använda Python 3.10 för den virtuella miljön och skapar sedan den virtuella miljöns stödfiler i en dold katalog med namnet .venv i rotkatalogen för Python-kodprojektet.
```
# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv
```
Använd venv för att aktivera den virtuella miljön. Se venv-dokumentationen för rätt kommando att använda, baserat på ditt operativsystem och din terminaltyp. Till exempel på macOS som kör zsh:
```
source ./.venv/bin/activate
```
Du vet att din virtuella miljö aktiveras när den virtuella miljöns namn (till exempel .venv) visas inom parenteser precis före terminalprompten.

Om du vill inaktivera den virtuella miljön när som helst kör du kommandot deactivate.

Du vet att den virtuella miljön inaktiveras när den virtuella miljöns namn inte längre visas inom parenteser precis före terminalprompten.

Gå vidare till Kom igång med Databricks SDK för Python.

Skapa en virtuell miljö med Poesi

Installera Poetry, om du inte redan har gjort det.
Från terminaluppsättningen till rotkatalogen för Python-kodprojektet kör du följande kommando för att instruera poetry dig att initiera Python-kodprojektet för Poetry.
```
poetry init
```
Poesi visar flera uppmaningar som du kan slutföra. Ingen av dessa uppmaningar är specifika för Databricks SDK för Python. Information om dessa frågor finns i init.
När du har slutfört anvisningarna lägger Poetry till en pyproject.toml fil i Python-projektet. Information om filen finns i pyproject.toml filen pyproject.toml.
Kör följande kommando med terminalen fortfarande inställd på rotkatalogen för Python-kodprojektet. Det här kommandot instruerar poetry dig att läsa pyproject.toml filen, installera och lösa beroenden, skapa en poetry.lock fil för att låsa beroendena och slutligen skapa en virtuell miljö.
```
poetry install
```
Från terminaluppsättningen till rotkatalogen för Python-kodprojektet kör du följande kommando för att instruera poetry att aktivera den virtuella miljön och ange gränssnittet.
```
poetry shell
```
Du vet att den virtuella miljön är aktiverad och gränssnittet anges när namnet på den virtuella miljön visas inom parenteser precis före terminalprompten.

Om du vill inaktivera den virtuella miljön och avsluta gränssnittet när som helst kör du kommandot exit.

Du vet att du har avslutat gränssnittet när den virtuella miljöns namn inte längre visas inom parenteser precis före terminalprompten.

Mer information om hur du skapar och hanterar virtuella poesimiljöer finns i Hantera miljöer.

Kom igång med Databricks SDK för Python

I det här avsnittet beskrivs hur du kommer igång med Databricks SDK för Python från din lokala utvecklingsdator. Om du vill använda Databricks SDK för Python inifrån en Azure Databricks-notebook-fil går du vidare till Använda Databricks SDK för Python från en Azure Databricks-notebook-fil.

På utvecklingsdatorn med Azure Databricks-autentisering konfigurerad, Python redan installerat och din virtuella Python-miljö redan aktiverad installerar du paketet databricks-sdk (och dess beroenden) från Python Package Index (PyPI) på följande sätt:

Venv

Använd pip för att installera databricks-sdk paketet. (På vissa system kan du behöva ersätta pip3 med pip, här och i hela.)
```
pip3 install databricks-sdk
```
Poesi
```
poetry add databricks-sdk
```
Information om hur du installerar en specifik version av databricks-sdk paketet när Databricks SDK för Python finns i Beta finns i paketets versionshistorik. Om du till exempel vill installera version 0.1.6:

Venv
```
pip3 install databricks-sdk==0.1.6
```
Poesi
```
poetry add databricks-sdk==0.1.6
```
Dricks

Om du vill uppgradera en befintlig installation av Databricks SDK för Python-paketet till den senaste versionen kör du följande kommando:

Venv
```
pip3 install --upgrade databricks-sdk
```
Poesi
```
poetry add databricks-sdk@latest
```
Om du vill visa Databricks SDK för Python-paketets aktuella Version och andra detaljer kör du följande kommando:

Venv
```
pip3 show databricks-sdk
```
Poesi
```
poetry show databricks-sdk
```
I din virtuella Python-miljö skapar du en Python-kodfil som importerar Databricks SDK för Python. I följande exempel, i en fil med namnet main.py med följande innehåll, visas helt enkelt alla kluster på din Azure Databricks-arbetsyta:
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for c in w.clusters.list():
  print(c.cluster_name)
```
Kör python-kodfilen, förutsatt att en fil med namnet main.py, genom att python köra kommandot:

Venv
```
python3.10 main.py
```
Poesi

Om du är i den virtuella miljöns gränssnitt:
```
python3.10 main.py
```
Om du inte är i den virtuella miljöns gränssnitt:
```
poetry run python3.10 main.py
```
Kommentar

Genom att inte ange några argument i föregående anrop till w = WorkspaceClient()använder Databricks SDK för Python sin standardprocess för att försöka utföra Azure Databricks-autentisering. Information om hur du åsidosätter det här standardbeteendet finns i följande autentiseringsavsnitt .

Autentisera Databricks SDK för Python med ditt Azure Databricks-konto eller din arbetsyta

I det här avsnittet beskrivs hur du autentiserar Databricks SDK för Python från din lokala utvecklingsdator till ditt Azure Databricks-konto eller din arbetsyta. Om du vill autentisera Databricks SDK för Python inifrån en Azure Databricks-notebook-fil går du vidare till Använda Databricks SDK för Python från en Azure Databricks-notebook-fil.

Databricks SDK för Python implementerar Databricks-klientens enhetliga autentiseringsstandard, en konsoliderad och konsekvent arkitektur- och programmeringsmetod för autentisering. Med den här metoden kan du konfigurera och automatisera autentisering med Azure Databricks mer centraliserad och förutsägbar. Det gör att du kan konfigurera Databricks-autentisering en gång och sedan använda den konfigurationen över flera Databricks-verktyg och SDK:er utan ytterligare autentiseringskonfigurationsändringar. Mer information, inklusive fler kompletta kodexempel i Python, finns i Databricks-klientens enhetliga autentisering.

Kommentar

Databricks SDK för Python har ännu inte implementerat Azure-hanterad identitetsautentisering.

Några av de tillgängliga kodningsmönstren för att initiera Databricks-autentisering med Databricks SDK för Python är:

Använd Databricks standardautentisering genom att göra något av följande:
- Skapa eller identifiera en anpassad Databricks-konfigurationsprofil med de obligatoriska fälten för databricks-målautentiseringstypen. Ange DATABRICKS_CONFIG_PROFILE sedan miljövariabeln till namnet på den anpassade konfigurationsprofilen.
- Ange nödvändiga miljövariabler för databricks-målautentiseringstypen.
Instansiera till exempel ett WorkspaceClient objekt med Databricks standardautentisering på följande sätt:
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...
```
Hårdkodning av obligatoriska fält stöds men rekommenderas inte, eftersom det riskerar att exponera känslig information i koden, till exempel personliga åtkomsttoken för Azure Databricks. I följande exempel hårdkodas Värden för Azure Databricks och åtkomsttokenvärden för Databricks-tokenautentisering:
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host  = 'https://...',
  token = '...'
)
# ...
```

Se även Autentisering i Dokumentationen om Databricks SDK för Python.

Använda Databricks SDK för Python från en Azure Databricks-notebook-fil

Du kan anropa Databricks SDK för Python-funktioner från en Azure Databricks-notebook-fil som har ett anslutet Azure Databricks-kluster med Databricks SDK för Python installerat. Databricks SDK för Python är redan installerat på alla Azure Databricks-kluster som använder Databricks Runtime 13.2 eller senare. För Azure Databricks-kluster som använder Databricks Runtime 13.1 och nedan måste du först installera Databricks SDK för Python. Se Steg 1: Installera eller uppgradera Databricks SDK för Python.

Information om hur du ser versionsnumret för Databricks SDK för Python som är installerad som standard för en specifik version av Databricks Runtime finns i avsnittet "Installerade Python-bibliotek" i Viktig information om Databricks Runtime för databricks Runtime-versionen.

Databricks SDK för Python 0.6.0 och senare använder standardautentisering för Azure Databricks Notebook. Standardautentisering för Azure Databricks-notebook-filer förlitar sig på en tillfällig personlig åtkomsttoken för Azure Databricks som Azure Databricks automatiskt genererar i bakgrunden för eget bruk. Azure Databricks tar bort den här temporära token när notebook-filen slutar köras.

Viktigt!

Standardautentisering för Azure Databricks-notebook-filer fungerar endast på klustrets drivrutinsnod och inte på någon av klustrets arbets- eller körnoder.

Databricks Runtime 13.1 och senare stöder standardautentisering med Azure Databricks Notebook med Databricks SDK för Python 0.1.7 eller senare installerat. Databricks Runtime 10.4 LTS och senare stöder standardautentisering med Azure Databricks Notebook med Databricks SDK för Python 0.1.10 eller senare installerat. Databricks rekommenderar dock att du installerar eller uppgraderar till Databricks SDK för Python 0.6.0 eller senare för maximal kompatibilitet med standardautentisering för Azure Databricks Notebook, oavsett Databricks Runtime-version.

Du måste installera eller uppgradera Databricks SDK för Python i Azure Databricks-klustret om du vill anropa API:er på Azure Databricks-kontonivå eller om du vill använda en annan Azure Databricks-autentiseringstyp än standardautentisering för Azure Databricks Notebook enligt följande:

Authentication type	Databricks SDK för Python-versioner
OAuth-autentisering från dator till dator (M2M)	0.18.0 och senare
OAuth-autentisering från användare till dator (U2M)	0.19.0 och senare
Autentisering av tjänstens huvudnamn för Microsoft Entra-ID	Alla versioner
Azure CLI-autentisering	Alla versioner
Autentisering med personlig åtkomsttoken för Databricks	Alla versioner

Azure-autentisering av hanterade identiteter stöds ännu inte.

Azure Databricks-notebook-autentisering fungerar inte med Azure Databricks-konfigurationsprofiler.

Steg 1: Installera eller uppgradera Databricks SDK för Python

Azure Databricks Python-notebook-filer kan använda Databricks SDK för Python precis som andra Python-bibliotek. Om du vill installera eller uppgradera Databricks SDK för Python-biblioteket i det anslutna Azure Databricks-klustret kör du det %pip magiska kommandot från en notebook-cell på följande sätt:
```
%pip install databricks-sdk --upgrade
```
När du har kört det %pip magiska kommandot måste du starta om Python för att göra det installerade eller uppgraderade biblioteket tillgängligt för notebook-filen. Det gör du genom att köra följande kommando från en notebook-cell omedelbart efter cellen med det %pip magiska kommandot:
```
dbutils.library.restartPython()
```
Om du vill visa den installerade versionen av Databricks SDK för Python kör du följande kommando från en notebook-cell:
```
%pip show databricks-sdk | grep -oP '(?<=Version: )\S+'
```

Steg 2: Kör koden

I notebook-cellerna skapar du Python-kod som importerar och anropar sedan Databricks SDK för Python. I följande exempel används standardautentisering för Azure Databricks-notebook-filer för att visa en lista över alla kluster på din Azure Databricks-arbetsyta:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for c in w.clusters.list():
  print(c.cluster_name)

När du kör den här cellen visas en lista över namnen på alla tillgängliga kluster på din Azure Databricks-arbetsyta.

Om du vill använda en annan Azure Databricks-autentiseringstyp kan du läsa autentiseringstyper som stöds i Azure Databricks och klicka på motsvarande länk för ytterligare teknisk information.

Använda Databricks-verktyg

Du kan anropa Databricks Utilities-referens (dbutils) från Databricks SDK för Python-kod som körs på din lokala utvecklingsdator eller inifrån en Azure Databricks-notebook-fil.

Från din lokala utvecklingsdator har Databricks Utilities endast åtkomst till dbutils.fskommandogrupperna , dbutils.secrets, dbutils.widgetsoch dbutils.jobs .
Från en Azure Databricks-notebook-fil som är kopplad till ett Azure Databricks-kluster har Databricks Utilities åtkomst till alla tillgängliga Databricks Utilities-kommandogrupper, inte bara dbutils.fs, dbutils.secretsoch dbutils.widgets. dbutils.notebook Dessutom är kommandogruppen begränsad till två nivåer av kommandon, till exempel dbutils.notebook.run eller dbutils.notebook.exit.

Om du vill anropa Databricks Utilities från din lokala utvecklingsdator eller en Azure Databricks-notebook-fil använder du dbutils i WorkspaceClient. I det här kodexemplet används standardautentisering för Azure Databricks-notebook-filer för att anropa dbutils inom WorkspaceClient för att lista sökvägarna för alla objekt i DBFS-roten på arbetsytan.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
d = w.dbutils.fs.ls('/')

for f in d:
  print(f.path)

Du kan också ringa dbutils direkt. Du är dock begränsad till att endast använda azure Databricks-standardautentisering för notebook-filer. Det här kodexemplet anropar dbutils direkt för att lista alla objekt i DBFS-roten på arbetsytan.

from databricks.sdk.runtime import *

d = dbutils.fs.ls('/')

for f in d:
  print(f.path)

Du kan inte använda dbutils sig själv eller inom WorkspaceClient för att komma åt Unity Catalog-volymer. Använd files i stället inom WorkspaceClient. Det här kodexemplet anropar files inom WorkspaceClient för att skriva ut innehållet i den angivna filen på den angivna volymen.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

resp = w.files.download('/Volumes/main/default/my-volume/sales.csv')
print(str(resp.contents.read(), encoding='utf-8'))

Se även Interaktion med dbutils.

Kodexempel

Följande kodexempel visar hur du använder Databricks SDK för Python för att skapa och ta bort kluster, köra jobb och lista grupper på kontonivå. I de här kodexemplen används standardautentisering för Azure Databricks-notebook-filer. Mer information om standardautentisering för Azure Databricks-notebook-filer finns i Använda Databricks SDK för Python från en Azure Databricks-notebook-fil. Mer information om standardautentisering utanför notebook-filer finns i Autentisera Databricks SDK för Python med ditt Azure Databricks-konto eller din arbetsyta.

Ytterligare kodexempel finns i exemplen i Databricks SDK för Python-lagringsplatsen i GitHub. Se även:

Skapa ett kluster

Det här kodexemplet skapar ett kluster med den angivna Databricks Runtime-versionen och klusternodtypen. Det här klustret har en arbetare och klustret avslutas automatiskt efter 15 minuters inaktivitetstid.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

print("Attempting to create cluster. Please wait...")

c = w.clusters.create_and_wait(
  cluster_name             = 'my-cluster',
  spark_version            = '12.2.x-scala2.12',
  node_type_id             = 'Standard_DS3_v2',
  autotermination_minutes = 15,
  num_workers              = 1
)

print(f"The cluster is now ready at " \
      f"{w.config.host}#setting/clusters/{c.cluster_id}/configuration\n")

Ta bort ett kluster permanent

Det här kodexemplet tar bort klustret permanent med det angivna kluster-ID:t från arbetsytan.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

c_id = input('ID of cluster to delete (for example, 1234-567890-ab123cd4): ')

w.clusters.permanent_delete(cluster_id = c_id)

Skapa ett jobb

Det här kodexemplet skapar ett Azure Databricks-jobb som kör den angivna notebook-filen i det angivna klustret. När koden körs hämtar den den befintliga notebook-filens sökväg, det befintliga kluster-ID:t och relaterade jobbinställningar från användaren i terminalen.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.jobs import Task, NotebookTask, Source

w = WorkspaceClient()

job_name            = input("Some short name for the job (for example, my-job): ")
description         = input("Some short description for the job (for example, My job): ")
existing_cluster_id = input("ID of the existing cluster in the workspace to run the job on (for example, 1234-567890-ab123cd4): ")
notebook_path       = input("Workspace path of the notebook to run (for example, /Users/someone@example.com/my-notebook): ")
task_key            = input("Some key to apply to the job's tasks (for example, my-key): ")

print("Attempting to create the job. Please wait...\n")

j = w.jobs.create(
  name = job_name,
  tasks = [
    Task(
      description = description,
      existing_cluster_id = existing_cluster_id,
      notebook_task = NotebookTask(
        base_parameters = dict(""),
        notebook_path = notebook_path,
        source = Source("WORKSPACE")
      ),
      task_key = task_key
    )
  ]
)

print(f"View the job at {w.config.host}/#job/{j.job_id}\n")

Visa en lista över grupper på kontonivå

I det här kodexemplet visas visningsnamnen för alla tillgängliga grupper i Azure Databricks-kontot.

from databricks.sdk import AccountClient

a = AccountClient()

for g in a.groups.list():
  print(g.display_name)

Ytterligare resurser

Mer information finns i:

Dokumentation om Databricks SDK för Python
Ytterligare kodexempel
Referens för API:er för Databricks-arbetsyta
Referens för Databricks-konto-API:er
Loggning
Tidskrävande åtgärder
Sidnumrerade svar
Enkel inloggning med OAuth

Databricks SDK för Python

Innan du börjar

Skapa en virtuell Python-miljö med venv

Skapa en virtuell miljö med Poesi

Kom igång med Databricks SDK för Python

Venv

Poesi

Venv

Poesi

Venv

Poesi

Venv

Poesi

Venv

Poesi

Autentisera Databricks SDK för Python med ditt Azure Databricks-konto eller din arbetsyta

Använda Databricks SDK för Python från en Azure Databricks-notebook-fil

Steg 1: Installera eller uppgradera Databricks SDK för Python

Steg 2: Kör koden

Använda Databricks-verktyg

Kodexempel

Skapa ett kluster

Ta bort ett kluster permanent

Skapa ett jobb

Visa en lista över grupper på kontonivå

Ytterligare resurser

Ytterligare resurser

Skapa en virtuell Python-miljö med `venv`