Compartilhar via

SDK do Databricks para Python

  • Artigo

Neste artigo, você aprenderá a automatizar operações em contas, espaços de trabalho e recursos relacionados do Azure Databricks com o SDK do Databricks para Python. Este artigo complementa a documentação do SDK do Databricks para Python sobre Leia a documentação e os exemplos de código no repositório do SDK do Databricks para Python no GitHub.

Observação

Esse recurso está em Beta e pode ser usado na produção.

Durante o período Beta, o Databricks recomenda que você fixe uma dependência na versão secundária específica do SDK do Databricks para Python da qual seu código depende. Por exemplo, você pode fixar dependências em arquivos como requirements.txt para venv, ou pyproject.toml e poetry.lock para o Poetry. Para obter mais informações sobre como fixar dependências, consulte Ambientes Virtuais e Pacotes para venv, ou Como instalar dependências para o Poetry.

Antes de começar

Você pode usar o SDK do Databricks para Python de dentro de um bloco de anotações do Azure Databricks ou de sua máquina de desenvolvimento local.

Antes de começar a usar o SDK do Databricks para Python, sua máquina de desenvolvimento deve ter:

  • A autenticação do Azure Databricks configurada.
  • Python 3.8 ou superior instalado. Para automatizar os recursos de computação do Azure Databricks, o Databricks recomenda que você tenha as versões principais e secundárias do Python instaladas que correspondam àquela instalada no recurso de computação de destino do Azure Databricks. Os exemplos deste artigo dependem da automação de clusters com o Databricks Runtime 13.3 LTS, que tem o Python 3.10 instalado. Para obter a versão correta, consulte Versões de notas de versão e compatibilidade do Databricks Runtime para a versão Databricks Runtime do cluster.
  • O Databricks recomenda que você crie e ative um ambiente virtual Python para cada projeto Python que você usar com o SDK do Databricks para Python. Os ambientes virtuais Python ajudam a garantir que seu projeto de código esteja usando versões compatíveis de pacotes Python e Python (neste caso, o pacote Databricks SDK for Python). Para obter mais informações sobre os ambientes virtuais do Python, confira venv ou Poetry.

Introdução ao SDK do Databricks para Python

Esta seção descreve como começar a usar o SDK do Databricks para Python a partir de sua máquina de desenvolvimento local. Para usar o SDK do Databricks para Python de um notebook do Azure Databricks, vá para Usar o SDK do Databricks para Python de um notebook do Azure Databricks.

  1. No computador de desenvolvimento com a autenticação do Azure Databricks configurada, o Python já instalado e o ambiente virtual do Python já ativado, instale o pacote databricks-sdk (e as respectivas dependências) do PyPI (Python Package Index) da seguinte maneira:

    Venv

    Use o pip para instalar o pacote databricks-sdk. (Em alguns sistemas, talvez seja necessário substituir pip3 por pip, aqui e em todos os lugares).

    pip3 install databricks-sdk

    Poetry

    poetry add databricks-sdk

    Para instalar uma versão específica do pacote databricks-sdk enquanto o SDK do Databricks para Python está na versão beta, confira o Histórico de versões do pacote. Por exemplo, para instalar a versão 0.1.6:

    Venv

    pip3 install databricks-sdk==0.1.6

    Poetry

    poetry add databricks-sdk==0.1.6

    Para atualizar uma instalação existente do pacote do SDK do Databricks para Python para a última versão, execute o seguinte comando:

    Venv

    pip3 install --upgrade databricks-sdk

    Poetry

    poetry add databricks-sdk@latest

    Para mostrar a Version atual do pacote do SDK do Databricks para Python e outros detalhes, execute o seguinte comando:

    Venv

    pip3 show databricks-sdk

    Poetry

    poetry show databricks-sdk

  2. Em seu ambiente virtual Python, crie um arquivo de código Python que importe o SDK do Databricks para Python. O exemplo a seguir, em um arquivo chamado main.py com o seguinte conteúdo, simplesmente lista todos os clusters no workspace do Azure Databricks:

    from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

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

  3. Execute o arquivo de código Python, supondo um arquivo chamado main.py, executando o comando python:

    Venv

    python3.10 main.py

    Poetry

    Se você estiver no shell do ambiente virtual:

    python3.10 main.py

    Se você não estiver no shell do ambiente virtual:

    poetry run python3.10 main.py

    Observação

    Ao não definir nenhum argumento na chamada anterior para w = WorkspaceClient(), o SDK do Databricks para Python usa seu processo padrão para tentar executar a autenticação do Azure Databricks. Para substituir esse comportamento padrão, consulte a seção autenticação a seguir.

Autenticar o SDK do Databricks para Python com sua conta ou espaço de trabalho do Azure Databricks

Esta seção descreve como autenticar o SDK do Databricks para Python de sua máquina de desenvolvimento local para sua conta ou espaço de trabalho do Azure Databricks. Para autenticar o SDK do Databricks para Python de um notebook do Azure Databricks, vá para Usar o SDK do Databricks para Python de um notebook do Azure Databricks.

O SDK do Databricks para Python implementa o padrão Autenticação unificada do cliente Databricks, uma abordagem arquitetônica e programática consolidada e consistente para autenticação. Essa abordagem ajuda a tornar a configuração e a automação da autenticação com o Azure Databricks mais centralizada e previsível. Ele permite que você configure a autenticação do Databricks uma vez e use essa configuração em várias ferramentas e SDKs do Databricks sem mais alterações na configuração da autenticação. Para obter mais informações, incluindo exemplos de código mais completos em Python, consulte Autenticação unificada do cliente Databricks.

Observação

O SDK do Databricks para Python ainda não implementou a Autenticação de identidades gerenciadas pelo Azure.

Alguns dos padrões de codificação disponíveis para inicializar a autenticação do Databricks com o SDK do Databricks para Python incluem:

  • Use a autenticação padrão do Databricks executando um destes procedimentos:

    • Criar ou identificar um perfil de configuração do Databricks personalizado com os campos obrigatórios para o tipo de autenticação do Databricks de destino. Em seguida, defina a variável de ambiente DATABRICKS_CONFIG_PROFILE para o nome do perfil de configuração personalizado.
    • Defina as variáveis de ambiente necessárias para o tipo de autenticação do Databricks de destino.

    Em seguida, crie uma instância, por exemplo, de um objeto WorkspaceClient com a autenticação padrão do Databricks da seguinte maneira:

    from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

  • A codificação dos campos obrigatórios é suportada, mas não recomendada, pois corre o risco de expor informações confidenciais em seu código, como tokens de acesso pessoal do Azure Databricks. O exemplo a seguir codifica os valores de host e token de acesso do Azure Databricks para autenticação de token do Databricks:

    from databricks.sdk import WorkspaceClient

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

Confira também Autenticação na documentação do SDK do Databricks para Python.

Usar o SDK do Databricks para Python de um notebook do Azure Databricks

Você pode chamar a funcionalidade do SDK do Databricks para Python de um notebook do Azure Databricks que tenha um cluster do Azure Databricks anexado com o SDK do Databricks para Python instalado. Está instalado por padrão em todos os clusters do Azure Databricks que usam o Databricks Runtime 13.3 LTS ou superior. Para clusters do Azure Databricks que usam o Databricks Runtime 12.2 LTS e inferior, você precisa instalar primeiro o SDK do Databricks para Python. Consulte Etapa 1: instalar ou atualizar o SDK do Databricks para Python.

Para ver a versão do Databricks para Python instalada por padrão para uma versão específica do Databricks Runtime, confira a seção Bibliotecas Python instaladas nas Notas de versão do Databricks Runtime para essa versão.

O Databricks recomenda que você instale a versão mais recente disponível do SDK do PiPy, mas, no mínimo, instale ou atualize para o SDK do Databricks para Python 0.6.0 ou superior, pois a autenticação padrão do notebook do Azure Databricks é usada pela versão 0.6.0 e superior em todas as versões do Databricks Runtime.

Observação

O Databricks Runtime 15.1 é o primeiro Databricks Runtime a ter uma versão do SDK do Databricks para Python (0.20.0) instalada que dá suporte à autenticação de notebook padrão sem necessidade de atualização.

A tabela a seguir descreve o suporte à autenticação de notebook para as versões SDK do Databricks para Python e Databricks Runtime:

SDK/DBR 10.4 LTS 11.3 LTS 12.3 LTS 13.3 LTS 14.3 LTS 15.1 e versões posteriores
0.1.7 e inferior
0.1.10 ✓ ✓ ✓ ✓ ✓
0.6.0 ✓ ✓ ✓ ✓ ✓ ✓
0.20.0 e superior ✓ ✓ ✓ ✓ ✓ ✓

A autenticação padrão do notebook do Azure Databricks depende de um token de acesso pessoal temporário do Azure Databricks que o Azure Databricks gera automaticamente em segundo plano para seu próprio uso. O Azure Databricks exclui esse token temporário depois que o notebook para de ser executado.

Importante

  • A autenticação padrão do notebook do Azure Databricks funciona apenas no nó de driver do cluster, mas não em nenhum dos nós de trabalho ou executor do cluster.
  • A autenticação do notebook do Azure Databricks não funciona com os perfis de configuração do Azure Databricks.

Se você quiser chamar APIs no nível da conta do Azure Databricks ou se quiser usar um tipo de autenticação do Databricks diferente da autenticação padrão do notebook do Databricks, também há suporte para os seguintes tipos de autenticação:

Tipo de autenticação SDK do Databricks para versões do Python
Autenticação OAuth máquina a máquina (M2M) 0.18.0 e superior
Autenticação U2M (usuário para computador) do OAuth 0.19.0 e superior
Autenticação de entidades de serviço do Microsoft Entra ID Todas as versões
Autenticação da CLI do Azure Todas as versões
Autenticação de token de acesso pessoal do Databricks Todas as versões

A autenticação de identidades gerenciadas do Azure ainda não é compatível.

Etapa 1: instalar ou atualizar o SDK do Databricks para Python

  1. Os blocos de anotações Python do Azure Databricks podem usar o SDK do Databricks para Python como qualquer outra biblioteca Python. Para instalar ou atualizar a biblioteca do SDK do Databricks para Python no cluster do Azure Databricks anexado, execute o comando mágico %pip em uma célula do notebook da seguinte forma:

    %pip install databricks-sdk --upgrade

  2. Depois de executar o comando mágico %pip, você deve reiniciar o Python para disponibilizar a biblioteca instalada ou atualizada para o notebook. Para fazer isso, execute o seguinte comando de uma célula de bloco de anotações imediatamente após a célula com o comando magic %pip:

    dbutils.library.restartPython()

  3. Para exibir a versão instalada do SDK do Databricks para Python, execute o seguinte comando em uma célula do notebook:

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

Etapa 2: Executar seu código

Nas células do bloco de anotações, crie um código Python que importe e chame o SDK do Databricks para Python. O exemplo a seguir usa a autenticação padrão do notebook do Azure Databricks para listar todos os clusters em seu workspace do Azure Databricks:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

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

Quando você executa essa célula, uma lista dos nomes de todos os clusters disponíveis em seu espaço de trabalho do Azure Databricks é exibida.

Para usar um tipo de autenticação diferente do Azure Databricks, consulte Métodos de autenticação do Azure Databricks e clique no link correspondente para obter detalhes técnicos adicionais.

Usar utilitários Databricks

Você pode chamar a referência Utilitários do Databricks (dbutils) do SDK do Databricks para código Python em execução em sua máquina de desenvolvimento local ou de dentro de um notebook do Azure Databricks.

  • No computador de desenvolvimento local, os Utilitários do Databricks tem acesso apenas aos grupos de comando dbutils.fs, dbutils.secrets, dbutils.widgets e dbutils.jobs.
  • Em um bloco de anotações do Azure Databricks anexado a um cluster do Azure Databricks, os Utilitários do Databricks têm acesso a todos os grupos de comandos disponíveis do Databricks Utilities, não apenas dbutils.fs, dbutils.secrets e dbutils.widgets. Além disso, o grupo de comandos dbutils.notebook é limitado a apenas dois níveis de comandos, por exemplo, dbutils.notebook.run ou dbutils.notebook.exit.

Para chamar os Utilitários do Databricks de sua máquina de desenvolvimento local ou de um bloco de anotações do Azure Databricks, use dbutils em WorkspaceClient. Este exemplo de código usa a autenticação padrão do notebook do Azure Databricks para chamar dbutils dentro de WorkspaceClient para listar os caminhos de todos os objetos na raiz DBFS do espaço de trabalho.

from databricks.sdk import WorkspaceClient

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

for f in d:
  print(f.path)

Como alternativa, você pode chamar diretamente dbutils. No entanto, você está limitado a usar apenas a autenticação padrão do notebook do Azure Databricks. Este exemplo de código chama dbutils diretamente para listar todos os objetos na raiz DBFS do espaço de trabalho.

from databricks.sdk.runtime import *

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

for f in d:
  print(f.path)

Para acessar volumes do Unity Catalog, use files em WorkspaceClient. Consulte Gerenciar arquivos em volumes do Unity Catalog. Não é possível usar dbutils sozinho ou no WorkspaceClient para acessar os volumes.

Consulte também Interação com dbutils.

Exemplos de código

Os exemplos de código a seguir demonstram como usar o SDK do Databricks para Python para criar e excluir clusters, executar trabalhos e listar grupos de nível de conta. Esses exemplos de código usam a autenticação padrão do notebook do Azure Databricks. Para obter detalhes sobre a autenticação padrão do notebook do Azure Databricks, confira Usar o SDK do Databricks para Python a partir de um notebook do Azure Databricks. Para obter detalhes sobre a autenticação padrão fora dos blocos de anotações, consulte Autenticar o SDK do Databricks para Python com sua conta ou espaço de trabalho do Azure Databricks.

Para ver outros exemplos de código, confira os exemplos no repositório do SDK do Databricks para Python no GitHub. Consulte também:

Criar um cluster

Este exemplo de código cria um cluster com a versão especificada do Databricks Runtime e o tipo de nó do cluster. Esse cluster tem um trabalho e o cluster será encerrado automaticamente após 15 minutos de tempo ocioso.

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

Excluir um cluster permanentemente

Este exemplo de código exclui permanentemente o cluster com a ID de cluster especificada do workspace.

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)

Criar um trabalho

Este exemplo de código cria um trabalho do Azure Databricks que executa o notebook especificado no cluster especificado. À medida que o código é executado, ele obtém o caminho do notebook existente, a ID do cluster existente e as configurações de trabalho relacionadas do usuário no terminal.

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

Criar um trabalho que usa computação sem servidor

O exemplo a seguir cria um trabalho que usa Computação sem servidor para trabalhos:

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

Gerenciar arquivos em volumes do Catálogo do Unity

Este exemplo de código demonstra várias chamadas para a funcionalidade files em WorkspaceClient a fim de acessar um volume do Catálogo do 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)

Listar grupos no nível da conta

Este exemplo de código lista os nomes de exibição de todos os grupos disponíveis na conta do Azure Databricks.

from databricks.sdk import AccountClient

a = AccountClient()

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

Testando

Para testar seu código, use estruturas de teste do Python, como pytest. Para testar seu código em condições simuladas sem chamar pontos de extremidade da API REST do Azure Databricks ou alterar o estado de suas contas ou workspaces do Azure Databricks, você pode usar bibliotecas de simulação do Python, como unittest.mock.

Por exemplo, dado o seguinte arquivo nomeado helpers.py contendo uma função create_cluster que retorna informações sobre o novo 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

E dado o seguinte arquivo chamado main.py que chama a função 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)

O arquivo nomeado test_helpers.py a seguir testa se a função create_cluster retorna a resposta esperada. Em vez de criar um cluster no workspace de destino, esse teste simula um objeto WorkspaceClient, define as configurações do objeto simulado e, em seguida, passa o objeto simulado para a função create_cluster. Em seguida, o teste verifica se a função retorna a ID esperada do novo cluster simulado.

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

Para executar esse teste, execute o comando pytest na raiz do projeto de código, que deve produzir resultados de teste semelhantes aos seguintes:

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

Recursos adicionais

Para saber mais, veja: