Azure Databricks REST API

Bu sayfa, Azure Databricks REST API'si, nasıl çağrılacağı ve bazı en iyi uygulamalar açıklanmaktadır.

Databricks REST API için tam referans için Databricks REST API referansına bakınız.

Note

Gelişmiş senaryolar dışında, Databricks nesnelerini programatik olarak yönetmek için Databricks REST API'si yerine Databricks SDK'ları veya Databricks CLI'sını kullanmayı önerir.

Workspace vs Account REST API'leri

Azure Databricks, iki REST API seti sağlar. Workspace API'leri, kümeler, işler, defterler ve Unity Kataloğu nesneleri gibi tek bir çalışma alanı içindeki kaynakları yönetir ve bunları ana bilgisayar olarak çalışma alanı URL'nizi kullanarak çağırırsınız. Hesap API'leri, kullanıcı ve grup oluşturma, çalışma alanı oluşturma, ağ ve faturalandırma yapılandırması ve hesap düzeyindeki Unity Kataloğu ayarları gibi hesap genelinde kaynakları yönetir ve bunları hesap konsolu giriş URL'si ve hesap kimliği ile çağırırsınız.

Her kümedeki işlemler için workspace API referansı ve hesap API referansına bakınız.

REST API çağırma

Bir Databricks REST API çağrısı aşağıdaki bileşenleri içerir:

  • Çalışma alanı mı yoksa hesap uç noktası mı olduğuna bağlı olarak, şunlardan biri:
  • REST API işlem türü, örneğin GET, POST, PATCH, , veya DELETE.
  • REST API işlem yolu, örneğin /api/2.0/clusters/get.
  • Databricks OAuth tokenı gibi kimlik doğrulama bilgileri.
  • REST API işlemi tarafından desteklenen herhangi bir talep yükü veya istek sorgusu parametreleri, örneğin bir kümenin kimliği.

REST API isteğinin nasıl yapılandırılacağı ve tercih ettiğiniz geliştirici aracı için yanıt yüklerinin nasıl ayrıştırılacağı hakkında bilgi almak için sağlayıcınızın dokümantasyonuna bakınız.

Örnek 1: Kümeleri alın

Aşağıdaki örnek, mevcut kümeler listesini döndürmek için Cluster, List uç noktasını çağırır. Çevre değişkeninin DATABRICKS_HOST Databricks çalışma alanı URL'nize ayarlandığını ve DATABRICKS_TOKEN Databricks token'ına ayarlandığını varsayar.

curl -X GET "$DATABRICKS_HOST/api/2.0/clusters/list" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN"

import requests
import os

headers = {"Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}"}
response = requests.get(f"{os.getenv('DATABRICKS_HOST')}/api/2.0/clusters/list", headers=headers)

print(response.json())

Örnek 2: Bir işi çalıştır

Aşağıdaki örnek, mevcut bir işin deneme çalıştırmasını tetiklemek için Job, Run Now endpoint'ini çağırır. Çevre değişkeninin DATABRICKS_HOST Databricks çalışma alanı URL'nize ayarlandığını ve DATABRICKS_TOKEN Databricks token'ına ayarlandığını varsayar.

curl -X POST "$DATABRICKS_HOST/api/2.1/jobs/run-now" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": 45678,
    "notebook_params": {
      "dry_run": "true",
      "start_date": "2026-08-27"
    }
  }'

import requests
import os

url = f"{os.getenv('DATABRICKS_HOST')}/api/2.1/jobs/run-now"
headers = {
    "Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}",
    "Content-Type": "application/json"
}
payload = {
    "job_id": 45678,
    "notebook_params": {"dry_run": "true", "start_date": "2026-08-27"}
}

response = requests.post(url, headers=headers, json=payload)
print(f"Run ID: {response.json().get('run_id')}")

Örnek 3: Hesap kullanıcılarını geri gönderin

Aşağıdaki örnek, Databricks hesabındaki kullanıcıları geri göndermek için Hesap Kullanıcısı, Listele uç noktasını çağırıyor:<account_id>

curl -X GET '<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users' \
  --header "Authorization: Bearer $OAUTH_TOKEN"

import requests
import os

url = "<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users"
headers = {"Authorization": f"Bearer {os.getenv('OAUTH_TOKEN')}"}

response = requests.get(url, headers=headers)
print(response.json())

En iyi uygulamalar

Aşağıdaki bölümler, çalışma alanınızdaki veri büyüdükçe bazı performans en iyi uygulamalarını açıklar.

API yanıtlarını sayfalandırın LIST

LIST API'ler sonuçları tek bir büyük yanıt yerine sayfalar olarak döndürür. Tam bir sonuç kümesini almak için ilk sayfayı talep edin, ardından yanıttaki tokenı kullanarak sonraki sayfaları talep edin, ta ki hiçbir token geri dönmeene kadar.

Tam bir sonuç kümesinin sayfaları arasında gezinmek için:

  • İsteğinizde max_results=0 ayarlayın. Bu, sunucunun uygun bir sayfa boyutunu seçmesini sağlar; bu, sayfa başına sabit sayıda sonuç istemekten daha verimlidir.
  • Her yanıttaki next_page_token alanını okuyun. Bir sonraki sayfayı istemek için, değerini page_token bir sonraki isteğinizin sorgu parametresine aktarın.
  • Bir yanıt next_page_token öğesini içermeyene veya onu boş bir değer olarak döndürene kadar tekrarlayın. Bu yanıt son sayfadır.
  • page_token öğesini ilk isteğe dahil etmeyin. Sadece takip talepleri için ekleyin.

Aşağıdaki örnek, bir şemadaki tüm tabloları Unity Catalog Table, listeleme uç noktasından almak için bu deseni kullanır. Aynı döngü herhangi bir LIST API için de çalışır. Yanıttaki yalnızca uç nokta ve dizi alanının adı değişir. Örneğin, Grants uç noktası sonuçları privilege_assignments dizisi içinde, tables yerine döndürür.

import requests

base_url = "https://example.cloud.databricks.com"  # No trailing slash
bearer_token = "<your-personal-access-token>"
catalog_name = "main"
schema_name = "default"


def list_tables(base_url, bearer_token, catalog_name, schema_name):
    endpoint = f"{base_url}/api/2.1/unity-catalog/tables"
    headers = {"Authorization": f"Bearer {bearer_token}"}
    params = {
        "catalog_name": catalog_name,
        "schema_name": schema_name,
        "max_results": 0,  # Let the server choose the page size.
    }

    tables = []
    while True:
        response = requests.get(endpoint, headers=headers, params=params)
        response.raise_for_status()
        body = response.json()

        tables.extend(body.get("tables", []))

        # Stop when the response no longer includes a page token.
        page_token = body.get("next_page_token")
        if not page_token:
            break
        params["page_token"] = page_token

    return tables

429 hız sınırı yanıtlarını yönetin

Databricks, çalışma alanlarının ağır yük altında yanıt vermesini sağlamak için REST API çağrılarında hız sınırları uygular. Adil kullanım ve erişilebilirliği desteklemek için sınırlar, uç nokta ve çalışma alanı başına uygulanır. Hız sınırını aşan bir istek, HTTP 429 Too Many Requests yanıtı döndürür.

429 yanıtlarını, üstel geri çekilme ve rastgele gecikme kullanarak yeniden deneyip sorunsuz bir şekilde işleyin:

  • Üstel bekleme: Bir 429 sonrasında, yeniden denemeden önce bekleyin ve sonraki her 429 sonrasında bekleme süresini iki katına çıkarın. Bir isteğin süresiz olarak yeniden denenmemesi için maksimum bekleme süresi ve maksimum yeniden deneme sayısı belirleyin.
  • Jitter: Her beklemeye küçük rastgele bir süre ekleyin. Jitter, birden fazla istemciden gelen yeniden denemeleri zamana yayarak hepsinin aynı anda yeniden deneme yapmasını ve tekrarlanan trafik patlamalarına neden olmasını önler.
  • Bir yanıt Retry-After üst bilgisi içeriyorsa, yeniden denemeden önce en az bu süre kadar bekleyin.

Çoğu HTTP istemci kütüphanesi bu yeniden deneme davranışını sizin için uygulayabilir. Algoritmanın arka planı için bkz. Üstel geri çekilme ve jitter.

Belirli API'lere uygulanan hız sınırları için, API hız sınırları bölümünde API hız sınırlarına bakınız.

Performans için yanıt alanlarını kesin

Bazı LIST API'ler, hesaplaması pahalı veya yanıtları büyük yapan alanlar döndürür. Bu alanlara ihtiyacınız olmadığında, onları çıkaran istek parametrelerini kullanarak yanıt boyutunu azaltabilir ve gecikmeyi artırır.

Örneğin, Unity Katalog Tabloları API'si aşağıdaki parametreleri destekler:

  • omit_properties=true: Yanıttaki her tablodan properties alanını çıkarır.
  • omit_columns=true: Yanıttaki her tablodan columns alanını hariç tutar.

Eğer sadece isimlerini almak için tabloları listeliyorsanız, her iki parametreyi de ayarlamak daha küçük bir yanıt verir ve tabloları daha hızlı listeler. Her uç noktanın desteklediği alan kesme parametreleri için REST API referansını kontrol edin.

Ek kaynaklar

  • Last updated on