Azure Databricks REST API

Halaman ini menjelaskan Azure Databricks REST API, cara memanggilnya, dan beberapa praktik terbaik.

Untuk referensi lengkap untuk Databricks REST API, lihat referensi Databricks REST API.

Nota

Kecuali untuk skenario lanjutan, Databricks merekomendasikan penggunaan Databricks SDK atau Databricks CLI daripada Databricks REST API untuk mengelola objek Databricks secara programatik.

REST API Workspace vs Akun

Azure Databricks menyediakan dua set API REST. API Workspace mengelola sumber daya di dalam satu workspace, seperti cluster, job, notebook, dan objek Unity Catalog, dan Anda memanggilnya menggunakan URL workspace Anda sebagai host. API akun mengelola sumber daya seluruh akun, seperti penyediaan pengguna dan grup, pembuatan workspace, konfigurasi jaringan dan penagihan, serta pengaturan Unity Catalog tingkat akun, dan Anda memanggilnya menggunakan URL login konsol akun dan ID akun Anda.

Untuk operasi yang tersedia di setiap set, lihat referensi API workspace dan referensi API akun.

Memanggil API REST

Panggilan API REST Databricks mencakup komponen berikut:

  • Bergantung pada apakah endpoint tersebut merupakan endpoint workspace atau endpoint akun, pilih salah satu berikut:
  • Jenis operasi API REST, seperti GET, POST, PATCH, atau DELETE.
  • Jalur operasi API REST, seperti /api/2.0/clusters/get.
  • Informasi autentikasi Databricks, seperti token OAuth Databricks.
  • Setiap muatan permintaan atau parameter kueri permintaan yang didukung oleh operasi API REST, seperti ID klaster.

Untuk informasi tentang cara menyusun permintaan REST API dan cara mengurai payload respons untuk alat pengembang pilihan Anda, lihat dokumentasi penyedia Anda.

Contoh 1: Dapatkan klaster

Contoh berikut memanggil endpoint Cluster, List untuk mengembalikan daftar cluster yang tersedia. Ini mengasumsikan bahwa variabel lingkungan DATABRICKS_HOST ditetapkan ke URL ruang kerja Databricks Anda dan DATABRICKS_TOKEN ditetapkan ke token Databricks.

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

Contoh 2: Jalankan pekerjaan

Contoh berikut memanggil endpoint Job, Run Now untuk memicu dry run dari pekerjaan yang sudah ada. Ini mengasumsikan bahwa variabel lingkungan DATABRICKS_HOST disetel ke URL ruang kerja Databricks Anda dan DATABRICKS_TOKEN disetel ke token Databricks.

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

Contoh 3: Pengguna akun yang kembali

Contoh berikut memanggil endpoint Daftar Pengguna Akun untuk mengembalikan pengguna di akun Databricks yang diidentifikasi oleh <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())

Praktik terbaik

Bagian berikut menjelaskan beberapa praktik terbaik kinerja seiring data di workspace Anda bertambah.

Paginasikan respons API LIST

LIST API mengembalikan hasil dalam bentuk halaman, bukan satu respons besar. Untuk mengambil hasil lengkap, minta halaman pertama, lalu gunakan token dalam respons untuk meminta setiap halaman berikutnya hingga tidak ada token yang dikembalikan.

Untuk menelusuri set hasil lengkap:

  • Tetapkan max_results=0 dalam permintaan Anda. Ini memungkinkan server memilih ukuran halaman yang sesuai, yang lebih efisien daripada meminta jumlah hasil tetap per halaman.
  • Baca next_page_token kolom dari setiap respons. Untuk meminta halaman berikutnya, sertakan nilainya dalam parameter kueri page_token pada permintaan berikutnya.
  • Ulangi hingga respons tidak menyertakan next_page_token atau mengembalikannya dengan nilai kosong. Jawaban itu adalah halaman terakhir.
  • Jangan masukkan page_token dalam permintaan pertama. Tambahkan hanya untuk permintaan tindak lanjut.

Contoh berikut menggunakan pola ini untuk mengambil setiap tabel dalam sebuah skema dari endpoint Unity Catalog Table, List. Loop yang sama berlaku untuk API apa pun LIST . Hanya endpoint dan nama field array pada respons yang berubah. Misalnya, endpoint Grants mengembalikan hasil dalam array privilege_assignments alih-alih tables.

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

Tangani 429 respons dengan batas laju

Databricks memberlakukan batas laju pada panggilan REST API untuk menjaga workspace tetap responsif di bawah beban berat. Batasan diterapkan per endpoint dan per workspace untuk mendukung penggunaan yang adil dan ketersediaan. Permintaan yang melebihi batas laju akan mengembalikan respons HTTP 429 Too Many Requests .

Tangani respons 429 dengan baik dengan mencoba kembali menggunakan penundaan eksponensial dan jitter:

  • Exponential backoff: Setelah 429, tunggu sebelum mencoba ulang, dan gandakan waktu tunggu setelah setiap 429. Atur waktu tunggu maksimum dan jumlah percobaan ulang maksimum agar permintaan tidak mencoba ulang tanpa batas waktu.
  • Jitter: Tambahkan sedikit waktu acak pada setiap penantian. Jitter mengatur agar percobaan ulang dari beberapa klien tersebar, sehingga tidak semuanya mencoba ulang pada saat yang sama dan menyebabkan lonjakan trafik yang berulang.
  • Jika sebuah respons menyertakan Retry-After header, tunggu setidaknya selama itu sebelum mencoba lagi.

Sebagian besar pustaka klien HTTP dapat menerapkan perilaku percobaan ulang ini untuk Anda. Untuk informasi latar belakang tentang algoritma ini, lihat Backoff eksponensial dan jitter.

Untuk batas tarif yang berlaku untuk API tertentu, lihat batas tingkat API dalam batas laju API.

Potong bidang respons untuk performa

Beberapa LIST API mengembalikan kolom yang mahal secara komputasi atau yang memperbesar ukuran respons. Saat Anda tidak membutuhkan kolom-kolom ini, gunakan parameter permintaan yang menghilangkannya untuk mengurangi ukuran respons dan meningkatkan latensi.

Sebagai contoh, API Tabel Katalog Unity mendukung parameter berikut:

  • omit_properties=true: Menghilangkan kolom properties dari setiap tabel dalam respons.
  • omit_columns=true: Menghilangkan kolom columns dari setiap tabel pada respons.

Jika Anda mendaftar tabel hanya untuk mengambil nama tabel, menyetel kedua parameter tersebut akan menghasilkan respons yang lebih kecil dan membuat daftar tabel ditampilkan lebih cepat. Periksa referensi REST API untuk parameter pemangkasan kolom yang didukung oleh masing-masing endpoint.

Sumber daya tambahan

  • Last updated on