Bagikan melalui

Lakebase Data API

Penting

Lakebase Autoscaling berada di Beta di wilayah berikut: eastus2, , westeuropewestus.

Lakebase Autoscaling adalah versi terbaru Lakebase dengan komputasi penskalaan otomatis, skala-ke-nol, percabangan, dan pemulihan instan. Untuk perbandingan fitur dengan Lakebase Provisioned, lihat memilih antar versi.

Lakebase Data API adalah antarmuka RESTful yang kompatibel dengan PostgREST yang memungkinkan Anda berinteraksi langsung dengan database Lakebase Postgres menggunakan metode HTTP standar. Ini menawarkan titik akhir API yang berasal dari skema database Anda, memungkinkan operasi CRUD (Buat, Baca, Perbarui, Hapus) yang aman pada data Anda tanpa perlu pengembangan backend kustom.

Ikhtisar

API Data secara otomatis menghasilkan titik akhir RESTful berdasarkan skema database Anda. Setiap tabel dalam database Anda dapat diakses melalui permintaan HTTP, memungkinkan Anda untuk:

  • Mengkueri data menggunakan permintaan HTTP GET dengan pemfilteran, pengurutan, dan penomoran halaman yang fleksibel
  • Menyisipkan rekaman menggunakan permintaan HTTP POST
  • Memperbarui rekaman menggunakan permintaan HTTP PATCH atau PUT
  • Menghapus rekaman menggunakan permintaan HTTP DELETE
  • Menjalankan fungsi sebagai RPC menggunakan permintaan HTTP POST

Pendekatan ini menghilangkan kebutuhan untuk menulis dan memelihara kode API kustom, memungkinkan Anda untuk fokus pada logika aplikasi dan skema database Anda.

Kompatibilitas PostgREST

Lakebase Data API kompatibel dengan spesifikasi PostgREST . Kamu bisa:

  • Menggunakan pustaka dan alat klien PostgREST yang ada
  • Ikuti konvensi PostgREST untuk pemfilteran, pemesanan, dan penomoran halaman
  • Mengadaptasi dokumentasi dan contoh dari komunitas PostgREST

Nota

Lakebase Data API adalah implementasi Azure Databricks yang dirancang agar kompatibel dengan spesifikasi PostgREST. Karena API Data adalah implementasi independen, beberapa fitur PostgREST yang tidak berlaku untuk lingkungan Lakebase tidak disertakan. Untuk detail tentang kompatibilitas fitur, lihat Referensi kompatibilitas fitur.

Untuk detail komprehensif tentang fitur API, parameter kueri, dan kemampuan, lihat referensi POSTGREST API.

Kasus penggunaan

Lakebase Data API sangat ideal untuk:

  • Aplikasi web: Membangun frontend yang langsung berinteraksi dengan database Anda melalui permintaan HTTP
  • Layanan mikro: Membuat layanan ringan yang mengakses sumber daya database melalui REST API
  • Arsitektur tanpa server: Integrasikan dengan fungsi tanpa server dan platform komputasi tepi
  • Aplikasi seluler: Menyediakan aplikasi seluler dengan akses database langsung melalui antarmuka RESTful
  • Integrasi pihak ketiga: Mengaktifkan sistem eksternal untuk membaca dan menulis data dengan aman

Menyiapkan API Data

Bagian ini memandu Anda menyiapkan API Data, mulai dari membuat peran yang diperlukan hingga membuat permintaan API pertama Anda.

Prasyarat

API Data memerlukan proyek database Autoscaling Lakebase Postgres. Jika Anda tidak memilikinya, lihat Mulai menggunakan proyek database.

Petunjuk / Saran

Jika Anda memerlukan tabel sampel untuk menguji API Data, buat tabel tersebut sebelum mengaktifkan API Data. Lihat Contoh skema untuk contoh skema lengkap.

Mengaktifkan API Data

API Data membuat semua akses database melalui satu peran Postgres bernama authenticator, yang tidak memerlukan izin kecuali untuk masuk. Saat Anda mengaktifkan API Data melalui Aplikasi Lakebase, peran ini dan infrastruktur yang diperlukan dibuat secara otomatis.

Untuk mengaktifkan API Data:

  1. Navigasi ke halaman API Data di proyek Anda.
  2. Klik Aktifkan API Data.

Tombol Aktifkan Data API

Ini secara otomatis melakukan semua langkah penyiapan, termasuk membuat authenticator peran, mengonfigurasi pgrst skema, dan mengekspos public skema melalui API.

Nota

Jika Anda perlu mengekspos skema tambahan (di luar public), Anda dapat memodifikasi skema yang diekspos di pengaturan ADVANCED Data API.

Setelah mengaktifkan API Data

Setelah Anda mengaktifkan API Data, Aplikasi Lakebase menampilkan halaman API Data dengan dua tab: API dan Pengaturan.

Halaman API Data memperlihatkan URL API dan opsi keamanan

Tab API menyediakan:

  • URL API: URL titik akhir REST untuk digunakan dalam kode aplikasi dan permintaan API Anda. URL yang ditampilkan tidak menyertakan skema, jadi Anda harus menambahkan nama skema (misalnya, /public) ke URL saat membuat permintaan API.
  • Refresh cache skema: Tombol untuk merefresh cache skema API setelah Anda membuat perubahan pada skema database Anda. Lihat Segarkan cache skema.
  • Lindungi data Anda: Opsi untuk mengaktifkan keamanan tingkat baris Postgres (RLS) untuk tabel Anda. Lihat Mengaktifkan keamanan tingkat baris.

Tab Pengaturan menyediakan opsi untuk mengonfigurasi perilaku API, seperti skema yang diekspos, baris maksimum, pengaturan CORS, dan banyak lagi. Lihat Pengaturan API Data Tingkat Lanjut.

Sampel skema (opsional)

Contoh dalam dokumentasi ini menggunakan skema berikut. Anda dapat membuat tabel Anda sendiri atau menggunakan skema sampel ini untuk pengujian. Jalankan pernyataan SQL ini menggunakan Editor Lakebase SQL atau klien SQL apa pun:

-- Create clients table
CREATE TABLE clients (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  company TEXT,
  phone TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create projects table with foreign key to clients
CREATE TABLE projects (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT,
  client_id INTEGER NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
  status TEXT DEFAULT 'active',
  start_date DATE,
  end_date DATE,
  budget DECIMAL(10,2),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create tasks table with foreign key to projects
CREATE TABLE tasks (
  id SERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  description TEXT,
  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
  status TEXT DEFAULT 'pending',
  priority TEXT DEFAULT 'medium',
  assigned_to TEXT,
  due_date DATE,
  estimated_hours DECIMAL(5,2),
  actual_hours DECIMAL(5,2),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Insert sample data
INSERT INTO clients (name, email, company, phone) VALUES
  ('Acme Corp', 'contact@acme.com', 'Acme Corporation', '+1-555-0101'),
  ('TechStart Inc', 'hello@techstart.com', 'TechStart Inc', '+1-555-0102'),
  ('Global Solutions', 'info@globalsolutions.com', 'Global Solutions Ltd', '+1-555-0103');

INSERT INTO projects (name, description, client_id, status, start_date, end_date, budget) VALUES
  ('Website Redesign', 'Complete overhaul of company website with modern design', 1, 'active', '2024-01-15', '2024-06-30', 25000.00),
  ('Mobile App Development', 'iOS and Android app for customer management', 1, 'planning', '2024-07-01', '2024-12-31', 50000.00),
  ('Database Migration', 'Migrate legacy system to cloud database', 2, 'active', '2024-02-01', '2024-05-31', 15000.00),
  ('API Integration', 'Integrate third-party services with existing platform', 3, 'completed', '2023-11-01', '2024-01-31', 20000.00);

INSERT INTO tasks (title, description, project_id, status, priority, assigned_to, due_date, estimated_hours, actual_hours) VALUES
  ('Design Homepage', 'Create wireframes and mockups for homepage', 1, 'in_progress', 'high', 'Sarah Johnson', '2024-03-15', 16.00, 8.00),
  ('Setup Development Environment', 'Configure local development setup', 1, 'completed', 'medium', 'Mike Chen', '2024-02-01', 4.00, 3.50),
  ('Database Schema Design', 'Design new database structure', 3, 'completed', 'high', 'Alex Rodriguez', '2024-02-15', 20.00, 18.00),
  ('API Authentication', 'Implement OAuth2 authentication flow', 4, 'completed', 'high', 'Lisa Wang', '2024-01-15', 12.00, 10.50),
  ('User Testing', 'Conduct usability testing with target users', 1, 'pending', 'medium', 'Sarah Johnson', '2024-04-01', 8.00, NULL),
  ('Performance Optimization', 'Optimize database queries and caching', 3, 'in_progress', 'medium', 'Alex Rodriguez', '2024-04-30', 24.00, 12.00);

Mengonfigurasi izin pengguna

Anda harus mengautentikasi semua permintaan API Data menggunakan token pembawa OAuth Azure Databricks, yang dikirim melalui Authorization header. API Data membatasi akses ke identitas Azure Databricks yang diautentikasi, dengan Postgres mengatur izin yang mendasar.

Peran authenticator mengambil alih identitas pengguna yang mengajukan saat memproses permintaan API. Agar ini berfungsi, setiap identitas Azure Databricks yang mengakses API Data harus memiliki peran Postgres yang sesuai dalam database Anda. Jika Anda perlu menambahkan pengguna ke akun Azure Databricks Anda terlebih dahulu, lihat Menambahkan pengguna ke akun Anda.

Menambahkan peran Postgres

databricks_auth Gunakan ekstensi untuk membuat peran Postgres yang sesuai dengan identitas Azure Databricks:

Buat ekstensi:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

Tambahkan peran Postgres:

SELECT databricks_create_role('user@databricks.com', 'USER');

Untuk petunjuk terperinci, lihat Membuat peran OAuth untuk identitas Azure Databricks menggunakan SQL.

Penting

Jangan gunakan akun pemilik database Anda (identitas Azure Databricks yang membuat proyek Lakebase) untuk mengakses API Data. Peran ini authenticator memerlukan kemampuan untuk menjalankan peran Anda, dan izin tersebut tidak dapat diberikan kepada akun dengan hak istimewa yang ditingkatkan.

Jika Anda mencoba memberikan peran pemilik database ke authenticator, Anda menerima kesalahan ini:

ERROR:  permission denied to grant role "db_owner_user@databricks.com"
DETAIL:  Only roles with the ADMIN option on role "db_owner_user@databricks.com" may grant this role.

Memberikan izin kepada pengguna

Sekarang setelah Anda membuat peran Postgres yang sesuai untuk identitas Azure Databricks, Anda perlu memberikan izin ke peran Postgres tersebut. Izin ini mengontrol objek database mana (skema, tabel, urutan, fungsi) yang dapat berinteraksi dengan setiap pengguna melalui permintaan API.

Berikan izin menggunakan pernyataan SQL GRANT standar. Contoh ini menggunakan public skema; jika Anda mengekspos skema yang berbeda, ganti public dengan nama skema Anda:

-- Allow authenticator to assume the identity of the user
GRANT "user@databricks.com" TO authenticator;

-- Allow user@databricks.com to access everything in public schema
GRANT USAGE ON SCHEMA public TO "user@databricks.com";
GRANT SELECT, UPDATE, INSERT, DELETE ON ALL TABLES IN SCHEMA public TO "user@databricks.com";
GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO "user@databricks.com";
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO "user@databricks.com";

Contoh ini memberikan akses penuh ke public skema untuk user@databricks.com identitas. Ganti ini dengan identitas Azure Databricks yang sebenarnya dan sesuaikan izin berdasarkan kebutuhan Anda.

Penting

Menerapkan keamanan tingkat baris: Izin di atas memberikan akses tingkat tabel, tetapi sebagian besar kasus penggunaan API memerlukan pembatasan tingkat baris. Misalnya, dalam aplikasi multi-tenant, pengguna hanya boleh melihat data mereka sendiri atau data organisasi mereka. Gunakan kebijakan keamanan tingkat baris (RLS) PostgreSQL untuk menerapkan kontrol akses mendetail di tingkat database. Lihat Menerapkan keamanan tingkat baris.

Autentikasi

Untuk mengakses API Data, Anda harus menyediakan token OAuth Azure Databricks di Authorization header permintaan HTTP Anda. Identitas Azure Databricks yang diautentikasi harus memiliki peran Postgres yang sesuai (dibuat pada langkah-langkah sebelumnya) yang menentukan izin databasenya.

Mendapatkan token OAuth

Hubungkan ke ruang kerja Anda sebagai identitas Azure Databricks untuk siapa Anda membuat peran Postgres pada langkah-langkah sebelumnya dan dapatkan token OAuth. Lihat Autentikasi untuk instruksi.

Membuat permintaan

Dengan token OAuth dan URL API Anda (tersedia dari tab API di Aplikasi Lakebase), Anda dapat membuat permintaan API menggunakan curl atau klien HTTP apa pun. Ingatlah untuk menambahkan nama skema (misalnya, /public) ke URL API. Contoh berikut mengasumsikan Anda telah mengekspor DBX_OAUTH_TOKEN variabel lingkungan dan REST_ENDPOINT .

Berikut adalah contoh panggilan dengan output yang diharapkan (menggunakan contoh skema klien/proyek/tugas):

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name,projects(id,name)&id=gte.2"

Contoh respons:

[
  { "id": 2, "name": "TechStart Inc", "projects": [{ "id": 3, "name": "Database Migration" }] },
  { "id": 3, "name": "Global Solutions", "projects": [{ "id": 4, "name": "API Integration" }] }
]

Untuk contoh selengkapnya dan informasi terperinci tentang operasi API, lihat bagian referensi API . Untuk detail komprehensif tentang parameter kueri dan kemampuan API, lihat referensi POSTGREST API. Untuk informasi kompatibilitas khusus Lakebase, lihat Kompatibilitas PostgREST.

Sebelum menggunakan API secara ekstensif, konfigurasikan Keamanan tingkat baris untuk melindungi data Anda.

Mengelola API Data

Setelah mengaktifkan API Data, Anda dapat mengelola perubahan skema dan pengaturan keamanan melalui Aplikasi Lakebase.

Refresh cache skema

Saat Anda membuat perubahan pada skema database Anda (menambahkan tabel, kolom, atau objek skema lainnya), Anda perlu merefresh cache skema. Ini membuat perubahan Anda segera tersedia melalui API Data.

Untuk menyegarkan cache skema:

  1. Navigasikan ke Data API di bagian Backend Aplikasi proyek Anda.
  2. Klik Segarkan skema cache.

API Data sekarang mencerminkan perubahan skema terbaru Anda.

Mengaktifkan keamanan tingkat baris

Aplikasi Lakebase menyediakan cara cepat untuk mengaktifkan keamanan tingkat baris (RLS) untuk tabel dalam database Anda. Saat tabel ada di skema Anda, tab API menampilkan bagian Lindungi data Anda yang memperlihatkan:

  • Tabel dengan RLS diaktifkan
  • Tabel dengan RLS dinonaktifkan (terdapat peringatan)
  • Tombol Aktifkan RLS untuk mengaktifkan RLS untuk semua tabel

Penting

Mengaktifkan RLS melalui Aplikasi Lakebase mengaktifkan keamanan tingkat baris untuk tabel Anda. Saat RLS diaktifkan, semua baris menjadi tidak dapat diakses oleh pengguna secara default (kecuali untuk pemilik tabel, peran dengan atribut BYPASSRLS, dan superusers—meskipun superuser tidak didukung di Lakebase). Anda harus membuat kebijakan RLS untuk memberikan akses ke baris tertentu berdasarkan persyaratan keamanan Anda. Lihat Keamanan tingkat baris untuk informasi tentang membuat kebijakan.

Untuk mengaktifkan RLS untuk tabel Anda:

  1. Navigasikan ke Data API di bagian Backend Aplikasi proyek Anda.
  2. Di bagian Lindungi data Anda , tinjau tabel yang tidak mengaktifkan RLS.
  3. Klik Aktifkan RLS untuk mengaktifkan keamanan tingkat baris untuk semua tabel.

Anda juga dapat mengaktifkan RLS untuk tabel individual menggunakan SQL. Lihat Keamanan tingkat baris untuk detailnya.

Pengaturan API Data Tingkat Lanjut

Bagian Pengaturan tingkat lanjut pada tab API di Aplikasi Lakebase mengontrol keamanan, performa, dan perilaku titik akhir API Data Anda.

Skema yang diekspos

Default:public

Menentukan skema PostgreSQL mana yang diekspos sebagai titik akhir REST API. Secara default, hanya public skema yang dapat diakses. Jika Anda menggunakan skema lain (misalnya, api, v1), pilih dari daftar drop-down untuk menambahkannya.

Nota

Izin berlaku: Menambahkan skema di sini mengekspos titik akhir, tetapi peran database yang digunakan oleh API masih harus memiliki USAGE hak istimewa pada skema dan SELECT hak istimewa pada tabel.

Jumlah baris maksimum

Default: Kosong

Memberlakukan batas keras pada jumlah baris untuk dikembalikan dalam satu respons API. Ini mencegah penurunan performa yang tidak disengaja dari kueri besar. Klien harus menggunakan batas penomoran halaman untuk mengambil data dalam ambang batas ini. Ini juga mencegah biaya keluar yang tidak terduga dari transfer data besar.

Konfigurasi asal CORS yang diizinkan

Default: Kosong (Izinkan semua sumber)

Mengontrol domain web mana yang dapat mengambil data dari API Anda menggunakan browser.

  • Kosong: Memungkinkan * (domain apa pun). Berguna untuk pengembangan.
  • Produksi: Cantumkan domain spesifik Anda (misalnya, https://myapp.com) untuk mencegah situs web yang tidak sah mengkueri API Anda.

spesifikasi OpenAPI

Default: Nonaktif

Mengontrol apakah skema OpenAPI 3 yang dihasilkan secara otomatis tersedia di /openapi.json. Skema ini menjelaskan tabel, kolom, dan titik akhir REST Anda. Saat diaktifkan, Anda dapat menggunakannya untuk:

  • Buat dokumentasi API (UI Swagger, Redoc)
  • Membangun pustaka klien terketik (TypeScript, Python, Go)
  • Mengimpor API Anda ke Postman
  • Integrasikan dengan gateway API dan alat berbasis OpenAPI lainnya

Header pengaturan waktu server

Default: Nonaktif

Saat diaktifkan, API Data menyertakan Server-Timing header di setiap respons. Header ini menunjukkan berapa lama bagian permintaan yang berbeda untuk diproses (misalnya, waktu eksekusi database dan waktu pemrosesan internal). Anda dapat menggunakan informasi ini untuk men-debug kueri lambat, mengukur performa, dan memecahkan masalah latensi di aplikasi Anda.

Nota

Setelah membuat perubahan pada pengaturan tingkat lanjut apa pun, klik Simpan untuk menerapkannya.

Keamanan tingkat baris

Kebijakan keamanan tingkat baris (RLS) menyediakan kontrol akses mendetail dengan membatasi baris mana yang dapat diakses pengguna dalam tabel.

Cara kerja RLS dengan API Data: Saat pengguna membuat permintaan API, peran mengasumsikan authenticator identitas pengguna tersebut. Setiap kebijakan RLS yang ditentukan untuk peran pengguna tersebut secara otomatis diberlakukan oleh PostgreSQL, memfilter data yang dapat mereka akses. Ini terjadi di tingkat database, jadi bahkan jika kode aplikasi mencoba mengkueri semua baris, database hanya mengembalikan baris yang diizinkan untuk dilihat pengguna. Ini memberikan keamanan pertahanan mendalam tanpa memerlukan logika pemfilteran dalam kode aplikasi Anda.

Mengapa RLS sangat penting untuk API: Tidak seperti koneksi database langsung tempat Anda mengontrol konteks koneksi, API HTTP mengekspos database Anda ke beberapa pengguna melalui satu titik akhir. Izin tingkat tabel saja berarti bahwa jika pengguna dapat mengakses clients tabel, mereka dapat mengakses semua rekaman klien kecuali Anda menerapkan pemfilteran. Kebijakan RLS memastikan setiap pengguna secara otomatis hanya melihat data yang diotorisasi.

RLS sangat penting untuk:

  • Aplikasi multi-tenant: Memisahkan data antara pelanggan atau organisasi yang berbeda.
  • Data milik pengguna: Pastikan pengguna hanya mengakses rekaman mereka sendiri
  • Akses berbasis tim: Membatasi visibilitas ke anggota tim atau grup tertentu
  • Persyaratan kepatuhan: Menerapkan pembatasan akses data di tingkat database

Aktifkan RLS

Anda dapat mengaktifkan RLS melalui Aplikasi Lakebase atau menggunakan pernyataan SQL. Untuk petunjuk tentang menggunakan Aplikasi Lakebase, lihat Mengaktifkan keamanan tingkat baris.

Peringatan

Jika Anda mengaktifkan tabel tanpa RLS, tab API di Aplikasi Lakebase menampilkan peringatan bahwa pengguna yang diautentikasi dapat melihat semua baris dalam tabel tersebut. API Data berinteraksi langsung dengan skema Postgres Anda, dan karena API dapat diakses melalui internet, sangat penting untuk memberlakukan keamanan di tingkat database menggunakan keamanan tingkat baris PostgreSQL.

Untuk mengaktifkan RLS menggunakan SQL, jalankan perintah berikut:

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Membuat kebijakan RLS

Setelah mengaktifkan RLS pada tabel, Anda harus membuat kebijakan yang menentukan aturan akses. Tanpa kebijakan, pengguna tidak dapat mengakses baris apa pun (semua baris disembunyikan secara default).

Cara kerja kebijakan: Saat RLS diaktifkan pada tabel, pengguna hanya dapat melihat baris yang cocok dengan setidaknya satu kebijakan. Semua baris lainnya difilter keluar. Pemilik tabel, peran dengan atribut BYPASSRLS, dan superuser dapat mengabaikan sistem keamanan baris (meskipun superuser tidak didukung di Lakebase).

Nota

Di Lakebase, current_user mengembalikan alamat email pengguna yang diautentikasi (misalnya, user@databricks.com). Gunakan ini dalam kebijakan RLS Anda untuk mengidentifikasi pengguna mana yang membuat permintaan.

Sintaks kebijakan dasar:

CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);
  • policy_name: Nama deskriptif untuk kebijakan
  • table_name: Tabel untuk menerapkan kebijakan
  • KE role_name: (Opsional). Menentukan peran dari kebijakan ini. Hilangkan klausa ini untuk menerapkan kebijakan ke semua peran.
  • USING (condition): Kondisi yang menentukan baris mana yang terlihat

Tutorial RLS

Tutorial berikut menggunakan skema sampel dari dokumentasi ini (klien, proyek, tabel tugas) untuk menunjukkan cara menerapkan keamanan tingkat baris.

Skenario: Anda memiliki beberapa pengguna yang seharusnya hanya melihat klien yang ditetapkan dan proyek terkait. Batasi akses sehingga:

  • alice@databricks.com hanya dapat melihat klien dengan ID 1 dan 2
  • bob@databricks.com hanya dapat melihat klien dengan ID 2 dan 3

Langkah 1: Aktifkan RLS pada tabel klien

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Langkah 2: Membuat kebijakan untuk Alice

CREATE POLICY alice_clients ON clients
  TO "alice@databricks.com"
  USING (id IN (1, 2));

Langkah 3: Buat kebijakan untuk Bob

CREATE POLICY bob_clients ON clients
  TO "bob@databricks.com"
  USING (id IN (2, 3));

Langkah 4: Menguji kebijakan

Ketika Alice membuat permintaan API:

# Alice's token in the Authorization header
curl -H "Authorization: Bearer $ALICE_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name"

Respons (Alice hanya melihat klien 1 dan 2):

[
  { "id": 1, "name": "Acme Corp" },
  { "id": 2, "name": "TechStart Inc" }
]

Ketika Bob membuat permintaan API:

# Bob's token in the Authorization header
curl -H "Authorization: Bearer $BOB_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name"

Respons (Bob hanya melihat klien 2 dan 3):

[
  { "id": 2, "name": "TechStart Inc" },
  { "id": 3, "name": "Global Solutions" }
]

Pola RLS umum

Pola-pola ini mencakup persyaratan keamanan umum untuk API Data:

Kepemilikan pengguna - Membatasi baris untuk pengguna yang diautentikasi:

CREATE POLICY user_owned_data ON tasks
  USING (assigned_to = current_user);

Isolasi penyewa - Membatasi baris ke organisasi pengguna:

CREATE POLICY tenant_data ON clients
  USING (tenant_id = (
    SELECT tenant_id
    FROM user_tenants
    WHERE user_email = current_user
  ));

Keanggotaan tim - Membatasi baris ke tim pengguna:

CREATE POLICY team_projects ON projects
  USING (client_id IN (
    SELECT client_id
    FROM team_clients
    WHERE team_id IN (
      SELECT team_id
      FROM user_teams
      WHERE user_email = current_user
    )
  ));

Akses berbasis peran - Membatasi baris berdasarkan keanggotaan peran:

CREATE POLICY manager_access ON tasks
  USING (
    status = 'pending' OR
    pg_has_role(current_user, 'managers', 'member')
  );

Baca-saja untuk peran tertentu - Kebijakan yang berbeda untuk operasi yang berbeda:

-- Allow all users to read their assigned tasks
CREATE POLICY read_assigned_tasks ON tasks
  FOR SELECT
  USING (assigned_to = current_user);

-- Only managers can update tasks
CREATE POLICY update_tasks ON tasks
  FOR UPDATE
  TO "managers"
  USING (true);

Sumber daya tambahan

Untuk informasi komprehensif tentang menerapkan RLS, termasuk jenis kebijakan, praktik terbaik keamanan, dan pola tingkat lanjut, lihat dokumentasi Kebijakan Keamanan Baris PostgreSQL.

Untuk informasi selengkapnya tentang izin, lihat Mengelola izin.

Referensi API

Bagian ini mengasumsikan Anda telah menyelesaikan langkah-langkah penyiapan, mengonfigurasi izin, dan menerapkan keamanan tingkat baris. Bagian berikut ini menyediakan informasi referensi untuk menggunakan API Data, termasuk operasi umum, fitur tingkat lanjut, pertimbangan keamanan, dan detail kompatibilitas.

Operasi dasar

Rekaman kueri

Ambil rekaman dari tabel menggunakan HTTP GET:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients"

Contoh respons:

[
  { "id": 1, "name": "Acme Corp", "email": "contact@acme.com", "company": "Acme Corporation", "phone": "+1-555-0101" },
  {
    "id": 2,
    "name": "TechStart Inc",
    "email": "hello@techstart.com",
    "company": "TechStart Inc",
    "phone": "+1-555-0102"
  }
]

Memfilter hasil

Gunakan parameter kueri untuk memfilter hasil. Contoh ini mengambil data klien dengan id lebih besar dari atau sama dengan 2:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?id=gte.2"

Contoh respons:

[
  { "id": 2, "name": "TechStart Inc", "email": "hello@techstart.com" },
  { "id": 3, "name": "Global Solutions", "email": "info@globalsolutions.com" }
]

Memilih kolom tertentu dan menggabungkan tabel

select Gunakan parameter untuk mengambil kolom tertentu dan menggabungkan tabel terkait:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name,projects(id,name)&id=gte.2"

Contoh respons:

[
  { "id": 2, "name": "TechStart Inc", "projects": [{ "id": 3, "name": "Database Migration" }] },
  { "id": 3, "name": "Global Solutions", "projects": [{ "id": 4, "name": "API Integration" }] }
]

Sisipkan rekaman

Buat rekaman baru menggunakan HTTP POST:

curl -X POST \
  -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Client",
    "email": "newclient@example.com",
    "company": "New Company Inc",
    "phone": "+1-555-0104"
  }' \
  "$REST_ENDPOINT/public/clients"

Memperbarui rekaman

Perbarui rekaman yang ada menggunakan HTTP PATCH:

curl -X PATCH \
  -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1-555-0199"}' \
  "$REST_ENDPOINT/public/clients?id=eq.1"

Hapus rekaman

Hapus rekaman menggunakan HTTP DELETE:

curl -X DELETE \
  -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?id=eq.5"

Fitur tingkat lanjut

Pengaturan halaman

Kontrol jumlah rekaman yang dikembalikan menggunakan limit parameter dan offset :

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/tasks?limit=10&offset=0"

Pengurutan

Urutkan hasil menggunakan order parameter:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/tasks?order=due_date.desc"

Pemfilteran kompleks

Gabungkan beberapa kondisi filter:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/tasks?status=eq.in_progress&priority=eq.high"

Operator filter umum:

  • eq -Sama
  • gte - lebih besar dari atau sama dengan
  • lte - kurang dari atau sama dengan
  • neq - tidak sama dengan
  • like - pencocokan pola
  • in - cocok dengan nilai apa pun dalam daftar

Untuk informasi selengkapnya tentang parameter kueri dan fitur API yang didukung, lihat referensi POSTGREST API. Untuk informasi kompatibilitas khusus Lakebase, lihat Kompatibilitas PostgREST.

Referensi kompatibilitas fitur

Bagian ini mencantumkan fitur PostgREST yang memiliki perilaku berbeda atau tidak didukung di Lakebase Data API.

Autentikasi dan otorisasi

Fitur Kedudukan Detail lebih lanjut
Konfigurasi JWT Tidak berlaku Lakebase Data API menggunakan token OAuth Azure Databricks alih-alih autentikasi JWT. Opsi konfigurasi khusus JWT (rahasia kustom, kunci RS256, validasi audiens) tidak tersedia.

Penyematan sumber daya

Fitur Kedudukan Detail lebih lanjut
Hubungan komputasi Tidak didukung Hubungan kustom yang ditentukan melalui fungsi database yang mengembalikan SETOF atau rekaman tunggal tidak didukung. Hanya hubungan kunci asing yang dapat disematkan.
Penyematan gabungan dalam (!inner petunjuk) Tidak didukung !inner Petunjuk yang mengonversi gabungan kiri ke gabungan dalam untuk memfilter baris induk berdasarkan kriteria anak tidak didukung. Contoh: ?select=*,clients!inner(*)&clients.id=eq.1

Format respons

Fitur Kedudukan Detail lebih lanjut
Penangan jenis media kustom Tidak didukung Format output kustom melalui agregat PostgreSQL (format biner, XML, buffer protokol) tidak didukung.
Null yang dilucuti Tidak didukung Parameter nulls=stripped jenis media yang menghapus bidang null dari respons JSON tidak didukung. Contoh: Accept: application/vnd.pgrst.object+json;nulls=stripped
PostGIS GeoJSON Didukung sebagian Kolom geometri PostGIS dapat dikueri, tetapi pemformatan GeoJSON otomatis melalui Accept: application/geo+json header tidak tersedia.

Penomoran halaman dan penghitungan

Fitur Kedudukan Detail lebih lanjut
Jumlah yang direncanakan Tidak didukung Opsi Prefer: count=planned yang menggunakan perencana kueri PostgreSQL untuk memperkirakan jumlah hasil tidak didukung. Gunakan Prefer: count=exact sebagai gantinya.
Estimasi jumlah Tidak didukung Opsi Prefer: count=estimated yang menggunakan statistik PostgreSQL untuk perkiraan jumlah tidak didukung. Gunakan Prefer: count=exact sebagai gantinya.

Preferensi permohonan

Fitur Kedudukan Detail lebih lanjut
Preferensi zona waktu Didukung sebagian Terdapat penanganan zona waktu, tetapi header Prefer: timezone=America/Los_Angeles untuk mengganti zona waktu server tidak didukung. Konfigurasikan zona waktu server atau gunakan fungsi zona waktu tingkat database.
Kontrol transaksi Tidak didukung Kontrol transaksi melalui Prefer: tx=commit header dan Prefer: tx=rollback tidak didukung.
Mode penanganan preferensi Tidak didukung Opsi Prefer: handling=strict dan Prefer: handling=lenient untuk mengontrol bagaimana preferensi yang tidak valid ditangani tidak didukung.

Observability

Lakebase Data API mengimplementasikan fitur pengamatannya sendiri. Fitur pengamatan PostgREST berikut ini tidak didukung:

Fitur Kedudukan Detail lebih lanjut
Paparan rencana kueri Tidak didukung Header Accept: application/vnd.pgrst.plan+json yang mengekspos output PostgreSQL EXPLAIN untuk analisis performa tidak didukung.
header Server-Timing Tidak didukung Header Server-Timing yang menyediakan perincian waktu permintaan tidak didukung. Lakebase mengimplementasikan fitur pengamatannya sendiri.
Lacak penyebaran header Tidak didukung Penyebaran header jejak X-Request-Id dan kustom untuk pelacakan terdistribusi tidak didukung. Lakebase mengimplementasikan fitur pengamatannya sendiri.

Konfigurasi tingkat lanjut

Fitur Kedudukan Detail lebih lanjut
Pengaturan aplikasi (GUC) Tidak didukung Meneruskan nilai konfigurasi kustom ke fungsi database melalui POSTGreSQL GUC tidak didukung.
Fungsi pra-permintaan Tidak didukung Konfigurasi db-pre-request yang memungkinkan menentukan fungsi database untuk dijalankan sebelum setiap permintaan tidak didukung.

Untuk informasi selengkapnya tentang fitur PostgREST, lihat dokumentasi PostgREST.

Pertimbangan keamanan

API Data memberlakukan model keamanan database Anda di beberapa tingkat:

  • Autentikasi: Semua permintaan memerlukan autentikasi token OAuth yang valid
  • Akses berbasis peran: Izin tingkat database mengontrol tabel dan operasi mana yang dapat diakses pengguna
  • Keamanan tingkat baris: Kebijakan RLS memberlakukan kontrol akses mendetail, membatasi baris tertentu mana yang dapat dilihat atau diubah pengguna
  • Konteks pengguna: API mengasumsikan identitas pengguna yang diautentikasi, memastikan izin dan kebijakan database berlaku dengan benar

Untuk penerapan produksi:

  1. Menerapkan keamanan tingkat baris: Gunakan kebijakan RLS untuk membatasi akses data di tingkat baris. Ini sangat penting untuk aplikasi multi-tenant dan data yang dimiliki oleh pengguna. Lihat keamanan tingkat baris.
  2. Berikan izin minimal: Hanya berikan izin yang dibutuhkan pengguna (SELECT, , INSERTUPDATE, DELETE) pada tabel tertentu daripada memberikan akses luas.
  3. Gunakan peran terpisah per aplikasi: Buat peran khusus untuk aplikasi atau layanan yang berbeda daripada berbagi satu peran.
  4. Akses audit secara teratur: Tinjau izin yang diberikan dan kebijakan RLS secara berkala untuk memastikannya sesuai dengan persyaratan keamanan Anda.

Untuk informasi tentang mengelola peran dan izin, lihat:

  • Last updated on