Panduan API Autoscaling Lakebase

Penting

Lakebase Autoscaling tersedia di wilayah berikut: eastus, , , eastus2centralus, southcentralus, westus, westus2canadacentral, brazilsouth, , northeurope, uksouth, westeurope, , , australiaeast, , centralindia, . southeastasia

Lakebase Autoscaling adalah versi terbaru Lakebase, dengan komputasi penskalaan otomatis, skala-ke-nol, percabangan, dan pemulihan instan. Jika Anda adalah pengguna Lakebase Provisioned, lihat Lakebase Provisioned.

Halaman ini memberikan gambaran umum tentang LAKEBASE Autoscaling API, termasuk autentikasi, titik akhir yang tersedia, dan pola umum untuk bekerja dengan REST API, Databricks CLI, dan Databricks SDK (Python, Java, Go).

Untuk referensi API lengkap, lihat dokumentasi API Postgres.

Penting

Lakebase Postgres API berada di Beta. Titik akhir, parameter, dan perilaku API dapat berubah.

Authentication

LAKEBASE Autoscaling API menggunakan autentikasi OAuth tingkat ruang kerja untuk mengelola infrastruktur proyek (membuat proyek, mengonfigurasi pengaturan, dll.).

Nota

Dua jenis konektivitas: API ini untuk manajemen platform (membuat proyek, cabang, komputasi). Untuk akses database (menyambungkan ke data kueri):

Klien SQL (psql, pgAdmin, DBeaver): Gunakan token OAuth Lakebase atau kata sandi Postgres. Lihat Autentikasi.
API Data (RESTful HTTP): Gunakan token Lakebase OAuth. Lihat API Data.
Driver bahasa pemrograman (psycopg, SQLAlchemy, JDBC): Gunakan token OAuth Lakebase atau kata sandi Postgres. Lihat Panduan Memulai Cepat.

Untuk penjelasan lengkap tentang dua lapisan autentikasi ini, lihat Arsitektur autentikasi.

Menyiapkan autentikasi

Autentikasi menggunakan Databricks CLI:

databricks auth login --host https://your-workspace.cloud.databricks.com

Ikuti perintah browser untuk masuk. CLI menyimpan token OAuth Anda di ~/.databricks/token-cache.json.

Kemudian pilih metode akses Anda:

Python SDK

SDK menggunakan autentikasi terpadu dan secara otomatis menangani token OAuth:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK

SDK menggunakan autentikasi terpadu dan secara otomatis menangani token OAuth:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

antarmuka baris perintah (CLI)

Perintah secara otomatis menggunakan token yang di-cache:

databricks postgres list-projects

melengkung

Buat token untuk panggilan API langsung:

export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

curl -X GET "https://your-workspace.cloud.databricks.com/api/2.0/postgres/projects" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Token OAuth kedaluwarsa setelah satu jam. Regenerasi sesuai kebutuhan.

Untuk detail selengkapnya, lihat Mengotorisasi akses pengguna ke Databricks dengan OAuth.

Titik akhir yang tersedia (Beta)

Semua titik akhir menggunakan jalur /api/2.0/postgres/dasar .

Proyek

Operasi	Metode	Titik akhir	Documentation
Membuat proyek	`POST`	`/projects`	Membuat proyek
Memperbarui proyek	`PATCH`	`/projects/{project_id}`	Pengaturan umum
Menghapus proyek	`DELETE`	`/projects/{project_id}`	Menghapus proyek
Dapatkan proyek	`GET`	`/projects/{project_id}`	Dapatkan detail proyek
Mencantumkan proyek	`GET`	`/projects`	Mencantumkan proyek

Cabang

Operasi	Metode	Titik akhir	Documentation
Membuat cabang	`POST`	`/projects/{project_id}/branches`	Membuat cabang
Memperbarui cabang	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	Memperbarui pengaturan cabang
Hapus cabang	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	Menghapus cabang
Ambil cabang	`GET`	`/projects/{project_id}/branches/{branch_id}`	Lihat cabang
Daftar cabang	`GET`	`/projects/{project_id}/branches`	Daftar cabang

Titik akhir (Komputasi dan Replika Baca)

Operasi	Metode	Titik akhir	Documentation
Membuat titik akhir	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Membuat komputasi / Membuat replika baca
Memperbarui titik akhir	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Mengedit mesin komputasi / Mengedit replika baca
Menghapus titik akhir	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Menghapus komputasi / Menghapus replika baca
Dapatkan titik akhir	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Menampilkan komputasi
Mencantumkan titik akhir	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Menampilkan komputasi

Peran

Operasi	Metode	Titik akhir	Documentation
Mencantumkan peran	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	Menampilkan peran Postgres
Membuat peran	`POST`	`/projects/{project_id}/branches/{branch_id}/roles`	Membuat peran OAuth \| Membuat peran kata sandi
Dapatkan peran	`GET`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Menampilkan peran Postgres
Memperbarui peran	`PATCH`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Memperbarui peran
Menghapus peran	`DELETE`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Menghapus peran

Kredensial Database

Operasi	Metode	Titik akhir	Documentation
Hasilkan kredensial database	`POST`	`/credentials`	Autentikasi token OAuth

Operasi

Operasi	Metode	Titik akhir	Documentation
Dapatkan operasi	`GET`	`/projects/{project_id}/operations/{operation_id}`	Lihat contoh di bawah ini

Izin

Izin Project ACL menggunakan API Izin Azure Databricks standar, bukan /api/2.0/postgres/ jalur dasar. Atur request_object_type ke database-projects dan request_object_id ke ID proyek.

Operasi	Metode	Titik akhir	Documentation
Mendapatkan izin proyek	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	Referensi API Izin
Memperbarui izin proyek	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	Referensi API Izin
Mengganti izin proyek	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	Referensi API Izin

Tingkat izin yang dapat diberikan untuk proyek Lakebase adalah CAN_USE dan CAN_MANAGE. CAN_CREATE adalah tingkat yang diwariskan dan tidak dapat diatur melalui API. Lihat Tingkat izin.

Untuk contoh penggunaan dan setara CLI/SDK/Terraform, lihat Memberikan izin secara terprogram.

Dapatkan operasi

Periksa status operasi yang berjalan lama dengan nama sumber dayanya.

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Start an operation (example: create project)
operation = w.postgres.create_project(...)
print(f"Operation started: {operation.name}")

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

Java SDK

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation (example: create project)
CreateProjectOperation operation = w.postgres().createProject(...);
System.out.println("Operation started: " + operation.getName());

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

antarmuka baris perintah (CLI)

CLI secara otomatis menunggu operasi selesai secara default. Gunakan --no-wait untuk melewati polling:

# Create project without waiting
databricks postgres create-project --no-wait ...

# Later, check the operation status
databricks postgres get-operation projects/my-project/operations/abc123

melengkung

# Get operation status
curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/abc123" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Format respons:

{
  "name": "projects/my-project/operations/abc123",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/databricks.postgres.v1.Project",
    "name": "projects/my-project",
    ...
  }
}

Bidang:

done: false saat sedang berlangsung, true ketika selesai
response: Berisi hasil ketika done adalah true
error: Berisi detail kesalahan jika operasi gagal

Pola umum

Penamaan sumber daya

Sumber daya mengikuti pola penamaan hierarkis di mana sumber daya anak dibatasi oleh induknya.

Proyek menggunakan format ini:

projects/{project_id}

Sumber daya anak seperti sumber daya operasional ditempatkan di bawah proyek induknya.

projects/{project_id}/operations/{operation_id}

Ini berarti Anda memerlukan ID proyek induk untuk mengakses operasi atau sumber daya anak lainnya.

ID sumber daya:

Saat membuat sumber daya, Anda harus memberikan ID sumber daya (seperti my-app) untuk parameter project_id, branch_id, atau endpoint_id. ID ini menjadi bagian dari jalur sumber daya dalam panggilan API (seperti projects/my-app/branches/development).

Anda dapat secara opsional menyediakan display_name untuk memberi sumber daya Anda label yang lebih deskriptif. Jika Anda tidak menentukan nama tampilan, sistem akan menggunakan ID sumber daya Anda sebagai nama tampilan.

:::tip Menemukan sumber daya di UI

Untuk menemukan proyek di UI Lakebase, cari nama tampilannya di daftar proyek. Jika Anda tidak memberikan nama tampilan kustom saat membuat proyek, cari proyek Anda project_id (seperti "aplikasi saya").

:::

Nota

ID sumber daya tidak dapat diubah setelah pembuatan.

Persyaratan:

Panjangnya harus 1-63 karakter
Huruf kecil, digit, dan tanda hubung saja
Tidak dapat memulai atau mengakhiri dengan tanda hubung
Contoh: my-app, analytics-db, customer-123

Operasi jangka panjang (LRO)

Operasi buat, perbarui, dan hapus mengembalikan databricks.longrunning.Operation objek yang menyediakan status penyelesaian.

Contoh respons operasi:

{
  "name": "projects/my-project/operations/abc123",
  "done": false
}

Polling untuk penyelesaian menggunakan GetOperation:

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Start an operation
operation = w.postgres.create_project(...)

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

Java SDK

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation
CreateProjectOperation operation = w.postgres().createProject(...);

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

antarmuka baris perintah (CLI)

CLI secara otomatis menunggu operasi selesai secara default. Gunakan --no-wait untuk segera kembali:

databricks postgres create-project --no-wait ...

melengkung

# Poll the operation
curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/abc123" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq '.done'

Memeriksa setiap beberapa detik hingga done menjadi true.

Memperbarui masker

Operasi pembaruan memerlukan parameter yang update_mask menentukan bidang mana yang akan diubah. Ini mencegah penimpaan secara tidak sengaja pada bidang yang tidak terkait.

Perbedaan format:

Metode	Rancangan	Example
REST API	Parameter pencarian	`?update_mask=spec.display_name`
Python SDK	Objek FieldMask	`update_mask=FieldMask(field_mask=["spec.display_name"])`
antarmuka baris perintah (CLI)	Argumen posisi	`update-project NAME spec.display_name`

Penanganan kesalahan

Lakebase API mengembalikan kode status HTTP standar.

409: Operasi yang bertentangan

Pesan kesalahan:

project already has running conflicting operations, scheduling of new ones is prohibited

Apa artinya:

Lakebase terkadang menjadwalkan operasi pemeliharaan internal pada proyek. Jika permintaan klien tiba saat salah satu operasi internal ini sedang berlangsung, Lakebase dapat menolak permintaan baru dengan kesalahan 409 Conflict .

Ini adalah perilaku yang diharapkan. Klien harus siap untuk mencoba kembali permintaan ketika kesalahan ini terjadi.

Apa yang harus dilakukan:

Ulangi permintaan tersebut. Ketika operasi internal selesai, Lakebase menerima permintaan baru untuk proyek.

Gunakan penundaan eksponensial untuk percobaan ulang: tunggu interval singkat sebelum coba lagi pertama, kemudian lipat gandakan waktu tunggu pada setiap upaya berikutnya. Interval awal 100 milidetik dengan maksimum 30 detik adalah default yang wajar.

Python SDK

import time
from databricks.sdk import WorkspaceClient
from databricks.sdk.errors import ResourceConflict
from databricks.sdk.service.postgres import Branch, BranchSpec

w = WorkspaceClient()

def retry_on_conflict(fn, max_attempts=5, base_delay=0.1):
    """Retry a Lakebase API call when a conflicting operation is in progress."""
    for attempt in range(max_attempts):
        try:
            return fn()
        except ResourceConflict:
            if attempt == max_attempts - 1:
                raise
            wait = base_delay * (2 ** attempt)
            print(f"Conflicting operation in progress. Retrying in {wait}s...")
            time.sleep(wait)

# Example: create a branch with retry
branch = retry_on_conflict(
    lambda: w.postgres.create_branch(
        parent="projects/my-project",
        branch=Branch(spec=BranchSpec(no_expiry=True)),
        branch_id="my-branch",
    ).wait()
)

melengkung

# Retry with exponential backoff on 409 responses
retry_on_conflict() {
  local cmd=("$@")
  local max_attempts=5
  local delay=0.1
  local attempt=0

  while [ $attempt -lt $max_attempts ]; do
    response=$(curl -s -w "\n%{http_code}" "${cmd[@]}")
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | sed '$d')

    if [ "$http_code" -ne 409 ]; then
      echo "$body"
      return 0
    fi

    attempt=$((attempt + 1))
    if [ $attempt -eq $max_attempts ]; then
      echo "Max retries reached. Last response: $body" >&2
      return 1
    fi

    echo "Conflicting operation in progress. Retrying in ${delay}s..." >&2
    sleep "$delay"
    delay=$((delay * 2))
  done
}

# Example: create a branch with retry
retry_on_conflict \
  -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches?branch_id=my-branch" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"no_expiry": true}}'

Nota

409 Conflict pada permintaan API Lakebase menunjukkan bahwa permintaan tidak diterima, bukan bahwa permintaan tersebut telah diterapkan. Selalu verifikasi status sumber daya setelah berhasil mencoba kembali dengan memanggil titik akhir yang GET sesuai.

SDK dan infrastruktur sebagai kode

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-28

Bagikan melalui

Panduan API Autoscaling Lakebase

Authentication

Menyiapkan autentikasi

Python SDK

Java SDK

antarmuka baris perintah (CLI)

melengkung

Titik akhir yang tersedia (Beta)

Proyek

Cabang

Titik akhir (Komputasi dan Replika Baca)

Peran

Kredensial Database

Operasi

Izin

Dapatkan operasi

Python SDK

Java SDK

antarmuka baris perintah (CLI)

melengkung

Pola umum

Penamaan sumber daya

Operasi jangka panjang (LRO)

Python SDK

Java SDK

antarmuka baris perintah (CLI)

melengkung

Memperbarui masker

Penanganan kesalahan

409: Operasi yang bertentangan

Python SDK

melengkung

SDK dan infrastruktur sebagai kode

Saran dan Komentar

Sumber Daya Tambahan: