Guía de la API de escalado automático de Lakebase

Importante

El escalado automático de Lakebase está en Beta en las siguientes regiones: eastus2, westeurope, westus.

El escalado automático de Lakebase es la versión más reciente de Lakebase con proceso de escalado automático, escalado a cero, bifurcación y restauración instantánea. Para ver la comparación de características con Lakebase Provisioned, consulte Elección entre versiones.

En esta página se proporciona información general sobre la API de escalado automático de Lakebase, incluida la autenticación, los puntos de conexión disponibles y los patrones comunes para trabajar con la API REST, la CLI de Databricks, los SDK de Databricks (Python, Java, Go) y Terraform.

Para obtener la referencia de API completa, consulte la documentación de la API de Postgres.

Importante

La API de Postgres de Lakebase está en beta. Los puntos de conexión de API, los parámetros y los comportamientos están sujetos a cambios.

Autenticación

La API de escalado automático de Lakebase usa la autenticación de OAuth de nivel de área de trabajo para administrar la infraestructura del proyecto (crear proyectos, configurar opciones, etc.).

Nota:

Dos tipos de conectividad: esta API es para la administración de plataformas (creación de proyectos, ramas, procesos). Para acceder a la base de datos (conectar para consultar datos):

Clientes SQL (psql, pgAdmin, DBeaver): Utiliza tokens OAuth de LakeBase o contraseñas de PostgreSQL. Consulte Autenticación.
Data API (RESTful HTTP): Use tokens de OAuth de LakeBase. Consulte Api de datos.
Controladores de lenguajes de programación (psycopg, SQLAlchemy, JDBC): Utilice Tokens de OAuth de LakeBase o contraseñas de Postgres. Consulte Inicio rápido.

Para obtener una explicación completa de estas dos capas de autenticación, consulte Arquitectura de autenticación.

Configuración de la autenticación

Autenticación mediante la CLI de Databricks:

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

Siga las indicaciones del explorador para iniciar sesión. La CLI almacena en caché el token de OAuth en ~/.databricks/token-cache.json.

A continuación, elija el método de acceso:

SDK de Python

El SDK usa la autenticación unificada y controla automáticamente los tokens de OAuth:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

SDK de Java

El SDK usa la autenticación unificada y controla automáticamente los tokens de OAuth:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

Interfaz de línea de comandos (CLI)

Los comandos usan automáticamente el token almacenado en caché:

databricks postgres list-projects

curl

Genere un token para llamadas DE API directas:

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

Los tokens de OAuth expiran después de una hora. Vuelva a generar según sea necesario.

Para más información, consulte Autorización del acceso de usuario a Databricks con OAuth.

Puntos de conexión disponibles (beta)

Todos los puntos de conexión usan la ruta base de acceso /api/2.0/postgres/.

Proyectos

Operation	Método	Punto final	Documentation
Crear proyecto	`POST`	`/projects`	Creación de un proyecto
Actualizar proyecto	`PATCH`	`/projects/{project_id}`	Configuración general
Eliminar proyecto	`DELETE`	`/projects/{project_id}`	Eliminación de un proyecto
Obtener proyecto	`GET`	`/projects/{project_id}`	Obtener detalles del proyecto
Enumerar proyectos	`GET`	`/projects`	Enumerar proyectos

Sucursales

Operation	Método	Punto final	Documentation
Crear rama	`POST`	`/projects/{project_id}/branches`	Crear una rama
Actualizar rama	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	Actualizar la configuración de la rama
Eliminar rama	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	Eliminación de una rama
Obtener rama	`GET`	`/projects/{project_id}/branches/{branch_id}`	Ver ramas
Enumerar ramas	`GET`	`/projects/{project_id}/branches`	Enumerar ramas

Puntos de conexión (procesos y réplicas de lectura)

Operation	Método	Punto final	Documentation
Creación de un punto de conexión	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Crear una instancia de cómputo / Crear una réplica de lectura
Actualizar punto de conexión	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Editar un recurso de computación / Edición de una réplica de lectura
Eliminación de un punto de conexión	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Eliminación de un proceso / Eliminación de una réplica de lectura
Obtención del punto de conexión	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Visualización de procesos
Enumerar puntos de conexión	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Visualización de procesos

Credenciales de base de datos

Operation	Método	Punto final	Documentation
Generación de credenciales de base de datos	`POST`	`/credentials`	Autenticación de tokens de OAuth

Operaciones

Operation	Método	Punto final	Documentation
Obtener operación	`GET`	`/projects/{project_id}/operations/{operation_id}`	Consulte el ejemplo siguiente.

Obtención de la operación

Compruebe el estado de una operación de ejecución prolongada por su nombre de recurso.

SDK de Python

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

SDK de 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(...);
System.out.println("Operation started: " + operation.getName());

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

Interfaz de línea de comandos (CLI)

La CLI espera automáticamente a que se completen las operaciones de forma predeterminada. Use --no-wait para omitir el sondeo:

# 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

Formato de respuesta:

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

Campos:

done: false mientras está en curso, true cuando se completa
response: contiene el resultado cuando done es true
error: contiene detalles de error si se produjo un error en la operación.

Patrones comunes

Asignación de nombres de recursos

Los recursos siguen un patrón de nomenclatura jerárquico en el que los recursos secundarios están delimitados por su recurso principal.

Los proyectos usan este formato:

projects/{project_id}

Los recursos secundarios, como las operaciones, están anidados en su proyecto primario:

projects/{project_id}/operations/{operation_id}

Esto significa que necesita el identificador del proyecto principal para acceder a las operaciones u otros recursos secundarios.

Identificadores de recursos:

Al crear recursos, debe proporcionar un identificador de recurso (como my-app) para el parámetro project_id, branch_id o endpoint_id. Este identificador forma parte de la ruta de acceso del recurso en las llamadas API (por ejemplo projects/my-app/branches/development, ).

Opcionalmente, puede proporcionar un display_name para proporcionar a su recurso una etiqueta más descriptiva. Si no especifica un nombre para mostrar, el sistema usa el identificador de recurso como nombre para mostrar.

:::tip Búsqueda de recursos en la interfaz de usuario

Para buscar un proyecto en la interfaz de usuario de Lakebase, busque su nombre de visualización en la lista de proyectos. Si no proporcionó un nombre visible personalizado al crear el proyecto, busque su project_id (por ejemplo, "my-app").

:::

Nota:

Los identificadores de recursos no se pueden cambiar después de la creación.

Requisitos:

Debe tener entre 1 y 63 caracteres
Solo letras minúsculas, dígitos y guiones
No se puede iniciar ni terminar con un guión
Ejemplos: my-app, analytics-db, customer-123

Operaciones de larga duración (LROs)

Las operaciones de creación, actualización y eliminación devuelven un databricks.longrunning.Operation objeto que proporciona un estado de finalización.

Respuesta de la operación de ejemplo:

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

Sondee la finalización mediante GetOperation:

SDK de Python

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

SDK de Java

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

Interfaz de línea de comandos (CLI)

La CLI espera automáticamente a que se completen las operaciones de forma predeterminada. usa --no-wait para retornar inmediatamente:

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'

Sondea cada pocos segundos hasta que done sea true.

Actualizar máscaras

Las operaciones de actualización requieren un update_mask parámetro que especifique los campos que se van a modificar. Esto evita que se sobrescriban accidentalmente campos no relacionados.

Diferencias de formato:

Método	Formato	Example
REST API	Parámetro de consulta	`?update_mask=spec.display_name`
SDK de Python	Objeto FieldMask	`update_mask=FieldMask(field_mask=["spec.display_name"])`
Interfaz de línea de comandos (CLI)	Argumento posicional	`update-project NAME spec.display_name`

Compartir a través de

Guía de la API de escalado automático de Lakebase

Autenticación

Configuración de la autenticación

SDK de Python

SDK de Java

Interfaz de línea de comandos (CLI)

curl

Puntos de conexión disponibles (beta)

Proyectos

Sucursales

Puntos de conexión (procesos y réplicas de lectura)

Credenciales de base de datos

Operaciones

Obtención de la operación

SDK de Python

SDK de Java

Interfaz de línea de comandos (CLI)

curl

Patrones comunes

Asignación de nombres de recursos

Operaciones de larga duración (LROs)

SDK de Python

SDK de Java

Interfaz de línea de comandos (CLI)

curl

Actualizar máscaras

Recursos adicionales

SDK y infraestructura como código

Comentarios

Recursos adicionales