Databricks SDK för Python

Artikel
10/31/2024

Kommentar

Databricks rekommenderar Databricks-tillgångspaket för att skapa, utveckla, distribuera och testa jobb och andra Databricks-resurser som källkod. Se Vad är Databricks-tillgångspaket?.

I den här artikeln får du lära dig hur du automatiserar Azure Databricks-åtgärder och påskyndar utvecklingen 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

Databricks SDK för Python ä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. I den här artikelns exempel används automatiserade kluster med Databricks Runtime 13.3 LTS, 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-projekt 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). Mer information om virtuella Python-miljöer finns i venv eller poesi.

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
```
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. Den installeras som standard på alla Azure Databricks-kluster som använder Databricks Runtime 13.3 LTS eller senare. För Azure Databricks-kluster som använder Databricks Runtime 12.2 LTS 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 Databricks SDK för Python-versionen som är installerad för en specifik Databricks Runtime-version finns i avsnittet Installerade Python-bibliotek i viktig information om Databricks Runtime för den versionen.

Databricks rekommenderar att du installerar den senaste tillgängliga versionen av SDK:t från PiPy, men vid en minsta installation eller uppgradering till Databricks SDK för Python 0.6.0 eller senare, som standard används Azure Databricks Notebook-autentisering av version 0.6.0 och senare på alla Databricks Runtime-versioner.

Kommentar

Databricks Runtime 15.1 är den första Databricks Runtime som har en version av Databricks SDK för Python (0.20.0) installerad som stöder standardautentisering av notebook-filer utan uppgradering krävs.

I följande tabell beskrivs stöd för notebook-autentisering för Databricks SDK för Python- och Databricks Runtime-versioner:

SDK/DBR	10.4 LTS	11.3 LTS	12.3 LTS	13.3 LTS	14.3 LTS	15.1 och senare
0.1.7 och lägre
0.1.10		✓	✓	✓	✓	✓
0.6.0	✓	✓	✓	✓	✓	✓
0.20.0 och senare	✓	✓	✓	✓	✓	✓

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.
Azure Databricks-notebook-autentisering fungerar inte med Azure Databricks-konfigurationsprofiler.

Om du vill anropa API:er på Azure Databricks-kontonivå eller om du vill använda en annan Databricks-autentiseringstyp än standardautentisering för Databricks-notebook-filer stöds även följande autentiseringstyper:

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 med tjänstens huvudnamn i 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.

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 autentiseringsmetoder för 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)

Om du vill komma åt Unity Catalog-volymer använder du files i WorkspaceClient. Se Hantera filer i Unity Catalog-volymer. Du kan inte använda dbutils sig själv eller inom WorkspaceClient för att komma åt volymer.

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:

Referens för API:er för Databricks-arbetsyta
Referens för Databricks-konto-API:er
Skapa ett kluster
Ta bort ett kluster permanent
Skapa ett jobb
Skapa ett jobb som använder serverlös beräkning
Hantera filer i Unity Catalog-volymer
Visa en lista över grupper på kontonivå

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")

Skapa ett jobb som använder serverlös beräkning

I följande exempel skapas ett jobb som använder serverlös beräkning för jobb:

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

w = WorkspaceClient()

j = w.jobs.create(
  name = "My Serverless Job",
  tasks = [
    Task(
      notebook_task = NotebookTask(
      notebook_path = "/Users/user@databricks.com/MyNotebook",
      source = Source("WORKSPACE")
      ),
      task_key = "MyTask",
   )
  ]
)

Hantera filer i Unity Catalog-volymer

Det här kodexemplet visar olika anrop till files funktioner i WorkspaceClient för att få åtkomst till en Unity Catalog-volym.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Define volume, folder, and file details.
catalog            = 'main'
schema             = 'default'
volume             = 'my-volume'
volume_path        = f"/Volumes/{catalog}/{schema}/{volume}" # /Volumes/main/default/my-volume
volume_folder      = 'my-folder'
volume_folder_path = f"{volume_path}/{volume_folder}" # /Volumes/main/default/my-volume/my-folder
volume_file        = 'data.csv'
volume_file_path   = f"{volume_folder_path}/{volume_file}" # /Volumes/main/default/my-volume/my-folder/data.csv
upload_file_path   = './data.csv'

# Create an empty folder in a volume.
w.files.create_directory(volume_folder_path)

# Upload a file to a volume.
with open(upload_file_path, 'rb') as file:
  file_bytes = file.read()
  binary_data = io.BytesIO(file_bytes)
  w.files.upload(volume_file_path, binary_data, overwrite = True)

# List the contents of a volume.
for item in w.files.list_directory_contents(volume_path):
  print(item.path)

# List the contents of a folder in a volume.
for item in w.files.list_directory_contents(volume_folder_path):
  print(item.path)

# Print the contents of a file in a volume.
resp = w.files.download(volume_file_path)
print(str(resp.contents.read(), encoding='utf-8'))

# Delete a file from a volume.
w.files.delete(volume_file_path)

# Delete a folder from a volume.
w.files.delete_directory(volume_folder_path)

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)

Testning

Om du vill testa koden använder du Python-testramverk som pytest. Om du vill testa koden under simulerade förhållanden utan att anropa Azure Databricks REST API-slutpunkter eller ändra tillståndet för dina Azure Databricks-konton eller arbetsytor använder du Python-modelleringsbibliotek som unittest.mock.

Dricks

Databricks Labs tillhandahåller ett pytest-plugin-program för att förenkla integreringstestningen med Databricks och ett pylint-plugin-program för att säkerställa kodkvaliteten.

Följande exempelfil med namnet helpers.py innehåller en create_cluster funktion som returnerar information om det nya klustret:

# helpers.py

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.compute import ClusterDetails

def create_cluster(
  w: WorkspaceClient,
  cluster_name:            str,
  spark_version:           str,
  node_type_id:            str,
  autotermination_minutes: int,
  num_workers:             int
) -> ClusterDetails:
  response = w.clusters.create(
    cluster_name            = cluster_name,
    spark_version           = spark_version,
    node_type_id            = node_type_id,
    autotermination_minutes = autotermination_minutes,
    num_workers             = num_workers
  )
  return response

Med följande fil med namnet main.py som anropar create_cluster funktionen:

# main.py

from databricks.sdk import WorkspaceClient
from helpers import *

w = WorkspaceClient()

# Replace <spark-version> with the target Spark version string.
# Replace <node-type-id> with the target node type string.
response = create_cluster(
  w = w,
  cluster_name            = 'Test Cluster',
  spark_version           = '<spark-version>',
  node_type_id            = '<node-type-id>',
  autotermination_minutes = 15,
  num_workers             = 1
)

print(response.cluster_id)

Följande fil med namnet test_helpers.py testar om create_cluster funktionen returnerar det förväntade svaret. I stället för att skapa ett kluster på målarbetsytan hånar det här testet ett WorkspaceClient objekt, definierar inställningarna för det simulerade objektet och skickar sedan det simulerade objektet till create_cluster funktionen. Testet kontrollerar sedan om funktionen returnerar det nya simulerade klustrets förväntade ID.

# test_helpers.py

from databricks.sdk import WorkspaceClient
from helpers import *
from unittest.mock import create_autospec # Included with the Python standard library.

def test_create_cluster():
  # Create a mock WorkspaceClient.
  mock_workspace_client = create_autospec(WorkspaceClient)

  # Set the mock WorkspaceClient's clusters.create().cluster_id value.
  mock_workspace_client.clusters.create.return_value.cluster_id = '123abc'

  # Call the actual function but with the mock WorkspaceClient.
  # Replace <spark-version> with the target Spark version string.
  # Replace <node-type-id> with the target node type string.
  response = create_cluster(
    w = mock_workspace_client,
    cluster_name            = 'Test Cluster',
    spark_version           = '<spark-version>',
    node_type_id            = '<node-type-id>',
    autotermination_minutes = 15,
    num_workers             = 1
  )

  # Assert that the function returned the mocked cluster ID.
  assert response.cluster_id == '123abc'

Kör det här testet genom att köra pytest kommandot från kodprojektets rot, vilket bör ge testresultat som liknar följande:

$ pytest
=================== test session starts ====================
platform darwin -- Python 3.12.2, pytest-8.1.1, pluggy-1.4.0
rootdir: <project-rootdir>
collected 1 item

test_helpers.py . [100%]
======================== 1 passed ==========================

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

Dela via

Databricks SDK för Python

Innan du börjar

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

Skapa ett jobb som använder serverlös beräkning

Hantera filer i Unity Catalog-volymer

Visa en lista över grupper på kontonivå

Testning

Ytterligare resurser

Feedback

Ytterligare resurser