Пакет SDK Databricks для Python

В этой статье вы узнаете, как автоматизировать операции Azure Databricks и ускорить разработку с помощью пакета SDK Databricks для Python. Эта статья дополняет документацию по Пакету SDK Databricks для Python на сайте Read The Docs и примеры кода в пакете SDK Databricks для Python в GitHub.

Подготовка к работе

Пакет SDK Databricks для Python можно использовать в записной книжке Azure Databricks или на локальном компьютере разработки.

• Чтобы использовать пакет SDK Databricks для Python из записной книжки Azure Databricks, перейдите к использованию пакета SDK Databricks для Python из записной книжки Azure Databricks.
• Чтобы использовать пакет SDK Databricks для Python на локальном компьютере разработки, выполните действия, описанные в этом разделе.

Прежде чем приступить к использованию пакета SDK Databricks для Python, компьютер разработки должен иметь следующее:

• Настроена проверка подлинности Azure Databricks.
• Установлен Python 3.8 или более поздней версии. Для автоматизации вычислительных ресурсов Azure Databricks Databricks рекомендует установить основные и дополнительные версии Python, соответствующие установленному на целевом вычислительном ресурсе Azure Databricks. Примеры этой статьи основаны на автоматизации кластеров с databricks Runtime 13.3 LTS, на котором установлен Python 3.10. Для правильной версии см . заметки о выпуске Databricks Runtime и совместимость для версии среды выполнения Databricks в кластере.
• Databricks рекомендует создавать и активировать виртуальную среду Python для каждого проекта Python, используемого с пакетом SDK Databricks для Python. Виртуальные среды Python помогают убедиться, что проект кода использует совместимые версии пакетов Python и Python (в данном случае — пакет SDK Databricks для Python). Дополнительные сведения о виртуальных средах Python см. в статье venv или Поэзия.

Get начало работы с пакетом SDK Databricks для Python

В этом разделе описывается, как get начать работу с пакетом SDK Databricks для Python с локального компьютера разработки. Чтобы использовать пакет SDK Databricks для Python из записной книжки Azure Databricks, перейдите к использованию пакета SDK Databricks для Python из записной книжки Azure Databricks.

1. На компьютере разработки с настроенной проверкой подлинности Azure Databricks, Python уже установлен и виртуальная среда Python уже активирована, установите пакет databricks-sdk (и его зависимости) из индекса пакетов Python (PyPI) следующим образом:

   Венв

   Используется pip для установки databricks-sdk пакета. (В некоторых системах может потребоваться заменить pip3 на pip, здесь и на протяжении всего.)

   pip3 install databricks-sdk
   

   Poetry

   poetry add databricks-sdk
   

   Чтобы установить определенную версию пакета, пока пакет Databricks SDK для Python находится в бета-версииdatabricks-sdk, ознакомьтесь с журналом выпуска пакета. Например, чтобы установить версию 0.1.6:

   Венв

   pip3 install databricks-sdk==0.1.6
   

   Poetry

   poetry add databricks-sdk==0.1.6
   

   Чтобы обновить существующую установку пакета SDK Databricks для Python до последней версии, выполните следующую команду:

   Венв

   pip3 install --upgrade databricks-sdk
   

   Poetry

   poetry add databricks-sdk@latest
   

   Чтобы отобразить пакет SDK Databricks для текущего Version пакета Python и другие сведения, выполните следующую команду:

   Венв

   pip3 show databricks-sdk
   

   Poetry

   poetry show databricks-sdk
   

2. В виртуальной среде Python создайте файл кода Python, который импортирует пакет SDK Databricks для Python. В следующем примере в файле main.py с именем следующего содержимого просто перечислены все кластеры в рабочей области Azure Databricks:

   from databricks.sdk import WorkspaceClient
   
   w = WorkspaceClient()
   
   for c in w.clusters.list():
     print(c.cluster_name)
   

3. Запустите файл кода Python, при условии, что файл с именем main.py, выполнив python команду:

   Венв

   python3.10 main.py
   

   Poetry

   Если вы находитесь в оболочке виртуальной среды:

   python3.10 main.py
   

   Если вы не находитесь в оболочке виртуальной среды:

   poetry run python3.10 main.py
   

   Примечание.

   Не устанавливая аргументы в предыдущем вызове w = WorkspaceClient(), пакет SDK Databricks для Python использует свой процесс по умолчанию для проверки подлинности Azure Databricks. Чтобы переопределить это поведение по умолчанию, см. следующий раздел проверки подлинности .

Проверка подлинности пакета SDK Databricks для Python с помощью учетной записи Или рабочей области Azure Databricks

В этом разделе описывается проверка подлинности пакета SDK Databricks для Python с локального компьютера разработки на учетную запись Или рабочую область Azure Databricks. Чтобы выполнить проверку подлинности пакета SDK Databricks для Python из записной книжки Azure Databricks, перейдите к использованию пакета SDK Databricks для Python из записной книжки Azure Databricks.

Пакет SDK Databricks для Python реализует стандарт унифицированной проверки подлинности Клиента Databricks, консолидированный и согласованный архитектурный и программный подход к проверке подлинности. Этот подход помогает настроить и автоматизировать проверку подлинности с помощью Azure Databricks более централизованным и предсказуемым. Он позволяет настроить проверку подлинности Databricks один раз, а затем использовать эту конфигурацию в нескольких средствах Databricks и пакетах SDK без дальнейших изменений конфигурации проверки подлинности. Дополнительные сведения, включая более полные примеры кода в Python, см. в статье Databricks client unified authentication.

Некоторые из доступных шаблонов кода для инициализации проверки подлинности Databricks с помощью пакета SDK Databricks для Python включают:

• Используйте проверку подлинности databricks по умолчанию, выполнив одно из следующих действий:

  • Создайте или определите пользовательский профиль конфигурации Databricks с обязательными полями для целевого типа проверки подлинности Databricks. Затем задайте для переменной среды set имя пользовательского профиля конфигурации DATABRICKS_CONFIG_PROFILE.
  • Set необходимые переменные среды для заданного типа аутентификации в Databricks.

  Затем создайте экземпляр объекта с проверкой WorkspaceClient подлинности databricks по умолчанию следующим образом:

  from databricks.sdk import WorkspaceClient
  
  w = WorkspaceClient()
  # ...
  

• Жесткое кодирование обязательных полей поддерживается, но не рекомендуется, так как он рискует предоставлять конфиденциальную информацию в коде, например личные маркеры доступа Azure Databricks. В следующем примере жестко задаются хост Azure Databricks и токен доступа values для аутентификации с помощью токена Databricks:

  from databricks.sdk import WorkspaceClient
  
  w = WorkspaceClient(
    host  = 'https://...',
    token = '...'
  )
  # ...
  

См. также проверку подлинности в документации по Пакету SDK Databricks для Python.

Использование пакета SDK Databricks для Python из записной книжки Azure Databricks

Вы можете вызвать пакет SDK Databricks для Python из записной книжки Azure Databricks с подключенным кластером Azure Databricks с установленным пакетом SDK Databricks для Python. Он устанавливается по умолчанию во всех кластерах Azure Databricks, использующих Databricks Runtime 13.3 LTS или более поздней версии. Для кластеров Azure Databricks, использующих Databricks Runtime 12.2 LTS и ниже, сначала необходимо установить пакет SDK Databricks для Python. См . шаг 1. Установка или обновление пакета SDK Databricks для Python.

Чтобы просмотреть пакет SDK Databricks для Версии Python, установленной для определенной версии Databricks Runtime, см. раздел "Установленные библиотеки Python" заметки о выпуске Databricks Runtime для этой версии.

Databricks рекомендует установить последнюю доступную версию пакета SDK из PiPy, но при минимальной установке или обновлении до пакета SDK Databricks для Python 0.6.0 или более поздней версии, так как проверка подлинности записной книжки Azure Databricks используется версией 0.6.0 и выше для всех версий среды выполнения Databricks.

Следующая table описывает поддержку проверки подлинности записной книжки для пакета SDK Databricks для Python и Databricks Runtime:

Проверка подлинности записной книжки Azure Databricks по умолчанию использует временный личный маркер доступа Azure Databricks, который Azure Databricks автоматически создает в фоновом режиме для собственного использования. Azure Databricks удаляет этот временный маркер после остановки работы записной книжки.

Если вы хотите вызвать API уровня учетной записи Azure Databricks или использовать тип проверки подлинности Databricks, отличный от проверки подлинности записной книжки Databricks по умолчанию, также поддерживаются следующие типы проверки подлинности:

Проверка подлинности управляемых удостоверений Azure еще не поддерживается.

Шаг 1. Установка или обновление пакета SDK Databricks для Python

1. Записные книжки Python для Azure Databricks могут использовать пакет SDK Databricks для Python так же, как и любая другая библиотека Python. Чтобы установить или обновить пакет SDK Databricks для библиотеки Python в подключенном кластере Azure Databricks, выполните %pip магическую команду из ячейки записной книжки следующим образом:

   %pip install databricks-sdk --upgrade
   

2. После выполнения волшебной %pip команды необходимо перезапустить Python, чтобы сделать установленную или обновленную библиотеку доступной для записной книжки. Для этого выполните следующую команду из ячейки записной книжки сразу после ячейки с магической командой %pip :

   dbutils.library.restartPython()
   

3. Чтобы отобразить установленную версию пакета SDK Databricks для Python, выполните следующую команду из ячейки записной книжки:

   %pip show databricks-sdk | grep -oP '(?<=Version: )\S+'
   

Шаг 2. Запуск кода

В ячейках записной книжки создайте код Python, который импортирует, а затем вызывает пакет SDK Databricks для Python. В следующем примере используется по умолчанию проверка подлинности блокнота Azure Databricks для list всех кластеров в рабочей области Azure Databricks:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

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

При запуске этой ячейки появится list имен всех доступных кластеров в рабочей области Azure Databricks.

Чтобы использовать другой тип проверки подлинности Azure Databricks, ознакомьтесь с методами проверки подлинности Azure Databricks и щелкните соответствующую ссылку для получения дополнительных технических сведений.

Использовать служебные программы Databricks

Вы можете вызвать справочник по Databricks Utilities (dbutils) из пакета SDK Databricks для кода Python, работающего на локальном компьютере разработки или из записной книжки Azure Databricks.

• На локальном компьютере разработки служебные программы Databricks имеют доступ только к dbutils.fsгруппам команд , dbutils.secretsа dbutils.widgetsтакже к группам команд.dbutils.jobs
• Из записной книжки Azure Databricks, подключенной к кластеру Azure Databricks, программы Databricks имеют доступ ко всем доступным группам команд Databricks Utilities, а не только dbutils.fsи dbutils.secretsdbutils.widgets. Кроме того, dbutils.notebook группа команд ограничена только двумя уровнями команд, напримерdbutils.notebook.run.dbutils.notebook.exit

Чтобы вызвать служебные программы Databricks с локального компьютера разработки или записной книжки Azure Databricks, используйте dbutils в WorkspaceClientпределах. Этот пример кода использует проверку подлинности записной книжки Azure Databricks по умолчанию для вызова dbutils в WorkspaceClient, чтобы list пути всех объектов в корневом каталоге рабочей области DBFS.

from databricks.sdk import WorkspaceClient

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

for f in d:
  print(f.path)

Кроме того, можно вызвать dbutils напрямую. Однако вы не можете использовать только проверку подлинности записной книжки Azure Databricks по умолчанию. Этот пример кода вызывает напрямую от dbutils до list все объекты в корневом каталоге DBFS в рабочей области.

from databricks.sdk.runtime import *

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

for f in d:
  print(f.path)

Чтобы получить доступ к Unity Catalogvolumes, используйте files в WorkspaceClient. См. раздел Управление файлами в CatalogvolumesUnity. Невозможно использовать dbutils самостоятельно или внутри WorkspaceClient для доступа к volumes.

См. также взаимодействие с dbutils.

Примеры кода

В следующих примерах кода показано, как использовать пакет SDK Databricks для Python для создания и удаления кластеров, выполнения заданий и list групп на уровне учетных записей. В этих примерах кода используется проверка подлинности записной книжки Azure Databricks по умолчанию. Дополнительные сведения о проверке подлинности записной книжки Azure Databricks по умолчанию см. в статье "Использование пакета SDK Databricks для Python" из записной книжки Azure Databricks. Дополнительные сведения о проверке подлинности по умолчанию за пределами записных книжек см. в статье "Проверка подлинности пакета SDK Databricks для Python" с помощью учетной записи Или рабочей области Azure Databricks.

Дополнительные примеры кода см . в примерах в пакете SDK Databricks для репозитория Python в GitHub. См. также:

• Справочник по API рабочей области Databricks

• Справочник по API учетной записи Databricks

• Создание кластера

• Окончательное удаление кластера

• Создание задания

• Создание задания, использующего бессерверные вычисления

• Управление файлами в Unity Catalogvolumes

• List группы уровня учетной записи

Создание кластера

В этом примере кода создается кластер с указанной версией Databricks Runtime и типом узла кластера. Этот кластер имеет одну рабочую роль, и кластер будет автоматически завершаться через 15 минут времени простоя.

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

Окончательное удаление пользователя

Этот пример кода окончательно удаляет кластер с указанным идентификатором кластера из рабочей области.

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)

Создание задания

В этом примере кода создается задание Azure Databricks, которое запускает указанную записную книжку в указанном кластере. По мере выполнения кода он получает путь к существующей записной книжке, существующий идентификатор кластера и связанные параметры задания от пользователя в терминале.

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

Создание задания, использующего бессерверные вычисления

В следующем примере создается задание, использующее бессерверные вычисления для заданий:

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

Управление файлами в Unity Catalogvolumes

В этом примере кода показаны различные вызовы функций files в WorkspaceClient для доступа к Catalogтома Unity.

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)

группы учетных записей уровня List

В этом примере кода перечислены отображаемые имена для всех доступных групп в учетной записи Azure Databricks.

from databricks.sdk import AccountClient

a = AccountClient()

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

Тестирование

Чтобы протестировать код, используйте платформы тестов Python, такие как pytest. Чтобы протестировать код в имитированных условиях без вызова конечных точек REST API Azure Databricks или изменения состояния учетных записей Или рабочих областей Azure Databricks, используйте библиотеки подражания Python, такие как unittest.mock.

В следующем примере файла с именем helpers.py содержится create_cluster функция, которая возвращает сведения о новом кластере:

# 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

Учитывая следующий файл с именем main.py , который вызывает функцию create_cluster :

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

Следующий файл с именем test_helpers.py проверяет, возвращает ли create_cluster функция ожидаемый ответ. Вместо того чтобы создать кластер в целевой рабочей области, этот тест макетирует WorkspaceClient объект, определяет параметры макетированного объекта, а затем передает макетируемый объект в функцию create_cluster . Затем тест проверяет, возвращает ли функция ожидаемый идентификатор нового макетированного кластера.

# 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'

Чтобы выполнить этот тест, выполните pytest команду из корневого каталога проекта кода, которая должна создать результаты теста, аналогичные следующим:

$ 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 ==========================

Дополнительные ресурсы

Дополнительные сведения см. в разделе:

• Документация по пакету SDK Databricks для Python

• Дополнительные примеры кода

• Справочник по API рабочей области Databricks

• Справочник по API учетной записи Databricks

• Ведение журнала

• Длительные операции

• Ответы с разбивкой на страницы

• Единый вход с помощью OAuth