API kullanarak dış uygulamayı Lakebase'e bağlama

Bu kılavuzda, doğrudan REST API çağrılarını kullanarak dış uygulamaların Lakebase Otomatik Ölçeklendirme'ye nasıl bağlanacakları gösterilmektedir. Dilinizde bir Databricks SDK'sı kullanılamadığında (Node.js, Ruby, PHP, Elixir, Rust vb.) bu yaklaşımı kullanın.

Dilinizde SDK desteği (Python, Java veya Go) varsa, daha basit belirteç yönetimi için SDK kullanarak dış uygulamayı Lakebase'e bağlama seçeneğini kullanın.

OAuth belirteci döndürmesi ile veritabanı kimlik bilgilerini almak için iki API çağrısı yaparsınız. Curl ve Node.jsiçin örnekler verilmiştir.

Uyarı

İki aşamalı kimlik doğrulaması: Bu yaklaşım, her veritabanı kimlik bilgisi için iki API çağrısı gerektirir: (1) çalışma alanı OAuth belirteci almak için Hizmet Prensibi sırrını takas et, (2) veritabanı kimlik bilgileri almak için OAuth belirtecini takas et. Her iki belirtecin süresi 60 dakika sonra dolar. SDK, 1. adımı otomatik olarak işler.

Önkoşullar

SDK yaklaşımıyla aynı kuruluma ihtiyacınız vardır: hizmet sorumlusu, Postgres rolü ve bağlantı ayrıntıları.

Önkoşul Anahtar ayrıntısı Daha Fazla Bilgi
Hizmet Prensibi En fazla 730 günlük ömrü olan OAuth gizli dizisi; Çalışma alanı erişimini etkinleştirin. Postgres rolü ve env vars için istemci kimliğini (UUID) not edin. Hizmet sorumlusu oluşturma
Postgres rolü Lakebase SQL Düzenleyicisi'nde OAuth rolü oluşturun: databricks_create_role('{client-id}', 'SERVICE_PRINCIPAL') ve CONNECT, USAGE, SELECT/INSERT//UPDATEDELETE verin. 1. adımdaki istemci kimliğini kullanın. Postgres rolü oluşturma
Bağlantı ayrıntıları Lakebase Console'dan Connect: uç nokta adı (projects/.../branches/.../endpoints/...), konak, veritabanı (genellikle databricks_postgres). Bağlantı ayrıntılarını alma

Nasıl çalışır?

El ile API yaklaşımı iki belirteç değişimi gerektirir:

Manuel API belirteci değişim akışı

Belirteç yaşam süreleri:

  • Hizmet Sorumlusu gizli anahtarı: 730 güne kadar (oluşturma sırasında ayarlanır)
  • Çalışma Alanı OAuth belirteci: 60 dakika (1. adım)
  • Veritabanı kimlik bilgileri: 60 dakika (2. adım)

Belirteç kapsamı: Veritabanı kimlik bilgileri çalışma alanı kapsamındadır. endpoint Parametresi gerekli olsa da, döndürülen belirteç çalışma alanında hizmet sorumlusunun izinlerine sahip olduğu herhangi bir veritabanına veya projeye erişebilir.

Ortam değişkenlerini ayarlama

Uygulamanızı çalıştırmadan önce şu ortam değişkenlerini ayarlayın:

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

Bağlantı kodu ekleme

Kıvrım

Bu örnekte ham API çağrıları gösterilmektedir. Üretim uygulamaları için belirteç önbelleğe alma ve yenileme mantığını uygulayın.

# 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

Bu örnekte, belirteç getirme ve önbelleğe alma işlemlerini işleyen zaman uyumsuz parola işlevine sahip node-postgres kullanılır.

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

Bağımlılıklar:pg (node-postgres)

Not: Node-postgres (pg) zaman uyumsuz bir işlevi parola olarak kabul eder. İşlev, yeni bir bağlantı oluşturulduğunda çağrılır ve yeni belirteçler sağlanır.

Bağlantıyı çalıştırma ve doğrulama

Kıvrım

Bash betiğini ortam değişkenleri yüklü olarak çalıştırın:

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

Beklenen çıkış:

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

Eğer current_user hizmet sorumlusu istemci kimliğiniz ile eşleşiyorsa, OAuth düzgün çalışıyor.

Node.js

Bağımlılıkları yükleme:

npm install pg

Çalıştır:

node app.js

Beklenen çıkış:

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

Not: Lakebase Otomatik Ölçeklendirme işlemi sıfırdan başlattığından, boşta kalmadan sonraki ilk bağlantı daha uzun sürebilir.

Sorun giderme

Hata Düzelt
"invalid_client" veya "Eksik istemci kimlik doğrulaması" Denetle DATABRICKS_CLIENT_ID ve DATABRICKS_CLIENT_SECRET doğru. Temel kimlik doğrulaması (base64 kodlanmış) kullanın.
"API, çalışma alanı erişimi yetkilendirmesi olmayan kullanıcılar için devre dışı bırakıldı" Hizmet sorumlusu için "Çalışma alanı erişimini" etkinleştirin (önkoşullar).
"INVALID_PARAMETER_VALUE" / "Uç noktası alanı zorunludur" endpointParametrenin 2. adımdaki POST gövdesine projects/<id>/branches/<id>/endpoints/<id> biçiminde eklendiğinden emin olun.
"Rol mevcut değil" veya kimlik doğrulama başarısız oluyor SQL aracılığıyla OAuth rolü oluşturma (önkoşullar).
"Bağlantı reddedildi" veya zaman aşımı Sıfıra ölçeklendikten sonra ilk bağlantı daha uzun sürebilir. Yeniden deneme mantığını uygulayın.
Belirtecin süresi doldu / "parola kimlik doğrulaması başarısız oldu" Çalışma alanı ve veritabanı belirteçlerinin her ikisi de 60 dakika sonra sona erer. Süre sonu denetimleriyle önbelleğe alma uygulayın.
  • Last updated on