Lakebase 自动缩放 API 指南

重要

Lakebase 自动缩放在以下区域处于 Beta 版：eastus2, westeurope, westus。

Lakebase 自动扩展是 Lakebase 的最新版本，具备自动扩展计算能力、缩减至零、分支和即时还原的功能。有关与 Lakebase 预配的功能比较，请参阅在版本之间进行选择。

本页概述了 Lakebase 自动缩放 API，包括身份验证、可用终结点以及用于处理 REST API、Databricks CLI 和 Databricks SDK（Python、Java、Go）的常见模式。

有关完整的 API 参考，请参阅 Postgres API 文档。

重要

Lakebase Postgres API 处于 Beta 版中。 API 终结点、参数和行为可能会更改。

Authentication

Lakebase 自动缩放 API 使用 工作区级 OAuth 身份验证 来管理项目基础结构（创建项目、配置设置等）。

注释

两种类型的连接：此 API 用于 平台管理 （创建项目、分支、计算）。对于 数据库访问 （连接到查询数据）：

SQL 客户端 （psql、pgAdmin、DBeaver）：使用 Lakebase OAuth 令牌或 Postgres 密码。请参阅身份验证。
数据 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

SDK 使用统一身份验证并自动处理 OAuth 令牌：

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

命令自动使用缓存的令牌：

databricks postgres list-projects

curl

为直接 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 令牌在一小时后过期。根据需要重新生成。

有关详细信息，请参阅授权用户使用 OAuth 访问 Databricks。

可用终结点（Beta）

所有终结点都使用基路径 /api/2.0/postgres/。

项目

操作	方法	端点	Documentation
创建项目	`POST`	`/projects`	创建项目
更新项目	`PATCH`	`/projects/{project_id}`	常规设置
删除项目	`DELETE`	`/projects/{project_id}`	删除项目
获取项目	`GET`	`/projects/{project_id}`	获取项目详细信息
列出项目	`GET`	`/projects`	列出项目

分支

操作	方法	端点	Documentation
创建分支	`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`	列出分支

终结点（计算和只读副本）

操作	方法	端点	Documentation
创建终结点	`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`	查看计算资源

数据库凭据

操作	方法	端点	Documentation
生成数据库凭据	`POST`	`/credentials`	OAuth 令牌身份验证

操作

操作	方法	端点	Documentation
获取操作	`GET`	`/projects/{project_id}/operations/{operation_id}`	请参阅以下示例

获取操作

按资源名称检查长时间运行的作的状态。

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

CLI

默认情况下，CLI 会自动等待操作完成。使用 --no-wait 跳过轮询。

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

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

curl

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

响应格式：

{
  "name": "projects/my-project/operations/abc123",
  "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 才能访问操作或其他子资源。

资源 ID：

创建资源时，必须为my-app、project_id或branch_id参数提供资源 ID（例如endpoint_id）。此 ID 将成为 API 调用中资源路径的一部分（例如 projects/my-app/branches/development）。

可以选择提供一个 display_name 用于为资源提供更具描述性的标签。如果未指定显示名称，系统将资源 ID 用作显示名称。

：：：tip 在 UI 中查找资源

若要在 Lakebase UI 中查找项目，请在项目列表中查找其显示名称。如果在创建项目时未提供自定义显示名称，请搜索你的 project_id （如“my-app”）。

:::

注释

创建后无法更改资源 ID。

要求：

长度必须为 1-63 个字符
仅小写字母、数字和连字符
不能以连字符开头或结尾
示例：my-app、、 analytics-dbcustomer-123

长时间运行的操作（LRO）

创建、更新和删除操作返回一个提供完成状态的 databricks.longrunning.Operation 对象。

操作响应示例：

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

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

CLI

默认情况下，CLI 会自动等待操作完成。使用 --no-wait 来立即返回。

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

curl

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

每隔几秒钟轮询一次，直到 done 是 true。

更新掩码

更新作需要一个 update_mask 参数，用于指定要修改的字段。这可以防止意外覆盖非相关字段。

格式差异：

方法	Format	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`

SDK 和基础结构即代码

反馈

此页面是否有帮助？

Last updated on 2026-02-14

通过

Lakebase 自动缩放 API 指南

Authentication

设置身份验证

Python SDK

Java SDK

CLI

curl

可用终结点 （Beta）

项目

分支

终结点（计算和只读副本）

数据库凭据

操作

获取操作

Python SDK

Java SDK

CLI

curl

常见模式

资源命名

长时间运行的操作（LRO）

Python SDK

Java SDK

CLI

curl

更新掩码

SDK 和基础结构即代码

反馈

其他资源

可用终结点（Beta）