Menyambungkan aplikasi eksternal ke Lakebase menggunakan API

Penting

Lakebase Autoscaling adalah versi terbaru Lakebase, dengan komputasi penskalaan otomatis, skala-ke-nol, percabangan, dan pemulihan instan. Untuk wilayah yang didukung, lihat Ketersediaan wilayah. Jika Anda adalah pengguna Lakebase Provisioned, lihat Lakebase Provisioned.

Panduan ini menunjukkan cara menghubungkan aplikasi eksternal ke Lakebase Autoscaling menggunakan panggilan REST API langsung. Gunakan pendekatan ini ketika Databricks SDK tidak tersedia untuk bahasa Anda (Node.js, Ruby, PHP, Elixir, Rust, dll.).

Jika bahasa Anda memiliki dukungan SDK (Python, Java, atau Go), gunakan Sambungkan aplikasi eksternal ke Lakebase menggunakan SDK sebagai gantinya untuk manajemen token yang lebih sederhana.

Anda melakukan dua panggilan API untuk mendapatkan kredensial database dengan rotasi token OAuth. Contoh disediakan untuk curl dan Node.js.

Nota

Autentikasi dua langkah: Pendekatan ini memerlukan dua panggilan API untuk setiap kredensial database: (1) rahasia Service Principal ditukar menjadi token OAuth ruang kerja, (2) menukar token OAuth menjadi kredensial database. Kedua token kedaluwarsa setelah 60 menit. SDK menangani langkah 1 secara otomatis.

Prasyarat

Anda memerlukan penyiapan yang sama dengan pendekatan SDK: perwakilan layanan, peran Postgres, dan detail koneksi.

Prasyarat Detail utama Informasi selengkapnya
Prinsipal layanan Rahasia OAuth dengan masa pakai maks 730 hari ; aktifkan akses Ruang Kerja. Perhatikan ID klien (UUID) untuk peran Postgres dan env vars. Membuat prinsipal layanan
Peran Postgres Buat peran OAuth di Editor Lakebase SQL: databricks_create_role('{client-id}', 'SERVICE_PRINCIPAL') dan berikan CONNECT, USAGE, SELECT/INSERT/UPDATE/DELETE. Gunakan ID klien dari langkah 1. Membuat peran Postgres
Detail koneksi Dari Lakebase Console Connect: nama titik akhir (projects/.../branches/.../endpoints/...), host, database (biasanya databricks_postgres). Mendapatkan detail koneksi

Cara kerjanya

Pendekatan API manual memerlukan dua pertukaran token:

Alur pertukaran token API manual

Masa pakai token:

  • Rahasia Perwakilan Layanan: Hingga 730 hari (diatur selama pembuatan)
  • Token OAuth ruang kerja: 60 menit (langkah 1)
  • Info masuk database: 60 menit (langkah 2)

Cakupan token: Kredensial database bercakupan pada ruang kerja. Meskipun parameter endpoint diperlukan, token yang dikembalikan dapat mengakses database atau proyek apa pun di ruang kerja yang memiliki izin perwakilan layanan.

Mengatur variabel lingkungan

Atur variabel lingkungan ini sebelum menjalankan aplikasi Anda:

# Databricks workspace authentication
export DATABRICKS_HOST="https://your-workspace.databricks.com"
export DATABRICKS_CLIENT_ID="<service-principal-client-id>"
export DATABRICKS_CLIENT_SECRET="<your-oauth-secret>"

# Lakebase connection details (from prerequisites)
export ENDPOINT_NAME="projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>"
export PGHOST="<endpoint-id>.database.<region>.cloud.databricks.com"
export PGDATABASE="databricks_postgres"
export PGUSER="<service-principal-client-id>"   # Same UUID as client ID
export PGPORT="5432"

Menambahkan kode koneksi

melengkung

Contoh ini menunjukkan panggilan API mentah. Untuk aplikasi produksi, terapkan penyimpanan sementara token dan logika penyegaran.

# Step 1: Get workspace OAuth token
OAUTH_TOKEN=$(curl -s -X POST "${DATABRICKS_HOST}/oidc/v1/token" \
  -u "${DATABRICKS_CLIENT_ID}:${DATABRICKS_CLIENT_SECRET}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=all-apis" \
  | jq -r '.access_token')

echo "Got workspace OAuth token (60-min lifetime)"

# Step 2: Get database credential
PG_TOKEN=$(curl -s -X POST "${DATABRICKS_HOST}/api/2.0/postgres/credentials" \
  -H "Authorization: Bearer ${OAUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"endpoint\": \"${ENDPOINT_NAME}\"}" \
  | jq -r '.token')

echo "Got database credential (60-min lifetime)"

# Step 3: Connect to Postgres
PGPASSWORD="${PG_TOKEN}" psql \
  -h "${PGHOST}" \
  -p "${PGPORT}" \
  -U "${PGUSER}" \
  -d "${PGDATABASE}" \
  -c "SELECT current_user, current_database()"

Node.js

Contoh ini menggunakan node-postgres dengan fungsi kata sandi asinkron yang menangani pengambilan token dan caching.

import pg from 'pg';

// Step 1: Fetch workspace OAuth token
async function getWorkspaceToken(host, clientId, clientSecret) {
  const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
  const response = await fetch(`${host}/oidc/v1/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${auth}`,
    },
    body: 'grant_type=client_credentials&scope=all-apis',
  });

  if (!response.ok) {
    throw new Error(`OAuth failed: ${response.status}`);
  }

  const data = await response.json();
  return {
    token: data.access_token,
    expires: Date.now() + data.expires_in * 1000,
  };
}

// Step 2: Fetch database credential
async function getPostgresCredential(host, workspaceToken, endpoint) {
  const response = await fetch(`${host}/api/2.0/postgres/credentials`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${workspaceToken}`,
    },
    body: JSON.stringify({ endpoint }),
  });

  if (!response.ok) {
    throw new Error(`Database credential failed: ${response.status}`);
  }

  const data = await response.json();
  return {
    token: data.token,
    expires: new Date(data.expire_time).getTime(),
  };
}

// Simple caching wrapper (production: use more sophisticated caching)
function cached(fetchFn) {
  let cache = null;
  return async (...args) => {
    const now = Date.now();
    if (!cache || now >= cache.expires - 5 * 60 * 1000) {
      // Refresh 5 min early
      const result = await fetchFn(...args);
      cache = result;
    }
    return cache.token;
  };
}

// Create connection pool with async password function
function createPool() {
  const host = process.env.DATABRICKS_HOST;
  const clientId = process.env.DATABRICKS_CLIENT_ID;
  const clientSecret = process.env.DATABRICKS_CLIENT_SECRET;
  const endpoint = process.env.ENDPOINT_NAME;

  const cachedWorkspaceToken = cached(() => getWorkspaceToken(host, clientId, clientSecret));
  const cachedPostgresToken = cached(async () => {
    const workspaceToken = await cachedWorkspaceToken();
    return getPostgresCredential(host, workspaceToken, endpoint);
  });

  return new pg.Pool({
    host: process.env.PGHOST,
    port: process.env.PGPORT,
    database: process.env.PGDATABASE,
    user: process.env.PGUSER,
    password: cachedPostgresToken, // Async function: () => Promise<string>
    ssl: { rejectUnauthorized: true },
    min: 1,
    max: 10,
    idleTimeoutMillis: 900000, // Example: 15 minutes
    connectionTimeoutMillis: 60000, // Example: 60 seconds
  });
}

// Use the pool
const pool = createPool();
const result = await pool.query('SELECT current_user, current_database()');
console.log('Connected as:', result.rows[0].current_user);

Dependensi:pg (node-postgres)

Catatan: Node-postgres (pg) menerima fungsi asinkron sebagai kata sandi. Fungsi ini dipanggil setiap kali koneksi baru dibuat, memastikan token baru.

Menjalankan dan memverifikasi koneksi

melengkung

Jalankan skrip bash dengan variabel lingkungan yang dimuat:

export $(cat .env | xargs)
bash connect.sh

Output yang diharapkan:

Got workspace OAuth token (60-min lifetime)
Got database credential (60-min lifetime)
     current_user      | current_database
-----------------------+------------------
 c00f575e-d706-4f6b... | databricks_postgres

Jika current_user cocok dengan ID klien perwakilan layanan Anda, OAuth berfungsi dengan benar.

Node.js

Pasang dependensi:

npm install pg

Menjalankan:

node app.js

Output yang diharapkan:

Connected as: c00f575e-d706-4f6b-b62c-e7a14850571b

Catatan: Koneksi pertama setelah tidak aktif mungkin memakan waktu lebih lama karena Sistem Penskalaan Otomatis Lakebase mulai komputasi dari awal.

Troubleshooting

Kesalahan Perbaiki
"invalid_client" atau "Autentikasi klien hilang" Periksa DATABRICKS_CLIENT_ID dan DATABRICKS_CLIENT_SECRET sudah benar. Gunakan autentikasi Dasar (dikodekan base64).
"API dinonaktifkan untuk pengguna tanpa hak akses ruang kerja" Aktifkan "Akses ruang kerja" untuk perwakilan layanan (prasyarat).
"INVALID_PARAMETER_VALUE" / "Bidang 'titik akhir' diperlukan" Pastikan endpoint parameter disertakan dalam isi POST langkah 2 dengan format projects/<id>/branches/<id>/endpoints/<id>.
"Peran tidak ada" atau autentikasi gagal Buat peran OAuth melalui SQL (prasyarat).
"Koneksi ditolak" atau waktu habis Koneksi pertama setelah skala-ke-nol mungkin memakan waktu lebih lama. Menerapkan logika pengulangan.
Token kedaluwarsa / "autentikasi kata sandi gagal" Token ruang kerja dan database kedaluwarsa setelah 60 menit. Implementasikan cache dengan pemeriksaan kedaluwarsa.
  • Last updated on