Panduan API Autoscaling Lakebase

Penting

Lakebase Autoscaling adalah versi terbaru Lakebase, dengan komputasi penskalaan otomatis, skala-ke-nol, percabangan, dan pemulihan instan. Untuk wilayah yang didukung, lihat Ketersediaan wilayah. 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)

Dalam API, komputasi disebut titik akhir. Untuk gambaran umum konseptual, lihat Komputasi dan titik akhir.

Tabel berikut memetakan konsep UI ke setara API mereka:

Konsep UI	Sumber daya atau bidang API	Documentation
Komputasi utama	Titik akhir dengan `endpoint_type: ENDPOINT_TYPE_READ_WRITE`	Mengelola komputasi
Replika baca	Titik akhir dengan `endpoint_type: ENDPOINT_TYPE_READ_ONLY`	Mengelola replika baca
Ketersediaan tinggi	`group` kolom (`EndpointGroupSpec`) pada spesifikasi titik akhir	Mengelola ketersediaan tinggi
Pengidentifikasi komputasi (UID, Nama sumber daya)	`uid` dan `name` (jalur sumber daya lengkap) pada objek Titik Akhir	Identifikasi Komputer

Operasi yang tersedia

Operasi	Metode	Titik akhir	Documentation
Membuat titik akhir	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Membuat replika baca
Memperbarui titik akhir	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Mengedit komputasi / Mengedit replika / bacaMengelola ketersediaan tinggi
Menghapus titik akhir	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Menghapus sebuah 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

Katalog

Operasi	Metode	Titik akhir	Documentation
Mendaftarkan database dengan Katalog Unity	`POST`	`/catalogs`	Mendaftarkan database
Pendaftaran katalog	`GET`	`/catalogs/{catalog_id}`	Periksa status pendaftaran
Menghapus pendaftaran katalog	`DELETE`	`/catalogs/{catalog_id}`	Membatalkan pendaftaran database

Nota

Mendaftar dan menghapus adalah operasi yang berjalan lama. Pantau operasi yang dikembalikan sampai done: true. Lihat Operasi jangka panjang.

Menghapus pendaftaran katalog tidak menghilangkan database Postgres yang mendasar.

Tabel yang Disinkronkan

Operasi	Metode	Titik akhir	Documentation
Membuat tabel yang disinkronkan	`POST`	`/synced_tables`	Membuat tabel yang disinkronkan
Dapatkan tabel yang disinkronkan	`GET`	`/synced_tables/{table_name}`	Periksa status sinkronisasi
Menghapus tabel yang disinkronkan	`DELETE`	`/synced_tables/{table_name}`	Menghapus tabel yang disinkronkan

Nota

table_name di jalur menggunakan format catalog.schema.table.

Buat dan hapus adalah operasi yang berjalan lama. Pantau operasi yang dikembalikan sampai done: true. Lihat Operasi jangka panjang.

Menghapus tabel yang disinkronkan hanya akan menghapus pendaftaran dari Katalog Unity. Hapus tabel Postgres secara terpisah untuk mengosongkan ruang.

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

Project izin ACL menggunakan standard Azure Databricks Permissions API, bukan jalur dasar /api/2.0/postgres/. Atur request_object_type ke database-projects dan request_object_id ke ID proyek Anda (misalnya, my-app).

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
from databricks.sdk.service.postgres import Project, ProjectSpec

w = WorkspaceClient()

# Start an operation (example: create project)
operation = w.postgres.create_project(
    project=Project(spec=ProjectSpec(pg_version=17)),
    project_id="my-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(
    new CreateProjectRequest()
        .setProjectId("my-project")
        .setProject(new Project()
            .setSpec(new ProjectSpec()
                .setPgVersion(17L)))
);
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 my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

# Later, check the operation status using the operation name from the response
databricks postgres get-operation projects/my-project/operations/<operation-id>

melengkung

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

Format respons:

{
  "name": "projects/my-project/operations/<operation-id>",
  "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/<operation-id>",
  "done": false
}

Polling untuk penyelesaian menggunakan GetOperation:

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Project, ProjectSpec

w = WorkspaceClient()

# Start an operation
operation = w.postgres.create_project(
    project=Project(spec=ProjectSpec(pg_version=17)),
    project_id="my-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(
    new CreateProjectRequest()
        .setProjectId("my-project")
        .setProject(new Project()
            .setSpec(new ProjectSpec()
                .setPgVersion(17L)))
);

// 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 my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

melengkung

# Poll the operation
curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
  -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

Lakebase dapat mengembalikan 409 Conflict kesalahan karena beberapa alasan:

Operasi pemeliharaan internal sedang berlangsung pada proyek.
Proyek ini telah mencapai batas operasi bersamaan.
Permintaan API Anda sendiri tumpang tindih. Misalnya, membuat cabang sebelum pembuatan cabang sebelumnya selesai.

Apa artinya:

Lakebase terkadang menjadwalkan operasi pemeliharaan pada proyek. Jika permintaan klien tiba saat salah satu operasi ini sedang berlangsung, Lakebase menolak permintaan baru dengan 409 Conflict kesalahan. Anda mungkin juga mendapatkan respons tersebut saat proyek telah mencapai kapasitas maksimal atau panggilan API Anda tumpang tindih.

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 atau kapasitas dibebaskan, 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-04-14

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)

Operasi yang tersedia

Peran

Katalog

Tabel yang Disinkronkan

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: