Lakebase Otomatik Ölçeklendirme API'si kılavuzu

Önemli

Lakebase Otomatik Ölçeklendirme, otomatik ölçeklendirme işlemi, sıfıra ölçeklendirme, dallanma ve anında geri yükleme ile Lakebase'in en son sürümüdür. Desteklenen bölgeler için bkz . Bölge kullanılabilirliği. Lakebase Tedarik Edilmiş bir kullanıcıysanız, bkz. Lakebase Tedarik Edilmiş.

Bu sayfada, kimlik doğrulaması, kullanılabilir uç noktalar ve REST API, Databricks CLI ve Databricks SDK'ları (Python, Java, Go) ile çalışmaya yönelik yaygın desenler de dahil olmak üzere Lakebase Otomatik Ölçeklendirme API'sine genel bir bakış sağlanır.

TAM API başvurusu için Postgres API belgelerine bakın.

Önemli

Lakebase Postgres API'si Beta sürümündedir. API uç noktaları, parametreler ve davranışlar değiştirilebilir.

Authentication

Lakebase Otomatik Ölçeklendirme API'sinde proje altyapısını yönetmek (proje oluşturma, ayarları yapılandırma vb.) için çalışma alanı düzeyinde OAuth kimlik doğrulaması kullanılır.

Uyarı

İki bağlantı türü: Bu API platform yönetimine yöneliktir (projeler, dallar, hesaplamalar oluşturma). Veritabanı erişimi için (sorgu verilerine bağlanma):

SQL istemcileri (psql, pgAdmin, DBeaver): Lakebase OAuth belirteçlerini veya Postgres parolalarını kullanın. Bkz. Kimlik doğrulaması.
Veri API'si (RESTful HTTP): Lakebase OAuth belirteçlerini kullanın. Bkz. Veri API'si.
Programlama dili sürücüleri (psycopg, SQLAlchemy, JDBC): Lakebase OAuth belirteçlerini veya Postgres parolalarını kullanın. Bkz. Hızlı Başlangıç.

Bu iki kimlik doğrulama katmanının tam açıklaması için bkz. Kimlik doğrulama mimarisi.

Kimlik doğrulamayı ayarlama

Databricks CLI kullanarak kimlik doğrulaması:

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

Oturum açmak için tarayıcı istemlerini izleyin. CLI, OAuth belirtecinizi konumunda ~/.databricks/token-cache.jsonönbelleğe alır.

Ardından erişim yönteminizi seçin:

Python SDK'sı

SDK birleşik kimlik doğrulaması kullanır ve OAuth belirteçlerini otomatik olarak işler:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK'sı

SDK birleşik kimlik doğrulaması kullanır ve OAuth belirteçlerini otomatik olarak işler:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

Komutlar önbelleğe alınmış belirteci otomatik olarak kullanır:

databricks postgres list-projects

Kıvrım

Doğrudan API çağrıları için belirteç oluşturma:

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

OAuth belirteçlerinin süresi bir saat sonra dolar. Gerektiğinde yeniden oluşturun.

Daha fazla ayrıntı için bkz. OAuth ile Databricks'e kullanıcı erişimini yetkilendirme.

Kullanılabilir uç noktalar (Beta)

Tüm uç noktalar temel yolunu /api/2.0/postgres/kullanır.

Projeler

Operation	Yöntem	Bitiş noktası	Documentation
Proje oluşturma	`POST`	`/projects`	Bir proje oluştur
Projeyi güncelleştirme	`PATCH`	`/projects/{project_id}`	Genel ayarlar
Projeyi silme	`DELETE`	`/projects/{project_id}`	Bir projeyi silme
Projeyi al	`GET`	`/projects/{project_id}`	Proje ayrıntılarını alma
Projeleri listeleme	`GET`	`/projects`	Projeleri listeleme

Dallanmalar

Operation	Yöntem	Bitiş noktası	Documentation
Dal oluşturma	`POST`	`/projects/{project_id}/branches`	Dal oluştur
Dalı güncelle	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	Dal ayarlarını güncelleştirme
Dalı sil	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	Bir dalı sil
Dalı getir	`GET`	`/projects/{project_id}/branches/{branch_id}`	Dalları görüntüle
Dalları listele	`GET`	`/projects/{project_id}/branches`	Şubeleri listele

Uç Noktalar (İşlemler ve Okuma Çoğaltmaları)

API'de işlem uç nokta olarak adlandırılır. Kavramsal genel bakış için bkz. İşlemler ve uç noktalar.

Aşağıdaki tablo, kullanıcı arabirimi kavramlarını API eşdeğerleriyle eşler:

KULLANıCı arabirimi kavramı	API kaynağı veya alanı	Documentation
Birincil hesaplama	Son nokta ile `endpoint_type: ENDPOINT_TYPE_READ_WRITE`	İşlemleri yönetme
Okuma amaçlı çoğaltma	Son nokta ile `endpoint_type: ENDPOINT_TYPE_READ_ONLY`	Okuma amaçlı çoğaltmaları yönetme
Yüksek kullanılabilirlik	`group` alan (`EndpointGroupSpec`) uç nokta belirtiminde	Yüksek kullanılabilirliği yönetme
İşlem tanımlayıcıları (UID, Kaynak adı)	`uid` ve `name` (tam kaynak yolu) Uç Nokta nesnesinde	İşlem tanımlayıcıları

Kullanılabilir işlemler

Operation	Yöntem	Bitiş noktası	Documentation
Uç nokta oluşturma	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Okuma replikası oluşturma
Uç noktayı güncelleştirme	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	İşlem düzenleme / Okuma çoğaltmayı düzenleme / Yüksek kullanılabilirliği yönetme
Uç noktayı silme	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Okuma amaçlı çoğaltmayı silme
Uç noktayı alma	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Bilgisayarları görüntüle
Uç noktaları listeleme	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Bilgisayarları görüntüle

Rolleri

Operation	Yöntem	Bitiş noktası	Documentation
Rolleri listeleme	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	Postgres rollerini görüntüleme
Rol oluşturma	`POST`	`/projects/{project_id}/branches/{branch_id}/roles`	OAuth rolü oluştur \| Parola rolü oluştur
Rol alma	`GET`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Postgres rollerini görüntüleme
Rolü güncelleştirme	`PATCH`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Rolü güncelleştirme
Rolü sil	`DELETE`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Bir rolü sil

Katalog

Operation	Yöntem	Bitiş noktası	Documentation
Unity Kataloğu'yla veritabanını kaydetme	`POST`	`/catalogs`	Veritabanını kaydetme
Katalog kaydını alma	`GET`	`/catalogs/{catalog_id}`	Kayıt durumunu denetleme
Katalog kaydını silme	`DELETE`	`/catalogs/{catalog_id}`	Veritabanının kaydını kaldırma

Uyarı

Kaydetme ve silme işlemleri uzun süre çalışan işlemlerdir. Döndürülen işlemi done: true'e kadar sorgulayın. Bkz. Uzun süre çalışan işlemler.

Katalog kaydının silinmesi, temel alınan Postgres veritabanını bırakmaz.

Eşitlenmiş Tablolar

Operation	Yöntem	Bitiş noktası	Documentation
Eşitlenmiş tablo oluşturma	`POST`	`/synced_tables`	Eşitlenmiş tablo oluşturma
Eşitlenmiş tabloyu alma	`GET`	`/synced_tables/{table_name}`	Eşitleme durumunu denetleme
Eşitlenen tabloyu silme	`DELETE`	`/synced_tables/{table_name}`	Eşitlenmiş tabloyu silme

Uyarı

table_name yolunda catalog.schema.table biçimi kullanır.

Oluşturma ve silme işlemleri uzun süre çalışan işlemlerdir. Döndürülen işlemi done: true'e kadar sorgulayın. Bkz. Uzun süre çalışan işlemler.

Eşitlenmiş bir tablo silindiğinde yalnızca Unity Kataloğu kaydı kaldırılır. Yer açmak için Postgres tablosunu ayrı olarak bırakın.

Veritabanı Kimlik Bilgileri

Operation	Yöntem	Bitiş noktası	Documentation
Veritabanı kimlik bilgisi oluşturma	`POST`	`/credentials`	OAuth jetonu kimlik doğrulaması

Işlem

Operation	Yöntem	Bitiş noktası	Documentation
getirme işlemi	`GET`	`/projects/{project_id}/operations/{operation_id}`	Aşağıdaki örne bakın

İzinler

Project ACL izinleri, standart Azure Databricks İzinleri API'sini, /api/2.0/postgres/ temel yolunu değil, kullanır. request_object_type'yi database-projects olarak ve request_object_id'yi proje kimliğiniz olarak ayarlayın (örneğin, my-app).

Operation	Yöntem	Bitiş noktası	Documentation
Proje izinlerini alma	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	İzinler API'si başvurusu
Proje izinlerini güncelleştirme	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	İzinler API'si başvurusu
Proje izinlerini değiştirme	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	İzinler API'si başvurusu

Lakebase projeleri için verilebilir izin düzeyleri CAN_USE ve CAN_MANAGE'dir. CAN_CREATE devralınan bir düzeydir ve API aracılığıyla ayarlanamaz. Bkz. İzin düzeyleri.

Kullanım örnekleri ve CLI/SDK/Terraform eşdeğerleri için bkz. Program aracılığıyla izin verme.

getirme işlemi

Uzun süre çalışan bir işlemin durumunu kaynak adına göre denetleyin.

Python SDK'sı

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'sı

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

CLI

CLI, işlemlerin varsayılan olarak tamamlanmasını otomatik olarak bekler. Yoklamayı atlamak için kullanın --no-wait :

# 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>

Kıvrım

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

Yanıt biçimi:

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

Alanları:

done: false devam ederken, true tamamlandığında
response: donetrue olduğunda sonucu içerir
error: İşlem başarısız olursa hata ayrıntılarını içerir

Ortak desenler

Kaynak adlandırma

Kaynaklar, alt kaynakların üst kaynakların kapsamına dahil olduğu hiyerarşik bir adlandırma modelini izler.

Projeler şu biçimi kullanır:

projects/{project_id}

Ana proje altında işlemler gibi alt kaynaklar konumlandırılmıştır.

projects/{project_id}/operations/{operation_id}

Bu, işlemlere veya diğer alt kaynaklara erişmek için üst proje kimliğine ihtiyacınız olduğu anlamına gelir.

Kaynak Kimlikleri:

Kaynak oluştururken my-app, project_id veya branch_id parametresi için bir kaynak kimliği (örneğin endpoint_id) sağlamanız gerekir. Bu kimlik, API çağrılarındaki kaynak yolunun bir parçası olur (örneğin projects/my-app/branches/development).

Kaynağınıza daha açıklayıcı bir etiket vermek için isteğe bağlı olarak bir display_name sağlayabilirsiniz. Görünen ad belirtmezseniz sistem, görünen ad olarak kaynak kimliğinizi kullanır.

:::tip Kullanıcı arabirimindeki kaynakları bulma

Lakebase kullanıcı arabiriminde bir projeyi bulmak için proje listesinde görünen adını arayın. Projeyi oluştururken özel bir görünen ad sağlamadıysanız, "project_id" (örneğin "uygulamam") için arama yapın.

:::

Uyarı

Kaynak kimlikleri oluşturulduktan sonra değiştirilemez.

Gereksinimler:

1-63 karakter uzunluğunda olmalıdır
Yalnızca küçük harfler, basamaklar ve kısa çizgiler
Kısa çizgiyle başlanamaz veya bitemez
Örnekler: my-app, analytics-db, customer-123

Uzun süre çalışan işlemler (LRO'lar)

Oluşturma, güncelleştirme ve silme işlemleri, tamamlanma durumu sağlayan bir databricks.longrunning.Operation nesne döndürür.

Örnek işlem yanıtı:

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": false
}

GetOperation kullanarak tamamlanma durumunu sorgulayın:

Python SDK'sı

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'sı

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

CLI

CLI, işlemlerin varsayılan olarak tamamlanmasını otomatik olarak bekler. Hemen dönmek için kullanın --no-wait :

databricks postgres create-project my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

Kıvrım

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

Her birkaç saniyede bir done’yi sorgulayın, ta ki true olana kadar.

Maskeleri güncelleştirme

Güncelleştirme işlemleri, hangi alanların değiştirileceğini belirten bir update_mask parametre gerektirir. Bu, ilgisiz alanların üzerine yanlışlıkla yazılmasını önler.

Biçim farklılıkları:

Yöntem	Biçim	Example
REST API	Sorgu parametresi	`?update_mask=spec.display_name`
Python SDK'sı	FieldMask adlı nesne	`update_mask=FieldMask(field_mask=["spec.display_name"])`
CLI	Konum argümanı	`update-project NAME spec.display_name`

Hata yönetimi

Lakebase API'sinde standart HTTP durum kodları döndürülüyor.

409: Çakışan işlemler

Lakebase birkaç nedenden dolayı hata 409 Conflict döndürebilir:

Projede bir iç bakım işlemi devam ediyor.
Proje eşzamanlı işlem sınırına ulaştı.
Kendi API istekleriniz çakışıyor. Örneğin, önceki dal oluşturma işlemi tamamlanmadan dal oluşturma.

Anlamı:

Lakebase bazen projelerde bakım işlemleri için zamanlama yapar. Bu işlemlerden biri devam ederken bir istemci isteği gelirse Lakebase yeni isteği bir 409 Conflict hatayla reddeder. Proje kapasitede olduğunda veya API çağrılarınız çakıştığında da bu yanıtı alabilirsiniz.

Bu beklenen bir davranıştır. İstemciler, bu hata oluştuğunda istekleri yeniden denemeye hazır olmalıdır.

Yapılması gerekenler:

İsteği yeniden deneyin. İç işlem tamamlandığında veya kapasite boşaltıldığında Lakebase proje için yeni istekleri kabul eder.

Yeniden denemeler için üstel geri almayı kullanın: İlk yeniden denemeden önce kısa bir süre bekleyin, ardından sonraki her denemede iki kez bekleyin. Başlangıç aralığı en fazla 30 saniye olan 100 milisaniyelik bir başlangıç aralığı makul bir varsayılan değerdir.

Python SDK'sı

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

Kıvrım

# 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}}'

Uyarı

409 Conflict Lakebase API isteği, isteğin kabul edilmediği anlamına gelir, uygulandığı değil. Başarılı bir yeniden denemeden sonra her zaman ilgili GET uç noktayı çağırarak kaynak durumunu doğrulayın.

SDK'lar ve kod olarak altyapı

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-14

Lakebase Otomatik Ölçeklendirme API'si kılavuzu

Authentication

Kimlik doğrulamayı ayarlama

Python SDK'sı

Java SDK'sı

CLI

Kıvrım

Kullanılabilir uç noktalar (Beta)

Projeler

Dallanmalar

Uç Noktalar (İşlemler ve Okuma Çoğaltmaları)

Kullanılabilir işlemler

Rolleri

Katalog

Eşitlenmiş Tablolar

Veritabanı Kimlik Bilgileri

Işlem

İzinler

getirme işlemi

Python SDK'sı

Java SDK'sı

CLI

Kıvrım

Ortak desenler

Kaynak adlandırma

Uzun süre çalışan işlemler (LRO'lar)

Python SDK'sı

Java SDK'sı

CLI

Kıvrım

Maskeleri güncelleştirme

Hata yönetimi

409: Çakışan işlemler

Python SDK'sı

Kıvrım

SDK'lar ve kod olarak altyapı

Geri Bildirim

Ek kaynaklar