Databricks SDK para Python

Artigo
10/11/2024

Nota

A Databricks recomenda o Databricks Asset Bundles para criar, desenvolver, implantar e testar trabalhos e outros recursos do Databricks como código-fonte. Consulte O que são Databricks Asset Bundles?.

Neste artigo, você aprenderá a automatizar as operações do Azure Databricks e acelerar o desenvolvimento com o SDK do Databricks para Python. Este artigo complementa a documentação do Databricks SDK for Python em Read The Docs e os exemplos de código no repositório Databricks SDK for Python no GitHub.

Nota

O Databricks SDK para Python está em Beta e pode ser usado em 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 Poetry. Para obter mais informações sobre como fixar dependências, consulte Ambientes virtuais e pacotes para venv, ou Instalando dependências para poesia.

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.

Para usar o SDK do Databricks para Python de dentro de um bloco de anotações do Azure Databricks, pule para Usar o SDK do Databricks para Python de um bloco de anotações do Azure Databricks.
Para usar o Databricks SDK for Python de sua máquina de desenvolvimento local, conclua as etapas nesta seção.

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

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 do Azure Databricks de destino. 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 das notas de versão do Databricks Runtime e compatibilidade para a versão do Databricks Runtime do cluster.
O Databricks recomenda que você crie e ative um ambiente virtual Python para cada projeto Python que você usa com o Databricks SDK for Python. Os ambientes virtuais Python ajudam a certificar-se de que o seu projeto de código está a utilizar versões compatíveis dos pacotes Python e Python (neste caso, o pacote Databricks SDK for Python). Para obter mais informações sobre ambientes virtuais Python, consulte 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 dentro de um bloco de anotações do Azure Databricks, pule para Usar o SDK do Databricks para Python de um bloco de anotações do Azure Databricks.

Em sua máquina de desenvolvimento com a autenticação do Azure Databricks configurada, o Python já instalado e seu ambiente virtual Python já ativado, instale o pacote databricks-sdk (e suas dependências) do Python Package Index (PyPI), da seguinte maneira:

Venv

Use pip para instalar o databricks-sdk pacote. (Em alguns sistemas, talvez seja necessário substituir pip3 por pip, aqui e por toda parte.)
```
pip3 install databricks-sdk
```
Poesia
```
poetry add databricks-sdk
```
Para instalar uma versão específica do databricks-sdk pacote enquanto o SDK do Databricks para Python estiver em versão beta, consulte 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
```
Poesia
```
poetry add databricks-sdk==0.1.6
```
Para atualizar uma instalação existente do pacote Databricks SDK for Python para a versão mais recente, execute o seguinte comando:

Venv
```
pip3 install --upgrade databricks-sdk
```
Poesia
```
poetry add databricks-sdk@latest
```
Para mostrar os detalhes atuais Version e outros detalhes do pacote Databricks SDK for Python, execute o seguinte comando:

Venv
```
pip3 show databricks-sdk
```
Poesia
```
poetry show databricks-sdk
```
Em seu ambiente virtual Python, crie um arquivo de código Python que importe o Databricks SDK for Python. O exemplo a seguir, em um arquivo nomeado main.py com o seguinte conteúdo, simplesmente lista todos os clusters em seu espaço de trabalho do Azure Databricks:
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for c in w.clusters.list():
  print(c.cluster_name)
```
Execute seu arquivo de código Python, assumindo um arquivo chamado main.py, executando o python comando:

Venv
```
python3.10 main.py
```
Poesia

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
```
Nota

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 de autenticação a seguir.

Autentique 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 dentro de um bloco de anotações do Azure Databricks, pule para Usar o SDK do Databricks para Python de um bloco de anotações do Azure Databricks.

O SDK do Databricks para Python implementa o padrão de 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 centralizadas e previsíveis. Ele permite que você configure a autenticação do Databricks uma vez e, em seguida, use essa configuração em várias ferramentas e SDKs do Databricks sem mais alterações na configuração de autenticação. Para obter mais informações, incluindo exemplos de código mais completos em Python, consulte Autenticação unificada do cliente Databricks.

Nota

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

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

Use a autenticação padrão do Databricks seguindo um destes procedimentos:
- Crie ou identifique um perfil de configuração personalizado do Databricks com os campos necessários para o tipo de autenticação Databricks de destino. Em seguida, defina a DATABRICKS_CONFIG_PROFILE variável de ambiente como o nome do perfil de configuração personalizado.
- Defina as variáveis de ambiente necessárias para o tipo de autenticação Databricks de destino.
Em seguida, instancie, por exemplo, um WorkspaceClient objeto com a autenticação padrão do Databricks da seguinte maneira:
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...
```
A codificação rígida 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 valores de token de host e acesso do Azure Databricks para autenticação de token Databricks:
```
from databricks.sdk import WorkspaceClient

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

Consulte também Autenticação na documentação do Databricks SDK for Python.

Usar o SDK do Databricks para Python de um bloco de anotações do Azure Databricks

Você pode chamar a funcionalidade do SDK do Databricks para Python a partir de um bloco de anotações do Azure Databricks que tenha um cluster do Azure Databricks anexado com o SDK do Databricks para Python instalado. Ele é 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ê deve instalar o SDK do Databricks para Python primeiro. Consulte Etapa 1: Instalar ou atualizar o SDK do Databricks para Python.

Para ver a versão do SDK do Databricks para Python instalada para uma versão específica do Databricks Runtime, consulte a seção Bibliotecas Python instaladas das 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 Databricks SDK for Python 0.6.0 ou superior, pois a autenticação padrão do bloco de anotações do Azure Databricks é usada pela versão 0.6.0 e superior em todas as versões do Databricks Runtime.

Nota

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

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

SDK/DBR	10.4 LTS	11.3 LTS	12,3 LTS	13.3 LTS	14,3 LTS	15.1 e superior
0.1.7 e inferior
0.1.10		✓	✓	✓	✓	✓
0.6.0	✓	✓	✓	✓	✓	✓
0.20.0 e superior	✓	✓	✓	✓	✓	✓

A autenticação padrão do bloco de anotações 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 bloco de anotações para de ser executado.

Importante

A autenticação padrão do bloco de anotações do Azure Databricks funciona apenas no nó do driver do cluster e não em qualquer um dos nós de trabalho ou executor do cluster.
A autenticação de bloco de anotações do Azure Databricks não funciona com 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 Databricks diferente da autenticação padrão do bloco de anotações Databricks, os seguintes tipos de autenticação também são suportados:

Authentication type	Databricks SDK para versões Python
Autenticação máquina a máquina (M2M) OAuth	0.18.0 e superior
Autenticação OAuth user-to-machine (U2M)	0.19.0 e superior
Autenticação ddo principal 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 Databricks	Todas as versões

A autenticação de identidades gerenciadas do Azure ainda não é suportada.

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

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 %pip comando magic a partir de uma célula do bloco de anotações da seguinte maneira:
```
%pip install databricks-sdk --upgrade
```
Depois de executar o %pip comando magic, 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 do bloco de anotações imediatamente após a célula com o %pip comando magic:
```
dbutils.library.restartPython()
```
Para exibir a versão instalada do Databricks SDK for Python, execute o seguinte comando a partir de uma célula do bloco de anotações:
```
%pip show databricks-sdk | grep -oP '(?<=Version: )\S+'
```

Etapa 2: Execute seu código

Nas células do bloco de anotações, crie código Python que importe e chame o SDK do Databricks para Python. O exemplo a seguir usa a autenticação padrão do bloco de anotações do Azure Databricks para listar todos os clusters em seu espaço de trabalho 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 aparece.

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 de Utilitários de 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 bloco de anotações do Azure Databricks.

A partir da sua máquina de desenvolvimento local, o dbutils.fsdbutils.secretsDatabricks Utilities tem acesso apenas aos grupos , , dbutils.widgetse dbutils.jobs comando.
A partir de um bloco de notas do Azure Databricks anexado a um cluster do Azure Databricks, o Databricks Utilities tem acesso a todos os grupos de comandos disponíveis do Databricks Utilities, não apenas dbutils.fs, dbutils.secretse dbutils.widgets. Além disso, o dbutils.notebook grupo de comandos é limitado apenas a dois níveis de comandos, por exemplo dbutils.notebook.run ou dbutils.notebook.exit.

Para chamar Utilitários 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 bloco de anotações do Azure Databricks para chamar dbutils WorkspaceClient dentro 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 ligar dbutils diretamente. No entanto, você está limitado a usar apenas a autenticação padrão do bloco de anotações 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 os volumes do Catálogo Unity, use files em WorkspaceClient. Consulte Gerenciar arquivos em volumes do Catálogo Unity. Você não pode usar dbutils sozinho ou dentro WorkspaceClient para acessar 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 no nível da conta. Estes exemplos de código usam a autenticação padrão do bloco de anotações do Azure Databricks. Para obter detalhes sobre a autenticação padrão do bloco de anotações do Azure Databricks, consulte Usar o SDK do Databricks para Python de um bloco de anotações 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 obter exemplos de código adicionais, consulte os exemplos no repositório Databricks SDK for Python no GitHub. Consulte também:

Referência das APIs do Databricks Workspace
Referência de APIs de conta do Databricks
Criar um cluster
Excluir permanentemente um cluster
Criar um emprego
Criar um trabalho que usa computação sem servidor
Gerenciar arquivos em volumes do Catálogo Unity
Listar grupos no nível da conta

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 trabalhador 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 permanentemente um cluster

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

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 bloco de anotações especificado no cluster especificado. À medida que o código é executado, ele obtém o caminho do bloco de anotações existente, o 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 Serverless Compute for Jobs:

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 Unity

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

Testar

Para testar seu código, use estruturas de teste 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 espaços de trabalho do Azure Databricks, use bibliotecas simuladas do Python como unittest.mock.

Gorjeta

O Databricks Labs fornece um plugin pytest para simplificar os testes de integração com o Databricks e um plugin pylint para garantir a qualidade do código.

O seguinte arquivo de exemplo chamado helpers.py contém uma create_cluster função 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

Dado o seguinte arquivo chamado main.py que chama a create_cluster função:

# 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 a seguir chamado test_helpers.py testa se a create_cluster função retorna a resposta esperada. Em vez de criar um cluster no espaço de trabalho de destino, esse teste simula um WorkspaceClient objeto, define as configurações do objeto simulado e, em seguida, passa o objeto simulado para a create_cluster função. 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 pytest comando a partir da 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 obter mais informações, consulte:

Documentação do Databricks SDK for Python
Exemplos de código adicionais
Referência das APIs do Databricks Workspace
Referência de APIs de conta do Databricks
Registo
Operações de longa duração
Respostas paginadas
Logon único com OAuth

Partilhar via

Databricks SDK para Python

Antes de começar

Introdução ao SDK do Databricks para Python

Venv

Poesia

Venv

Poesia

Venv

Poesia

Venv

Poesia

Venv

Poesia

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

Usar o SDK do Databricks para Python de um bloco de anotações do Azure Databricks

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

Etapa 2: Execute seu código

Usar utilitários Databricks

Exemplos de código

Criar um cluster

Excluir permanentemente um cluster

Criar um trabalho

Criar um trabalho que usa computação sem servidor

Gerenciar arquivos em volumes do Catálogo Unity

Listar grupos no nível da conta

Testar

Recursos adicionais

Comentários

Recursos adicionais