Lakebase 自動縮放 API 指南

本頁提供 Lakebase 自動擴展 API 的概述，包括認證、可用端點，以及使用 REST API、Databricks CLI 和 Databricks SDK（Python、Java、Go）的常見操作模式。

完整操作清單及其參數，請參閱 Postgres API 參考文獻。

備註

部分作業仍停留在 Beta 階段。 Postgres API 參考標示每個操作的狀態。

Authentication

Lakebase 自動擴展 API 使用 工作區層級的 OAuth 認證 來管理專案基礎設施（建立專案、設定等）。

備註

兩種連接方式：此 API 用於 平台管理 （建立專案、分支、運算）。關於 資料庫存取 （連接查詢資料）：

SQL 用戶端 （psql、pgAdmin、DBeaver）：使用 Lakebase OAuth 令牌或 Postgres 密碼。請參閱驗證。
Data API （RESTful HTTP）：使用 Lakebase OAuth 代幣。請參閱資料API。
程式語言驅動程式 （psycopg、SQLAlchemy、JDBC）：使用 Lakebase OAuth 令牌或 Postgres 密碼。請參見快速入門。

關於這兩個認證層的完整說明，請參見認證架構。

設定驗證

使用 Databricks CLI 進行認證：

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

請依照瀏覽器提示登入。 CLI 會將你的 OAuth 標記快取在 ~/.databricks/token-cache.json。

然後選擇你的存取方式：

Python SDK

SDK 採用統一認證，並自動處理 OAuth 令牌：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java 開發套件

SDK 採用統一認證，並自動處理 OAuth 令牌：

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

指令會自動使用快取的標記：

databricks postgres list-projects

curl (Unix指令)

產生一個用於直接 API 呼叫的令牌：

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 代幣在一小時後過期。需要時再生。

更多細節請參閱授權用戶存取 Databricks with OAuth。

可用的端點

所有端點都使用基底路徑 /api/2.0/postgres/。

專案

行動	方法	端點	文件資料
建立專案	`POST`	`/projects`	建立專案
更新專案	`PATCH`	`/projects/{project_id}`	一般設定
刪除專案	`DELETE`	`/projects/{project_id}`	刪除專案
取得專案	`GET`	`/projects/{project_id}`	獲取專案詳情
列出專案	`GET`	`/projects`	列出專案

分支

行動	方法	端點	文件資料
建立分支	`POST`	`/projects/{project_id}/branches`	建立分支
更新分支	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	更新分支設定
刪除分支	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	刪除分支
取得分支	`GET`	`/projects/{project_id}/branches/{branch_id}`	查看分支
列出分支	`GET`	`/projects/{project_id}/branches`	列出分支

端點（計算與讀取副本）

在 API 中，計算稱為端點。關於概念概述，請參見計算與端點。

下表將 UI 概念對應於其 API 對應：

使用者介面概念	API 資源或欄位	文件資料
主要運算	端點為 `endpoint_type: ENDPOINT_TYPE_READ_WRITE`	管理運算
讀取複本	端點為 `endpoint_type: ENDPOINT_TYPE_READ_ONLY`	管理讀取副本
高可用性	`group` 端點規格上的欄位（`EndpointGroupSpec`）	管理高可用性
計算識別碼（UID、資源名稱）	`uid` 以及 `name` （完整資源路徑）在端點物件上	計算識別碼

可用操作

行動	方法	端點	文件資料
建立端點	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	建立一個讀取副本
更新端點	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	編輯計算資源 / 編輯讀取複本 / 管理高可用性
刪除端點	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	刪除讀取副本
取得端點	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	檢視運算資源
列出端點	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	檢視運算資源

角色

行動	方法	端點	文件資料
列出角色	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	查看 Postgres 角色
創建角色	`POST`	`/projects/{project_id}/branches/{branch_id}/roles`	建立一個 OAuth 角色 \| 建立密碼角色
取得角色	`GET`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	查看 Postgres 角色
更新角色	`PATCH`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	更新角色
刪除角色	`DELETE`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	刪除角色

行動	方法	端點	文件資料
使用 Unity 目錄登錄資料庫	`POST`	`/catalogs`	註冊資料庫
取得目錄註冊	`GET`	`/catalogs/{catalog_id}`	請檢查註冊狀態
刪除目錄註冊	`DELETE`	`/catalogs/{catalog_id}`	取消註冊資料庫

同步表格

行動	方法	端點	文件資料
建立同步表	`POST`	`/synced_tables`	建立同步表格
取得同步表	`GET`	`/synced_tables/{table_name}`	檢查同步狀態
刪除同步的資料表	`DELETE`	`/synced_tables/{table_name}`	刪除同步的表格

備註

路徑中的 table_name 使用格式 catalog.schema.table。

建立與刪除是長時間執行的操作。輪詢返回的操作直到 done: true。參見長時間執行的操作。

刪除同步的表格僅會移除 Unity Catalog 的註冊。另外把 Postgres 表格放下來，這樣可以釋放空間。

變更資料串流

Lakebase 變更資料饋送（CDF）作業以分支為範圍。關於請求與回應的細節，請參閱 Postgres API 參考中的 CDF 操作。

行動	方法	文件資料
建立 CDF 配置	`POST`	啟動變更資料串流
取得CDF身份	`GET`	啟動變更資料串流
CDF狀態列表	`GET`	啟動變更資料串流
取得 CDF 設定	`GET`	啟動變更資料串流
刪除 CDF 設定	`DELETE`	停用 Lakebase CDF

備註

建立 CDF 設定以啟動變更資料串流。你也可以從 Lakebase 的介面開始訂閱。請參閱開始變更資料串流。

刪除 CDF 配置會永久移除該配置及其表格映射;Unity 目錄中的目的地 Delta 資料表則被保留。

資料庫憑證

行動	方法	端點	文件資料
產生資料庫憑證	`POST`	`/credentials`	OAuth 令牌認證

操作

行動	方法	端點	文件資料
取得操作	`GET`	`/projects/{project_id}/operations/{operation_id}`	請見下方範例

權限

Project ACL 權限使用 standard Azure Databricks Permissions API，而非 /api/2.0/postgres/ 基礎路徑。將request_object_type設為database-projects，並將request_object_id設為你的專案 ID（例如，my-app）。

行動	方法	端點	文件資料
取得專案權限	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	權限 API 參考
更新專案權限	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	權限 API 參考
替換專案權限	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	權限 API 參考

湖基專案的可核准許可等級為 CAN_USE 和 CAN_MANAGE。 CAN_CREATE 是繼承的層級，無法透過 API 設定。請參見權限等級。

關於使用範例及 CLI/SDK/Terraform 等效物，請參見「程式授權權限」。

動手術

透過資源名稱查詢長期執行作業的狀態。

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 開發套件

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 預設會自動等待操作完成。使用--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>

curl (Unix指令)

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

回應格式：

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

田野：

done： false 進行中， true 完成時
response：當 done 是 true 時，包含結果
error：若操作失敗，包含錯誤細節

常見模式

資源命名

資源遵循階層式命名模式，子資源的範圍會指向父資源。

專案採用此格式：

projects/{project_id}

子資源如作業隸屬於其父項目之下。

projects/{project_id}/operations/{operation_id}

這表示你需要父專案 ID 才能存取操作或其他子資源。

資源識別碼：

建立資源時，必須為 my-app、project_id 或 branch_id 參數提供資源 ID（如 endpoint_id）。此 ID 會成為 API 呼叫中資源路徑的一部分（例如 projects/my-app/branches/development）。

你可以選擇性地提供一個 display_name ，讓你的資源有更具體的標籤。如果你沒有指定顯示名稱，系統會使用你的資源 ID 作為顯示名稱。

：：：小撇步在 UI 中尋找資源

要在 Lakebase 應用程式中找到專案，請在專案列表中尋找其顯示名稱。如果你在建立專案時沒有提供自訂顯示名稱，可以搜尋你的 project_id （例如「my-app」）。

:::

備註

資源 ID 在建立後無法更改。

Requirements:

必須是 1 到 63 個字元
僅使用小寫字母、數字及連字號
不能以連字號開頭或結尾
範例： my-app、 analytics-db、 customer-123

長時間運行操作（LRO）

建立、更新和刪除操作會回傳 databricks.longrunning.Operation 一個提供完成狀態的物件。

範例操作回應：

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

使用 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 開發套件

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 預設會自動等待操作完成。使用 --no-wait 立即返回：

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

curl (Unix指令)

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

每隔幾秒輪詢一次，直到 done 為 true。

更新遮罩

更新操作需要一個 update_mask 參數來指定要修改哪些欄位。這可避免意外覆蓋無關欄位。

格式差異：

方法	格式	Example
REST API	查詢參數	`?update_mask=spec.display_name`
Python SDK	FieldMask 物件	`update_mask=FieldMask(field_mask=["spec.display_name"])`
CLI	立場論證	`update-project NAME spec.display_name`

錯誤處理

Lakebase API 會回傳標準的 HTTP 狀態碼。

409：衝突行動

Lakebase 可能會因多種原因回傳 409 Conflict 錯誤：

目前專案內部正在進行維護作業。
該計畫已達到並行作業的極限。
你自己的 API 請求會重疊。例如，在前一個分支建立完成前就建立了分支。

意義：

Lakebase 有時會安排專案的維護作業。若客戶端請求在這些操作進行中抵達，Lakebase 會拒絕該新請求並返回 409 Conflict 錯誤。當專案已滿或 API 呼叫重疊時，你也可能收到這種回應。

這是預期行為。當發生此錯誤時，客戶端應準備好重新嘗試請求。

處理方式：

請重試。當內部運作完成或容量空出時，Lakebase 會接受新的專案申請。

重試時使用指數退縮：在第一次重試前短暫停，然後每次後續嘗試都加倍等待。預設為100毫秒、最多30秒的起始間隔。

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

curl (Unix指令)

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

備註

Lakebase API 請求中的 A 409 Conflict 表示該請求已被拒絕，而不是被執行。成功重試後，務必透過呼叫相應 GET 端點來驗證資源狀態。

SDK 與基礎設施即程式碼

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-21

Lakebase 自動縮放 API 指南

Authentication

設定驗證

Python SDK

Java 開發套件

CLI

curl (Unix指令)

可用的端點

專案

分支

端點（計算與讀取副本）

可用操作

角色

目錄

同步表格

變更資料串流

資料庫憑證

操作

權限

動手術

Python SDK

Java 開發套件

CLI

curl (Unix指令)

常見模式

資源命名

長時間運行操作（LRO）

Python SDK

Java 開發套件

CLI

curl (Unix指令)

更新遮罩

錯誤處理

409：衝突行動

Python SDK

curl (Unix指令)

SDK 與基礎設施即程式碼

意見反應

其他資源