Lakebase 自動スケール API ガイド

Important

Lakebase 自動スケールは、 eastus、 eastus2、 centralus、 southcentralus、 westus、 westus2、 canadacentral、 brazilsouth、 northeurope、 uksouth、 westeurope、 australiaeast、 centralindia、 southeastasiaの各リージョンで使用できます。

Lakebase 自動スケールは、自動スケールコンピューティング、ゼロへのスケール、分岐、インスタントリストアを備えた最新バージョンの Lakebase です。 Lakebase プロビジョニング済みユーザーの場合は、「 Lakebase Provisioned」を参照してください。

このページでは、認証、使用可能なエンドポイント、REST API、Databricks CLI、Databricks SDK (Python、Java、Go) を操作するための一般的なパターンなど、Lakebase 自動スケール API の概要について説明します。

完全な API リファレンスについては、 Postgres API のドキュメントを参照してください。

Important

Lakebase Postgres API は ベータ版です。 API エンドポイント、パラメーター、および動作は変更される可能性があります。

Authentication

Lakebase 自動スケール API では、プロジェクトインフラストラクチャの管理 (プロジェクトの作成、設定の構成など) に ワークスペースレベルの OAuth 認証 が使用されます。

注

2 種類の接続: この API は プラットフォーム管理 用です (プロジェクト、ブランチ、コンピューティングの作成)。 データベースアクセスの場合 (クエリデータへの接続):

SQL クライアント (psql、pgAdmin、DBeaver): Lakebase OAuth トークンまたは Postgres パスワードを使用します。認証に関するページを参照してください。
データ API (RESTful HTTP): Lakebase OAuth トークンを使用します。データ API を参照してください。
プログラミング言語ドライバー (psycopg、SQLAlchemy、JDBC): Lakebase OAuth トークンまたは Postgres パスワードを使用します。クイックスタートを参照してください。

これら 2 つの認証レイヤーの詳細については、「認証アーキテクチャ」を参照してください。

認証を設定する

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 トークンは 1 時間後に期限切れになります。必要に応じて再生成します。

詳細については、「 OAuth を使用して Databricks へのユーザーアクセスを承認する」を参照してください。

使用可能なエンドポイント (ベータ)

すべてのエンドポイントは、基本パス /api/2.0/postgres/を使用します。

プロジェクト

Operation	メソッド	エンドポイント	Documentation
プロジェクトを作成	`POST`	`/projects`	プロジェクトの作成
プロジェクトを更新する	`PATCH`	`/projects/{project_id}`	全般設定
プロジェクトの削除	`DELETE`	`/projects/{project_id}`	プロジェクトを削除する
プロジェクトを取得する	`GET`	`/projects/{project_id}`	プロジェクトの詳細を取得する
プロジェクトを一覧表示する	`GET`	`/projects`	プロジェクトの一覧表示

ブランチ

Operation	メソッド	エンドポイント	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`	ブランチを一覧表示する

エンドポイント (コンピュートとリードレプリカ)

Operation	メソッド	エンドポイント	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`	コンピュートの表示

役割

Operation	メソッド	エンドポイント	Documentation
ロールの一覧表示	`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}`	ロールを削除する

データベース資格情報

Operation	メソッド	エンドポイント	Documentation
データベース資格情報を生成する	`POST`	`/credentials`	OAuth トークン認証

操作

Operation	メソッド	エンドポイント	Documentation
操作を取得する	`GET`	`/projects/{project_id}/operations/{operation_id}`	以下の例を参照してください

アクセス許可

プロジェクト ACL のアクセス許可では、ベースパスではなく、/api/2.0/postgres/ が使用されます。 request_object_typeをdatabase-projectsに設定し、プロジェクト ID にrequest_object_idします。

Operation	メソッド	エンドポイント	Documentation
プロジェクトのアクセス許可を取得する	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	Permissions API リファレンス
プロジェクトのアクセス許可を更新する	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	Permissions API リファレンス
プロジェクトのアクセス許可を置き換える	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	Permissions API リファレンス

Lakebase プロジェクトの許可可能なアクセス許可レベルは、CAN_USE と CAN_MANAGE です。 CAN_CREATE は継承されたレベルであり、API を使用して設定することはできません。アクセス許可レベルを参照してください。

使用例と CLI/SDK/Terraform に相当するものについては、「プログラムによるアクセス許可の付与」を参照してください。

Get 操作

実行時間の長い操作の状態をリソース名で確認します。

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 は、作成後に変更できません。

Requirements:

長さは 1 ~ 63 文字にする必要があります
小文字、数字、ハイフンのみ
ハイフンで開始または終了することはできません
例: my-app、 analytics-db、 customer-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	Query parameter (クエリパラメーター)	`?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: 競合する操作

エラーメッセージ:

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

意味:

Lakebase では、プロジェクトの内部メンテナンス操作をスケジュールすることがあります。これらの内部操作のいずれかが進行中にクライアント要求が到着した場合、Lakebase は 409 Conflict エラーで新しい要求を拒否できます。

これは通常の動作です。クライアントは、このエラーが発生したときに要求を再試行するように準備する必要があります。

実行する操作:

要求をやり直してください。内部操作が完了すると、Lakebase はプロジェクトの新しい要求を受け入れます。

再試行には指数バックオフを使用します。最初の再試行の前に短い間隔で待機してから、後続の各試行で待機を 2 倍にしてください。開始間隔は 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

# 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 要求の 409 Conflict は、要求が適用されたのではなく、受け入れられなかったことを意味します。対応する GET エンドポイントを呼び出して、再試行が成功した後は常にリソースの状態を確認します。

SDK とコードとしてのインフラストラクチャ

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-28

次の方法で共有

Lakebase 自動スケール API ガイド

Authentication

認証を設定する

Python SDK

Java SDK

CLI

curl

使用可能なエンドポイント (ベータ)

プロジェクト

ブランチ

エンドポイント (コンピュートとリードレプリカ)

役割

データベース資格情報

操作

アクセス許可

Get 操作

Python SDK

Java SDK

CLI

curl

一般的なパターン

リソースの名前付け

実行時間の長い操作 (LRO)

Python SDK

Java SDK

CLI

curl

マスクを更新する

エラー処理

409: 競合する操作

Python SDK

curl

SDK とコードとしてのインフラストラクチャ

フィードバック

その他のリソース