Aracılığıyla paylaş

Lakebase Data API'si

Önemli

Lakebase Otomatik Ölçeklendirme şu bölgelerde kullanılabilir: eastus, eastus2, centralus, southcentralus, westus, westus2, canadacentral, brazilsouth, northeurope, uksouth, westeurope, australiaeast, centralindia, southeastasia.

Lakebase Otomatik Ölçeklendirme, otomatik ölçeklendirme işlemi, sıfıra ölçeklendirme, dallanma ve anında geri yükleme ile Lakebase'in en son sürümüdür. Lakebase Tedarik Edilmiş bir kullanıcıysanız, bkz. Lakebase Tedarik Edilmiş.

Lakebase Veri API'si, standart HTTP yöntemlerini kullanarak Doğrudan Lakebase Postgres veritabanınızla etkileşim kurmanızı sağlayan PostgREST uyumlu bir RESTful arabirimidir. Veritabanı şemanızdan türetilen API uç noktaları seçerek özel arka uç geliştirmesine gerek kalmadan verilerinizde güvenli CRUD (Oluşturma, Okuma, Güncelleştirme, Silme) işlemlerine olanak sağlar.

Genel bakış

Veri API'si, veritabanı şemanıza göre otomatik olarak RESTful uç noktaları oluşturur. Veritabanınızdaki her tablo HTTP istekleri aracılığıyla erişilebilir hale gelir ve şunları gerçekleştirmenizi sağlar:

  • Esnek filtreleme, sıralama ve sayfalandırma ile HTTP isteklerini kullanarak GET
  • HTTP POST isteklerini kullanarak kayıt ekleme
  • HTTP PATCH veya PUT isteklerini kullanarak kayıtları güncelleştirme
  • HTTP DELETE isteklerini kullanarak kayıtları silme
  • HTTP POST isteklerini kullanarak işlevleri RPC olarak yürütme

Bu yaklaşım, özel API kodu yazma ve koruma gereksinimini ortadan kaldırarak uygulama mantığınıza ve veritabanı şemanıza odaklanmanızı sağlar.

PostgREST uyumluluğu

Lakebase Veri API'si PostgREST belirtimi ile uyumludur. Şunları yapabilirsiniz:

  • Mevcut PostgREST istemci kitaplıklarını ve araçlarını kullanma
  • Filtreleme, sıralama ve sayfalandırma için PostgREST kurallarını izleyin
  • PostgREST topluluğundan belgeleri ve örnekleri uyarlama

Uyarı

Lakebase Veri API'si, Azure Databricks'in PostgREST belirtimi ile uyumlu olacak şekilde tasarlanmış uygulamasıdır. Veri API'si bağımsız bir uygulama olduğundan, Lakebase ortamı için geçerli olmayan bazı PostgREST özellikleri dahil değildir. Özellik uyumluluğu hakkında ayrıntılı bilgi için bkz . Özellik uyumluluğu başvurusu.

API özellikleri, sorgu parametreleri ve özellikleri hakkında kapsamlı ayrıntılar için bkz. PostgREST API başvurusu.

Kullanım örnekleri

Lakebase Veri API'si aşağıdakiler için idealdir:

  • Web uygulamaları: HTTP istekleri aracılığıyla veritabanınızla doğrudan etkileşim kuran ön uçlar oluşturun
  • Mikro hizmetler: REST API'leri aracılığıyla veritabanı kaynaklarına erişen basit hizmetler oluşturma
  • Sunucusuz mimariler: Sunucusuz işlevler ve uç bilgi işlem platformlarıyla tümleştirme
  • Mobil uygulamalar: ReSTful arabirimi aracılığıyla mobil uygulamalara doğrudan veritabanı erişimi sağlama
  • Üçüncü taraf tümleştirmeleri: Dış sistemlerin verileri güvenli bir şekilde okumasını ve yazmasını sağlama

Veri API'sini ayarlama

Bu bölüm, gerekli rolleri oluşturmaktan ilk API isteğinizi oluşturmaya kadar Veri API'sini ayarlama konusunda size yol gösterir.

Önkoşullar

Veri API'sinde Bir Lakebase Postgres Otomatik Ölçeklendirme veritabanı projesi gerekir. Bir tane yoksa bkz. Veritabanı projelerine başlama.

Tavsiye

Veri API'sini test için örnek tablolara ihtiyacınız varsa, Veri API'sini etkinleştirmeden önce bunları oluşturun. Tam bir örnek şema için bkz. Örnek şema.

Veri API'sini etkinleştirme

Veri API'si, oturum açmak dışında hiçbir izin gerektirmeyen adlı authenticatortek bir Postgres rolü aracılığıyla tüm veritabanı erişimini sağlar. Lakebase Uygulaması aracılığıyla Veri API'sini etkinleştirdiğinizde, bu rol ve gerekli altyapı otomatik olarak oluşturulur.

Veri API'sini etkinleştirmek için:

  1. Projenizde Veri API'si sayfasına gidin.
  2. Veri API'sini Etkinleştir'e tıklayın.

Veri API'sini Etkinleştir düğmesi

Bu, authenticator rolünü oluşturma, pgrst şemayı yapılandırma ve public şemayı API aracılığıyla gösterme dahil olmak üzere tüm kurulum adımlarını otomatik olarak gerçekleştirir.

Uyarı

Ek şemaları (ötesinde public) kullanıma sunmanız gerekiyorsa , Gelişmiş Veri API'sinin ayarlarında kullanıma sunulan şemaları değiştirebilirsiniz.

Veri API'sini etkinleştirdikten sonra

Veri API'sini etkinleştirdikten sonra Lakebase Uygulaması , Veri API'sini iki sekmeyle görüntüler: API ve Ayarlar.

API URL'sini ve güvenlik seçeneklerini gösteren Veri API'si sayfası

API sekmesi şunları sağlar:

  • API URL'si: Uygulama kodunuzda ve API isteklerinizde kullanılacak REST uç nokta URL'si. Görüntülenen URL şemayı içermez, bu nedenle API istekleri yaparken URL'ye şema adını (örneğin, /public) eklemeniz gerekir.
  • Şema önbelleğini yenile: Veritabanı şemanızda değişiklik yaptıktan sonra API'nin şema önbelleğini yenilemek için bir düğme. Bkz. Şema önbelleğini yenileme.
  • Verilerinizi koruma: Tablolarınız için Postgres satır düzeyi güvenliği (RLS) etkinleştirme seçenekleri. Bkz . Satır düzeyi güvenliği etkinleştirme.

Ayarlar sekmesi, kullanıma sunulan şemalar, en fazla satır sayısı, CORS ayarları ve daha fazlası gibi API davranışını yapılandırma seçenekleri sağlar. Bkz. Gelişmiş Veri API'si ayarları.

Örnek şema (isteğe bağlı)

Bu belgedeki örneklerde aşağıdaki şema kullanılır. Kendi tablolarınızı oluşturabilir veya test için bu örnek şemayı kullanabilirsiniz. Lakebase SQL Düzenleyicisi'ni veya herhangi bir SQL istemcisini kullanarak şu SQL deyimlerini çalıştırın:

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

Kullanıcı izinlerini yapılandırma

Azure Databricks OAuth taşıyıcı belirteçlerini, Authorization üst bilgisi aracılığıyla göndererek tüm Veri API isteklerini kimlik doğrulamanız gerekir. Veri API'si, kimliği doğrulanmış Azure Databricks kimliklerine erişimi kısıtlar ve temel izinleri Postgres yönetir.

Rol, authenticator API isteklerini işlerken istekte bulunan kullanıcının kimliğini varsayar. Bunun işe yaraması için, Veri API'sine erişen her Azure Databricks kimliğinin veritabanınızda karşılık gelen bir Postgres rolüne sahip olması gerekir. Önce Azure Databricks hesabınıza kullanıcı eklemeniz gerekiyorsa bkz. Hesabınıza kullanıcı ekleme.

Postgres rollerini eklemek

Uzantıyı databricks_auth kullanarak Azure Databricks kimliklerine karşılık gelen Postgres rolleri oluşturun:

Uzantıyı oluşturun:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

Postgres rolü ekleme:

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

Ayrıntılı yönergeler için bkz. SQL kullanarak Azure Databricks kimliği için OAuth rolü oluşturma.

Önemli

Veri API'sine erişmek için veritabanı sahibi hesabınızı (Lakebase projesini oluşturan Azure Databricks kimliği) kullanmayın. Rol authenticator, rolünüzü üstlenebilme yeteneğini gerektirir ve yükseltilmiş ayrıcalıklara sahip hesaplar için bu izin verilemez.

veritabanı sahibi rolüne authenticatorverme girişiminde bulunursanız şu hatayı alırsınız:

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.

Kullanıcılara izin verme

Azure Databricks kimlikleriniz için karşılık gelen Postgres rollerini oluşturduğunuza göre, bu Postgres rollerine izin vermeniz gerekir. Bu izinler, her kullanıcının API istekleri aracılığıyla etkileşim kurabileceği veritabanı nesnelerini (şemalar, tablolar, diziler, işlevler) denetler.

Standart SQL GRANT deyimlerini kullanarak izinler verin. Bu örnekte public şeması kullanılmaktadır; farklı bir şemayı açığa çıkarıyorsanız, public yerine şema adınızı yazın.

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

Bu örnek, public şeması için user@databricks.com kimliğine tam erişim izni verir. Bunu gerçek Azure Databricks kimliğiyle değiştirin ve gereksinimlerinize göre izinleri ayarlayın.

Önemli

Satır düzeyi güvenlik uygulama: Yukarıdaki izinler tablo düzeyinde erişim verir, ancak ÇOĞU API kullanım örneği için satır düzeyi kısıtlamalar gerekir. Örneğin, çok kiracılı uygulamalarda kullanıcılar yalnızca kendi verilerini veya kuruluşlarının verilerini görmelidir. Veritabanı düzeyinde ayrıntılı erişim denetimi uygulamak için PostgreSQL satır düzeyi güvenlik (RLS) ilkelerini kullanın. Bkz. Satır düzeyi güvenlik uygulama.

Kimlik doğrulama

Veri API'sine erişmek için HTTP isteğinizin üst bilgisinde Authorization bir Azure Databricks OAuth belirteci sağlamanız gerekir. Kimliği doğrulanmış Azure Databricks kimliği, veritabanı izinlerini tanımlayan karşılık gelen bir Postgres rolüne (önceki adımlarda oluşturulmuştur) sahip olmalıdır.

OAuth belirteci edinin

Önceki adımlarda Postgres rolü oluşturduğunuz Azure Databricks kimliğinizle çalışma alanınıza bağlanın ve bir OAuth token'ı edinin. Yönergeler için bkz. Kimlik doğrulaması .

İstekte bulunma

OAuth belirteciniz ve API URL'niz (Lakebase Uygulamasının API sekmesinden kullanılabilir) ile curl veya herhangi bir HTTP istemcisi kullanarak API isteklerinde bulunabilirsiniz. Şema adını (örneğin, /public) API URL'sine eklemeyi unutmayın. Aşağıdaki örneklerin, DBX_OAUTH_TOKEN ve REST_ENDPOINT ortam değişkenlerini dışa aktardığınızı varsaydığı kabul edilir.

Aşağıda beklenen çıkışı içeren örnek bir çağrı verilmiştir (örnek istemciler/projeler/görevler şeması kullanılarak):

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

Örnek yanıt:

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

API işlemleri hakkında daha fazla örnek ve ayrıntılı bilgi için API başvurusu bölümüne bakın. Sorgu parametreleri ve API özellikleri hakkında kapsamlı ayrıntılar için bkz. PostgREST API başvurusu. Lakebase'e özgü uyumluluk bilgileri için bkz. PostgREST uyumluluğu.

API'yi kapsamlı bir şekilde kullanmadan önce verilerinizi korumak için Satır düzeyi güvenliği yapılandırın.

Veri API'sini yönetme

Veri API'sini etkinleştirdikten sonra, Şema değişikliklerini ve güvenlik ayarlarını Lakebase Uygulaması aracılığıyla yönetebilirsiniz.

Şema önbelleğini yenileme

Veritabanı şemanızda değişiklikler yaptığınızda (tablo, sütun veya diğer şema nesneleri eklerken), şema önbelleğini yenilemeniz gerekir. Bu, değişikliklerinizi Veri API'sinde hemen kullanılabilir hale getirir.

Şema önbelleğini yenilemek için:

  1. Projenizin Uygulama Arka Ucu bölümünde Veri API'sine gidin.
  2. Şema önbelleğini yenile'ye tıklayın.

Veri API'si artık en son şema değişikliklerinizi yansıtır.

Satır düzeyi güvenliği etkinleştirme

Lakebase Uygulaması, veritabanınızdaki tablolar için satır düzeyi güvenliği (RLS) etkinleştirmek için hızlı bir yol sağlar. Şemanızda tablolar mevcut olduğunda , API sekmesinde aşağıdakilerin gösterildiği bir Verilerinizi koruyun bölümü görüntülenir:

  • RLS'nin etkinleştirildiği tablolar
  • RLS devre dışı bırakılmış tablolar (uyarılarla)
  • Tüm tablolarda RLS'yi etkinleştirmek için RLS'yi Etkinleştir düğmesi

Önemli

RLS'nin Lakebase Uygulaması aracılığıyla etkinleştirilmesi, tablolarınız için satır düzeyi güvenliği etkinleştirir. RLS etkinleştirildiğinde, tüm satırlara varsayılan olarak kullanıcılar erişemez duruma gelir (tablo sahipleri, BYPASSRLS özniteliğine sahip roller ve süper kullanıcılar hariç, ancak süper kullanıcılar Lakebase'de desteklenmez). Güvenlik gereksinimlerinize göre belirli satırlara erişim vermek için RLS ilkeleri oluşturmanız gerekir. İlke oluşturma hakkında bilgi almak için Satır düzeyi güvenlik bölümüne bakın.

Tablolarınız için RLS'yi etkinleştirmek için:

  1. Projenizin Uygulama Arka Ucu bölümünde Veri API'sine gidin.
  2. Verilerinizi koruyun bölümünde RLS'nin etkinleştirilmemiş olduğu tabloları gözden geçirin.
  3. Tüm tablolarda satır düzeyi güvenliği etkinleştirmek için RLS'yi Etkinleştir'e tıklayın.

SQL kullanarak tek tek tablolar için RLS'yi de etkinleştirebilirsiniz. Ayrıntılar için bkz. Satır düzeyi güvenlik .

Gelişmiş Veri API'si ayarları

Lakebase Uygulamasının API sekmesindeki Gelişmiş ayarlar bölümü, Veri API'si uç noktanızın güvenliğini, performansını ve davranışını denetler.

Açıklanan şemalar

Varsayılan:public

Hangi PostgreSQL şemalarının REST API uç noktaları olarak kullanıma sunulduğunı tanımlar. Varsayılan olarak, yalnızca public şema erişilebilir. Başka şemalar (örneğin , ) kullanıyorsanız, apiv1bunları eklemek için açılan listeden seçin.

Uyarı

İzinler geçerlidir: Buraya bir şema eklemek uç noktaları açığa çıkarır, ancak API tarafından kullanılan veritabanı rolünün şema üzerinde USAGE ayrıcalıkları ve tablolar üzerinde SELECT ayrıcalıkları olması gerekir.

Maksimum satır sayısı

Varsayılan: Boş

Tek bir API yanıtında döndürülecek satır sayısı üzerinde sabit bir sınır uygular. Bu, büyük sorgularda yanlışlıkla performans düşüşü oluşmasını önler. İstemciler bu eşik içindeki verileri almak için sayfalandırma sınırları kullanmalıdır. Bu, büyük veri aktarımlarından kaynaklanan beklenmeyen çıkış maliyetlerini de önler.

CORS izin verilen kaynaklar

Varsayılan: Boş (Tüm çıkış noktalarına izin verir)

Hangi web etki alanlarının tarayıcı kullanarak API'nizden veri getirebileceğini denetler.

  • Boş: İzin verir *(herhangi bir alan adı). Geliştirme için kullanışlıdır.
  • Üretim: Yetkisiz web sitelerinin API'nizi sorgulamasını önlemek için belirli etki alanlarınızı (örneğin, https://myapp.com) listeleyin.

OpenAPI belirtimi

Varsayılan: Devre Dışı

otomatik olarak oluşturulan bir OpenAPI 3 şemasının adresinde /openapi.jsonkullanılabilir olup olmadığını denetler. Bu şema tablolarınızı, sütunlarınızı ve REST uç noktalarınızı açıklar. Etkinleştirildiğinde şunları yapmak için kullanabilirsiniz:

  • API belgeleri oluşturma (Swagger UI, Redoc)
  • Yazılan istemci kitaplıkları oluşturma (TypeScript, Python, Go)
  • API'nizi Postman'e aktarma
  • API ağ geçitleri ve diğer OpenAPI tabanlı araçlarla tümleştirme

Sunucu zamanlama başlıkları

Varsayılan: Devre Dışı

Etkinleştirildiğinde, Veri API'si her yanıtta Server-Timing başlıklarını içerir. Bu üst bilgiler, isteğin farklı bölümlerinin işlenmesinin ne kadar sürdüğünü gösterir (örneğin, veritabanı yürütme süresi ve iç işlem süresi). Yavaş sorgularda hata ayıklamak, performansı ölçmek ve uygulamanızdaki gecikme sorunlarını gidermek için bu bilgileri kullanabilirsiniz.

Uyarı

Gelişmiş ayarlarda değişiklik yaptıktan sonra, bunları uygulamak için Kaydet'e tıklayın.

Satır düzeyi güvenlik

Satır düzeyi güvenlik (RLS) ilkeleri, kullanıcıların tabloda erişebileceği satırları kısıtlayarak ayrıntılı erişim denetimi sağlar.

RLS,Veri API'siyle nasıl çalışır? Kullanıcı API isteğinde bulunursa rol, authenticator kullanıcının kimliğini varsayar. Bu kullanıcının rolü için tanımlanan tüm RLS ilkeleri, PostgreSQL tarafından otomatik olarak uygulanır ve erişim haklarına göre erişebileceği veriler filtrelenir. Bu, veritabanı düzeyinde gerçekleşir, bu nedenle uygulama kodu tüm satırları sorgulamaya çalışsa bile, veritabanı yalnızca kullanıcının görmesine izin verilen satırları döndürür. Bu, uygulama kodunuzda filtreleme mantığı gerektirmeden derinlemesine savunma güvenliği sağlar.

RLS'nin API'ler için neden kritik öneme sahip olduğu: Bağlantı bağlamını denetlediğiniz doğrudan veritabanı bağlantılarından farklı olarak, HTTP API'leri veritabanınızı tek bir uç nokta üzerinden birden çok kullanıcıya sunar. Yalnızca tablo düzeyinde izinler, bir kullanıcının tabloya erişebilmesi clients durumunda filtreleme uygulamadığınız sürece tüm istemci kayıtlarına erişebileceği anlamına gelir. RLS ilkeleri, her kullanıcının yalnızca yetkili verilerini otomatik olarak görmesini sağlar.

RLS, şu nedenler için gereklidir:

  • Çok kiracılı uygulamalar: Farklı müşteriler veya kuruluşlar arasında verileri yalıtma
  • Kullanıcıya ait veriler: Kullanıcıların yalnızca kendi kayıtlarına eriştiklerinden emin olun
  • Ekip tabanlı erişim: Görünürlüğü ekip üyeleri veya belirli gruplar ile sınırlayın
  • Uyumluluk gereksinimleri: Veritabanı düzeyinde veri erişimi kısıtlamalarını zorunlu kılma

RLS'yi etkinleştirme

RLS'yi Lakebase Uygulaması aracılığıyla veya SQL deyimlerini kullanarak etkinleştirebilirsiniz. Lakebase Uygulamasını kullanma yönergeleri için bkz. Satır düzeyi güvenliği etkinleştirme.

Uyarı

RLS etkinleştirilmemiş tablolarınız varsa, Lakebase Uygulamasındaki API sekmesinde kimliği doğrulanmış kullanıcıların bu tablolardaki tüm satırları görüntüleyebileceğine ilişkin bir uyarı görüntülenir. Veri API'si doğrudan Postgres şemanızla etkileşim kurar ve API'ye İnternet üzerinden erişilebildiği için PostgreSQL satır düzeyi güvenliği kullanarak veritabanı düzeyinde güvenliği zorunlu kılmak çok önemlidir.

SQL kullanarak RLS'yi etkinleştirmek için aşağıdaki komutu çalıştırın:

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

RLS ilkeleri oluşturma

Tabloda RLS'yi etkinleştirdikten sonra, erişim kurallarını tanımlayan ilkeler oluşturmanız gerekir. İlkeler olmadan, kullanıcılar herhangi bir satıra erişemez (tüm satırlar varsayılan olarak gizlenir).

İlkeler nasıl çalışır? RLS bir tabloda etkinleştirildiğinde, kullanıcılar yalnızca en az bir ilkeyle eşleşen satırları görebilir. Diğer tüm satırlar filtrelenir. Tablo sahipleri, özniteliğine BYPASSRLS sahip roller ve süper kullanıcılar satır güvenlik sistemini atlayabilir (ancak lakebase'de süper kullanıcılar desteklenmez).

Uyarı

Lakebase'de, current_user kimliği doğrulanmış kullanıcının e-posta adresini (örneğin, user@databricks.com) döndürür. Hangi kullanıcının isteği yaptığını belirlemek için RLS ilkelerinizde bunu kullanın.

Temel ilke söz dizimi:

CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);
  • policy_name: İlke için açıklayıcı bir ad
  • table_name: İlkenin uygulanacağı tablo
  • TO role_name: İsteğe bağlı. Bu ilkenin rolünü belirtir. İlkeyi tüm rollere uygulamak için bu yan tümceyi atla.
  • USING (condition): Hangi satırların görünür olduğunu belirleyen koşul

RLS öğreticisi

Aşağıdaki öğreticide, satır düzeyi güvenliğin nasıl uygulaneceğini göstermek için bu belgelerden (istemciler, projeler, görev tabloları) örnek şema kullanılmaktadır.

Senaryo: Yalnızca atanmış istemcilerini ve ilgili projelerini görmesi gereken birden çok kullanıcınız var. Erişimi kısıtla:

  • alice@databricks.com yalnızca 1 ve 2 kimliklerine sahip istemcileri görüntüleyebilir
  • bob@databricks.com yalnızca 2 ve 3 kimlikli istemcileri görüntüleyebilir

1. Adım: İstemciler tablosunda RLS'yi etkinleştirme

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

2. Adım: Alice için ilke oluşturma

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

3. Adım: Bob için ilke oluşturma

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

4. Adım: İlkeleri test edin

Alice bir API isteğinde bulunurken:

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

Yanıt (Alice yalnızca 1 ve 2 istemcilerini görür):

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

Bob bir API isteğinde bulunursa:

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

Yanıt (Bob yalnızca 2 ve 3 istemcilerini görür):

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

Yaygın RLS desenleri

Bu desenler, Veri API'si için tipik güvenlik gereksinimlerini kapsar:

Kullanıcı sahipliği - Satırları kimliği doğrulanmış kullanıcıyla kısıtlar:

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

Kiracı izolasyonu - Satırları kullanıcının kuruluşuna göre filtreler:

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

Ekip üyeliği - Satırları kullanıcının ekiplerine kısıtlar:

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

Rol tabanlı erişim - Rol üyeliğine göre satırları kısıtlar:

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

Belirli roller için salt okunur - Farklı işlemler için farklı politikalar:

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

Ek kaynaklar

İlke türleri, en iyi güvenlik uygulamaları ve gelişmiş desenler dahil olmak üzere RLS uygulama hakkında kapsamlı bilgi için PostgreSQL Satır Güvenlik İlkeleri belgelerine bakın.

İzinler hakkında daha fazla bilgi için bkz. İzinleri yönetme.

API başvurusu

Bu bölümde kurulum adımlarını tamamladığınız, izinleri yapılandırdığınız ve satır düzeyi güvenlik uyguladığınız varsayılır. Aşağıdaki bölümlerde Yaygın işlemler, gelişmiş özellikler, güvenlik konuları ve uyumluluk ayrıntıları dahil olmak üzere Veri API'sini kullanmaya yönelik başvuru bilgileri sağlanır.

Temel işlemler

Kayıtları sorgulama

HTTP GETkullanarak bir tablodan kayıt alma:

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

Örnek yanıt:

[
  { "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"
  }
]

Sonuçları filtrele

Sonuçları filtrelemek için sorgu parametrelerini kullanın. Bu örnek, 2'den büyük veya buna eşit olan istemcileri id listeler.

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

Örnek yanıt:

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

Belirli sütunları seçme ve tabloları birleştirme

select Belirli sütunları almak ve ilgili tabloları birleştirmek için parametresini kullanın:

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

Örnek yanıt:

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

Kayıt ekleme

HTTP POST kullanarak yeni kayıtlar oluşturma:

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"

Kayıtları güncelleştirme

HTTP PATCH kullanarak mevcut kayıtları güncelleştirme:

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"

Kayıtları silme

HTTP DELETE kullanarak kayıtları silme:

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

Gelişmiş özellikler

Sayfalandırma

limit ve offset parametrelerini kullanarak döndürülen kayıtların sayısını kontrol edin.

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

Sıralama

Sonuçları parametresini kullanarak sıralayın order :

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

Karmaşık filtreleme

Birden çok filtre koşullarını birleştirme:

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

Yaygın filtre işleçleri:

  • eq -Eşit -tir
  • gte - büyüktür veya eşittir
  • lte - küçüktür veya eşittir
  • neq - eşit değil
  • like - desen eşleştirme
  • in - listedeki herhangi bir değerle eşleşir

Desteklenen sorgu parametreleri ve API özellikleri hakkında daha fazla bilgi için bkz. PostgREST API başvurusu. Lakebase'e özgü uyumluluk bilgileri için bkz. PostgREST uyumluluğu.

Özellik uyumluluğu referansı

Bu bölümde, farklı davranışlara sahip olan veya Lakebase Veri API'sinde desteklenmeyen PostgREST özellikleri listelenir.

Kimlik doğrulaması ve yetkilendirme

Özellik Statü Ayrıntılar
JWT yapılandırması Uygulanamaz Lakebase Veri API'sinde JWT kimlik doğrulaması yerine Azure Databricks OAuth belirteçleri kullanılır. JWT'ye özgü yapılandırma seçenekleri (özel gizli diziler, RS256 anahtarları, hedef kitle doğrulaması) kullanılamaz.

Kaynak ekleme

Özellik Statü Ayrıntılar
Hesaplanan ilişkiler Desteklenmez Veritabanı işlevleri aracılığıyla tanımlanan, SETOF veya tek kayıt döndüren özel ilişkiler desteklenmez. Yalnızca yabancı anahtar ilişkileri eklenebilir.
İç birleşim ekleme (!inner ipucu) Desteklenmez Çocuk kriterlerine göre ebeveyn satırlarını filtrelemek için sol birleşimleri iç birleşimlere dönüştüren !inner işareti desteklenmez. Örnek: ?select=*,clients!inner(*)&clients.id=eq.1

Yanıt biçimleri

Özellik Statü Ayrıntılar
Özel medya türü işleyicileri Desteklenmez PostgreSQL toplamaları (ikili biçimler, XML, protokol arabellekleri) aracılığıyla özel çıkış biçimleri desteklenmez.
Kaldırılan null değerler Desteklenmez nulls=stripped JSON yanıtlarından null alanları kaldıran medya türü parametresi desteklenmez. Örnek: Accept: application/vnd.pgrst.object+json;nulls=stripped
PostGIS GeoJSON Kısmen desteklenir PostGIS geometri sütunları sorgulanabilir, ancak üst bilgi aracılığıyla Accept: application/geo+json otomatik GeoJSON biçimlendirmesi kullanılamaz.

Sayfalandırma ve sayma

Özellik Statü Ayrıntılar
Planlanan sayı Desteklenmez Sonuç Prefer: count=planned sayılarını tahmin etmek için PostgreSQL'in sorgu planlayıcısını kullanan seçenek desteklenmez. Bunun yerine Prefer: count=exact kullanın.
Tahmini sayı Desteklenmez Yaklaşık Prefer: count=estimated sayımlar için PostgreSQL istatistiklerini kullanan seçenek desteklenmez. Bunun yerine Prefer: count=exact kullanın.

Talep tercihleri

Özellik Statü Ayrıntılar
Saat dilimi tercihi Kısmen desteklenir Saat dilimi işlemesi var, ancak sunucu saat dilimini Prefer: timezone=America/Los_Angeles geçersiz kılma üst bilgisi desteklenmiyor. Sunucu saat dilimini yapılandırın veya veritabanı düzeyinde saat dilimi işlevlerini kullanın.
İşlem denetimi Desteklenmez Prefer: tx=commit ve Prefer: tx=rollback üst bilgileri aracılığıyla işlem denetimi desteklenmez.
Tercih işleme modları Desteklenmez Geçersiz tercihlerinin nasıl işleneceğini denetlemek için Prefer: handling=strict ve Prefer: handling=lenient seçenekleri desteklenmez.

Observability

Lakebase Veri API'si kendi gözlemlenebilirlik özelliklerini uygular. Aşağıdaki PostgREST gözlemlenebilirlik özellikleri desteklenmez:

Özellik Statü Ayrıntılar
Sorgu planının ifşası Desteklenmez Accept: application/vnd.pgrst.plan+json Performans analizi için PostgreSQL EXPLAIN çıkışını açığa çıkaran üst bilgi desteklenmemektedir.
Server-Timing üst bilgisi Desteklenmez İstek zamanlaması dökümü sağlayan Server-Timing üst bilgisi desteklenmez. Lakebase kendi gözlemlenebilirlik özelliklerini uygular.
İzleme başlık yayılımı Desteklenmez Dağıtılmış izleme için X-Request-Id ve özel izleme başlığı yayılması desteklenmez. Lakebase kendi gözlemlenebilirlik özelliklerini uygular.

Gelişmiş yapılandırma

Özellik Statü Ayrıntılar
Uygulama ayarları (GUC' ler) Desteklenmez PostgreSQL GUC'leri aracılığıyla veritabanı işlevlerine özel yapılandırma değerleri geçirme desteklenmez.
İstek öncesi işlevi Desteklenmez Bu db-pre-request yapılandırma, her isteğin öncesinde çalıştırılabilecek bir veritabanı işlevini belirtmeye olanak tanıyorsa, desteklenmiyor.

PostgREST özellikleri hakkında daha fazla bilgi için PostgREST belgelerine bakın.

Güvenlikle ilgili dikkat edilmesi gerekenler

Veri API'si veritabanınızın güvenlik modelini birden çok düzeyde zorlar:

  • Kimlik doğrulaması: Tüm istekler geçerli OAuth belirteci kimlik doğrulaması gerektirir
  • Rol tabanlı erişim: Veritabanı düzeyinde izinler, kullanıcıların erişebileceği tabloları ve işlemleri denetler
  • Satır düzeyi güvenlik: RLS ilkeleri ayrıntılı erişim denetimi uygulayarak kullanıcıların görebileceği veya değiştirebileceği belirli satırları kısıtlar
  • Kullanıcı bağlamı: API, kimliği doğrulanmış kullanıcının kimliğini varsayarak veritabanı izinlerinin ve ilkelerinin doğru şekilde uygulandığından emin olur

Üretim dağıtımları için:

  1. Satır düzeyi güvenlik uygulama: Satır düzeyinde veri erişimini kısıtlamak için RLS ilkelerini kullanın. Bu özellikle çok kiracılı uygulamalar ve kullanıcıya ait veriler için önemlidir. Bkz. Satır düzeyi güvenlik.
  2. En az izin ver: Geniş erişim vermek yerine yalnızca belirli tablolarda kullanıcıların ihtiyaç duyduğu izinleri (SELECT, INSERT, UPDATE, DELETE) verin.
  3. Uygulama başına ayrı roller kullanın: Tek bir rol paylaşmak yerine farklı uygulamalar veya hizmetler için ayrılmış roller oluşturun.
  4. Erişimi düzenli olarak denetleme: Güvenlik gereksinimlerinize uygun olduğundan emin olmak için verilen izinleri ve RLS ilkelerini düzenli aralıklarla gözden geçirin.

Rolleri ve izinleri yönetme hakkında bilgi için bkz:

  • Last updated on