Sdílet prostřednictvím

Lakebase Data API

Důležité

Automatické škálování LakeBase je v beta verzích v následujících oblastech: eastus2, westeurope, westus.

Automatické škálování LakeBase je nejnovější verze LakeBase s automatickým škálováním výpočetních prostředků, škálováním na nulu, větvení a okamžitým obnovením. Porovnání funkcí se službou Lakebase Provisioned najdete v tématu Volba mezi verzemi.

Rozhraní Lakebase Data API je kompatibilní s PostgREST a nabízí RESTful rozhraní, které umožňuje přímou interakci s vaší Lakebase Postgres databází pomocí standardních HTTP metod. Nabízí koncové body rozhraní API odvozené ze schématu databáze, což umožňuje zabezpečené operace CRUD (vytvoření, čtení, aktualizace, odstranění) na vašich datech bez nutnosti vlastního vývoje back-endu.

Přehled

Rozhraní DATA API automaticky generuje koncové body RESTful na základě vašeho schématu databáze. Každá tabulka v databázi bude přístupná prostřednictvím požadavků HTTP, což vám umožní:

  • Dotazování dat pomocí požadavků HTTP GET s flexibilním filtrováním, řazením a stránkováním
  • Vkládání záznamů pomocí požadavků HTTP POST
  • Aktualizace záznamů pomocí požadavků HTTP PATCH nebo PUT
  • Odstranění záznamů pomocí požadavků HTTP DELETE
  • Spuštění funkcí jako RPC pomocí HTTP POST požadavků

Tento přístup eliminuje nutnost psát a udržovat vlastní kód rozhraní API, takže se můžete soustředit na logiku aplikace a schéma databáze.

Kompatibilita PostgREST

Rozhraní Lakebase Data API je kompatibilní se specifikací PostgREST . Můžete:

  • Použití existujících klientských knihoven a nástrojů PostgREST
  • Postupujte podle konvencí PostgREST pro filtrování, řazení a stránkování.
  • Přizpůsobte dokumentaci a příklady z komunity PostgREST

Poznámka:

Rozhraní Lakebase Data API je implementace Azure Databricks navržená tak, aby byla kompatibilní se specifikací PostgREST. Vzhledem k tomu, že rozhraní Data API je nezávislá implementace, některé funkce PostgREST, které se nevztahují na prostředí Lakebase, nejsou zahrnuty. Podrobnosti o kompatibilitě funkcí najdete v referenčních informacích k kompatibilitě funkcí.

Podrobné informace o funkcích rozhraní API, parametrech dotazů a možnostech najdete v referenčních informacích k rozhraní PostgREST API.

Případy použití

Rozhraní Lakebase Data API je ideální pro:

  • Webové aplikace: Vytváření front-endů, které přímo komunikují s databází prostřednictvím požadavků HTTP
  • Mikroslužby: Vytváření jednoduchých služeb, které přistupují k databázovým prostředkům prostřednictvím rozhraní REST API
  • Bezserverové architektury: Integrace s bezserverovými funkcemi a hraničními výpočetními platformami
  • Mobilní aplikace: Poskytování přímého přístupu k databázi prostřednictvím rozhraní RESTful
  • Integrace třetích stran: Povolení bezpečného čtení a zápisu dat externími systémy

Nastavení rozhraní DATA API

Tato část vás provede nastavením rozhraní API pro data, od vytvoření požadovaných rolí až po vytvoření prvního požadavku rozhraní API.

Požadavky

Rozhraní Data API vyžaduje projekt databáze Lakebase Postgres s automatickým škálováním. Pokud ho nemáte, přečtěte si téma Začínáme s databázovými projekty.

Návod

Pokud potřebujete ukázkové tabulky pro testování rozhraní DATA API, vytvořte je před povolením rozhraní DATA API. Kompletní ukázkové schéma najdete v ukázkovém schématu .

Povolení rozhraní DATA API

Rozhraní Data API provádí veškerý přístup k databázi prostřednictvím jedné role Postgres s názvem authenticator, která nevyžaduje žádná oprávnění s výjimkou přihlášení. Když povolíte rozhraní DATA API prostřednictvím aplikace Lakebase, tato role a nezbytná infrastruktura se vytvoří automaticky.

Povolení rozhraní API pro data:

  1. Ve svém projektu přejděte na stránku Data API.
  2. Klikněte na Povolit rozhraní API pro data.

Tlačítko Povolit rozhraní API pro data

Tím se automaticky provede všechny kroky nastavení, včetně vytvoření authenticator role, konfigurace pgrst schématu a zveřejnění schématu public prostřednictvím rozhraní API.

Poznámka:

Pokud potřebujete zveřejnit další schémata (nad rámec public), můžete upravit vystavená schémata v nastavení rozhraní Advanced Data API.

Po povolení rozhraní DATA API

Po povolení rozhraní DATA API aplikace Lakebase zobrazí stránku rozhraní DATA API se dvěma kartami: rozhraní API a nastavení.

Stránka rozhraní API pro data zobrazující adresu URL rozhraní API a možnosti zabezpečení

Karta rozhraní API poskytuje:

  • Adresa URL rozhraní API: Adresa URL koncového bodu REST, která se má použít v kódu aplikace a požadavcích rozhraní API. Zobrazená adresa URL neobsahuje schéma, takže při vytváření požadavků rozhraní API musíte k adrese URL připojit název schématu (například /public).
  • Aktualizovat mezipaměť schématu: Tlačítko pro aktualizaci mezipaměti schématu rozhraní API po provedení změn schématu databáze. Viz Aktualizace mezipaměti schématu.
  • Ochrana dat: Možnosti povolení zabezpečení na úrovni řádků (RLS) postgres pro tabulky Viz Povolení zabezpečení na úrovni řádků.

Karta Nastavení poskytuje možnosti konfigurace chování rozhraní API, jako jsou vystavená schémata, maximální počet řádků, nastavení CORS a další. Viz Upřesňující nastavení rozhraní API pro data.

Ukázkové schéma (volitelné)

Příklady v této dokumentaci používají následující schéma. Můžete vytvořit vlastní tabulky nebo použít toto ukázkové schéma pro testování. Pomocí editoru SQL Lakebase nebo libovolného klienta SQL spusťte tyto příkazy SQL:

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

Konfigurace uživatelských oprávnění

Všechny požadavky rozhraní Data API musíte ověřit pomocí nosných tokenů Azure Databricks OAuth, které se odesílají prostřednictvím hlavičky Authorization . Rozhraní Data API omezuje přístup k ověřeným identitám Azure Databricks a postgres řídí příslušná oprávnění.

Role authenticator předpokládá identitu žádajícího uživatele při zpracování požadavků rozhraní API. Aby to fungovalo, musí mít každá identita Azure Databricks, která přistupuje k rozhraní Data API, ve vaší databázi odpovídající roli Postgres. Pokud potřebujete nejprve přidat uživatele do svého účtu Azure Databricks, přečtěte si téma Přidání uživatelů do vašeho účtu.

Přidání rolí Postgres

databricks_auth Pomocí rozšíření vytvořte role Postgres, které odpovídají identitám Azure Databricks:

Vytvořte rozšíření:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

Přidání role Postgres:

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

Podrobné pokyny najdete v tématu Vytvoření role OAuth pro identitu Azure Databricks pomocí SQL.

Důležité

Pro přístup k rozhraní Data API nepoužívejte účet vlastníka databáze (identitu Azure Databricks, která vytvořila projekt Lakebase). Tato authenticator role vyžaduje možnost převzít vaši roli a toto oprávnění nelze udělit pro účty se zvýšenými oprávněními.

Pokud se pokusíte udělit roli authenticatorvlastníka databáze, zobrazí se tato chyba:

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.

Udělení oprávnění uživatelům

Teď, když jste pro své identity Azure Databricks vytvořili odpovídající role Postgres, musíte těmto rolím Postgres udělit oprávnění. Tato oprávnění řídí, se kterými databázovými objekty (schémata, tabulky, sekvencemi, funkcemi) můžou jednotliví uživatelé interagovat prostřednictvím požadavků rozhraní API.

Udělte oprávnění pomocí standardních příkazů SQL GRANT . Tento příklad používá public schéma. Pokud vystavujete jiné schéma, nahraďte public názvem schématu:

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

Tento příklad uděluje úplný přístup ke schématu public pro identitu user@databricks.com. Nahraďte ji skutečnou identitou Azure Databricks a upravte oprávnění na základě vašich požadavků.

Důležité

Implementace zabezpečení na úrovni řádků: Oprávnění uvedená výše udělují přístup na úrovni tabulky, ale většina případů použití rozhraní API vyžaduje omezení na úrovni řádků. Například v aplikacích s více tenanty by uživatelé měli vidět jenom svá vlastní data nebo data organizace. Pomocí zásad zabezpečení na úrovni řádků (RLS) PostgreSQL vynucujte jemně odstupňované řízení přístupu na úrovni databáze. Viz Implementace zabezpečení na úrovni řádků.

Autentizace

Pokud chcete získat přístup k rozhraní Data API, musíte v Authorization hlavičce požadavku HTTP zadat token Azure Databricks OAuth. Ověřená identita Azure Databricks musí mít odpovídající roli Postgres (vytvořenou v předchozích krocích), která definuje svá oprávnění k databázi.

Získání tokenu OAuth

Připojte se k pracovnímu prostoru jako uživatel Azure Databricks, pro kterého jste v předchozích krocích vytvořili roli Postgres, a získejte token OAuth. Pokyny najdete v tématu Ověřování .

Vytvoření žádosti

Pomocí tokenu OAuth a adresy URL rozhraní API (dostupné na kartě ROZHRANÍ API v aplikaci Lakebase) můžete požadavky rozhraní API provádět pomocí curl nebo libovolného klienta HTTP. Nezapomeňte k adrese URL rozhraní API připojit název schématu (například /public). Následující příklady předpokládají, že jste exportovali proměnné prostředí DBX_OAUTH_TOKEN a REST_ENDPOINT.

Tady je příklad volání s očekávaným výstupem (pomocí ukázkových klientů, projektů nebo schématu úkolů):

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

Příklad odpovědi:

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

Další příklady a podrobné informace o operacích rozhraní API najdete v referenční části rozhraní API . Podrobné informace o parametrech dotazu a možnostech rozhraní API najdete v referenčních informacích k rozhraní PostgREST API. Informace o kompatibilitě specifické pro Lakebase najdete v tématu Kompatibilita PostgREST.

Před rozsáhlým použitím rozhraní API nakonfigurujte zabezpečení na úrovni řádků pro ochranu dat.

Správa rozhraní API pro data

Po povolení rozhraní Data API můžete spravovat změny schématu a nastavení zabezpečení prostřednictvím aplikace Lakebase.

Aktualizace mezipaměti schématu

Když provedete změny schématu databáze (přidání tabulek, sloupců nebo jiných objektů schématu), musíte aktualizovat mezipaměť schématu. Změny se tak zpřístupní okamžitě prostřednictvím rozhraní DATA API.

Aktualizace mezipaměti schématu:

  1. V části Back-end aplikace vašeho projektu přejděte k rozhraní API pro data.
  2. Klikněte na Aktualizovat mezipaměť schématu.

Rozhraní API pro data teď odráží nejnovější změny schématu.

Povolení zabezpečení na úrovni řádků

Aplikace Lakebase poskytuje rychlý způsob, jak povolit zabezpečení na úrovni řádků (RLS) pro tabulky v databázi. Pokud ve schématu existují tabulky, na kartě rozhraní API se zobrazí oddíl Chránit vaše data , který ukazuje:

  • Tabulky s aktivovaným zabezpečením na úrovni řádků
  • Tabulky s vypnutým RLS (s upozorněními)
  • Tlačítko Povolit zabezpečení na úrovni řádků pro povolení zabezpečení na úrovni řádků pro všechny tabulky

Důležité

Zapnutím zabezpečení na úrovni řádků prostřednictvím aplikace Lakebase aktivujete toto zabezpečení pro vaše tabulky. Pokud je zabezpečení na úrovni řádků povolené, stanou se ve výchozím nastavení všechny řádky uživatelům nedostupné (s výjimkou vlastníků tabulek, rolí s atributem BYPASSRLS a superuživatelů, i když superuživatelé v Lakebase nejsou podporovaní). Musíte vytvořit zásady zabezpečení na úrovni řádků, které udělí přístup ke konkrétním řádkům na základě vašich požadavků na zabezpečení. Další informace o vytváření zásad naleznete v části Zabezpečení na úrovni řádků.

Jak povolit RLS pro vaše tabulky:

  1. V sekci App Backend vašeho projektu přejděte na Data API.
  2. V části Ochrana dat zkontrolujte tabulky, které nemají povolené RLS.
  3. Kliknutím na Povolit RLS aktivujete zabezpečení na úrovni řádků pro všechny tabulky.

Můžete také povolit zabezpečení na úrovni řádků (RLS) pro jednotlivé tabulky pomocí SQL ve vašich databázových systémech. Podrobnosti najdete v tématu Zabezpečení na úrovni řádků .

Pokročilá nastavení rozhraní API pro data

Část Pokročilá nastavení na kartě API v aplikaci Lakebase řídí zabezpečení, výkon a chování vašeho koncového bodu Data API.

Vystavená schémata

Výchozí:public

Definuje, která schémata PostgreSQL se zveřejňují jako koncové body rozhraní REST API. Ve výchozím nastavení je přístupné pouze public schéma. Pokud používáte jiná schémata (například api, v1), vyberte je z rozevíracího seznamu a přidejte je.

Poznámka:

Oprávnění platí: Přidání schématu sem zveřejňuje koncové body, ale role databáze používaná rozhraním API musí mít USAGE stále oprávnění ke schématu a SELECT oprávněním v tabulkách.

Maximální počet řádků

Výchozí: Prázdný

Vynucuje pevný limit počtu řádků, které se mají vrátit v jedné odpovědi rozhraní API. Tím zabráníte náhodnému snížení výkonu u velkých dotazů. Klienti by měli k načtení dat v rámci této prahové hodnoty použít omezení stránkování. Tím se také zabrání neočekávaným nákladům souvisejícím s odchozím přenosem velkých objemů dat.

Povolené zdroje CORS

Výchozí: Prázdné (umožňuje všechny zdroje)

Určuje, které webové domény můžou načítat data z vašeho rozhraní API pomocí prohlížeče.

  • Prázdné: Povoluje * (libovolnou doménu). Užitečné pro vývoj.
  • Produkce: Uveďte konkrétní domény (například https://myapp.com), abyste zabránili neoprávněným webům v dotazování se na vaše rozhraní API.

Specifikace OpenAPI

Výchozí: Zakázáno

Určuje, zda je k dispozici automaticky generované schéma OpenAPI 3 na adrese /openapi.json. Toto schéma popisuje tabulky, sloupce a koncové body REST. Pokud je tato možnost povolená, můžete ji použít k:

  • Generování dokumentace k rozhraní API (Swagger UI, Redoc)
  • Sestavte typové klientské knihovny (TypeScript, Python, Go)
  • Import rozhraní API do Postmanu
  • Integrace s bránami rozhraní API a dalšími nástroji založenými na OpenAPI

Hlavičky serverového časování

Výchozí: Zakázáno

Pokud je rozhraní API pro data povoleno, zahrnuje hlavičky Server-Timing do každé odpovědi. Tyto hlavičky ukazují, jak dlouho trvalo zpracování různých částí požadavku (například doba provádění databáze a doba interního zpracování). Tyto informace můžete použít k ladění pomalých dotazů, měření výkonu a řešení potíží s latencí ve vaší aplikaci.

Poznámka:

Po provedení změn v upřesňujících nastaveních je kliknutím na Uložit použijte.

Zabezpečení na úrovni řádků

Zásady zabezpečení na úrovni řádků (RLS) poskytují jemně odstupňované řízení přístupu tím, že omezují, ke kterým řádkům mají uživatelé přístup v tabulce.

Jak funguje zabezpečení na úrovni řádků s datovým rozhraním API: Když uživatel odešle požadavek na rozhraní API, role authenticator převezme identitu toho uživatele. Všechny zásady RLS (zabezpečení na úrovni řádků) definované pro tuto uživatelskou roli jsou automaticky vynucovány PostgreSQL, které filtruje data, k nimž má uživatel přístup. K tomu dochází na úrovni databáze, takže i když se kód aplikace pokusí dotazovat všechny řádky, databáze vrátí pouze řádky, které uživatel může zobrazit. To poskytuje zabezpečení do hloubky bez nutnosti filtrování logiky ve vašem aplikačním kódu.

Proč je RLS kritické pro API: Na rozdíl od přímých databázových připojení, kde řídíte kontext připojení, HTTP API odhalují vaši databázi více uživatelům prostřednictvím jednoho koncového bodu. Samotná oprávnění na úrovni tabulky znamenají, že pokud uživatel má přístup k clients tabulce, může přistupovat ke všem záznamům klienta, pokud neimplementujete filtrování. RLS - Zásady zabezpečení na úrovni řádků zajišťují, aby každý uživatel automaticky viděl jenom svá autorizovaná data.

RLS je nezbytné pro:

  • Aplikace s více tenanty: Izolace dat mezi různými zákazníky nebo organizacemi
  • Data vlastněná uživatelem: Zajistěte, aby uživatelé měli přístup jenom ke svým vlastním záznamům.
  • Přístup na základě týmu: Omezení viditelnosti pro členy týmu nebo konkrétní skupiny
  • Požadavky na dodržování předpisů: Vynucení omezení přístupu k datům na úrovni databáze

Povolit zabezpečení na úrovni řádků

Zabezpečení na úrovni řádků (RLS) můžete povolit prostřednictvím aplikace Lakebase nebo pomocí příkazů SQL. Pokyny k používání aplikace Lakebase najdete v tématu Povolení zabezpečení na úrovni řádků.

Výstraha

Pokud máte tabulky bez aktivovaného zabezpečení na úrovni řádků, karta API v aplikaci Lakebase zobrazí upozornění, že ověření uživatelé mohou zobrazit všechny řádky v těchto tabulkách. Rozhraní DATA API komunikuje přímo se schématem Postgres a protože rozhraní API je přístupné přes internet, je nezbytné vynutit zabezpečení na úrovni databáze pomocí zabezpečení na úrovni řádků PostgreSQL.

Pokud chcete povolit RLS (zabezpečení na úrovni řádků) pomocí SQL, spusťte následující příkaz:

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Vytvořte zásady RLS

Po povolení RLS (zabezpečení na úrovni řádků) v tabulce musíte vytvořit politiky, které definují pravidla přístupu. Bez zásad nemají uživatelé přístup k žádným řádkům (ve výchozím nastavení jsou všechny řádky skryté).

Jak fungují zásady: Když je v tabulce povoleno RLS, uživatelé mohou vidět jenom řádky, které odpovídají alespoň jedné zásadě. Vyfiltrují se všechny ostatní řádky. Vlastníci tabulek, role s atributem BYPASSRLS a superuživatelé můžou obejít systém zabezpečení řádků (i když superuživatelé nejsou v Lakebase podporováni).

Poznámka:

V Lakebase current_user vrátí e-mailovou adresu ověřeného uživatele (například user@databricks.com). Použijte to ve svých zásadách RLS (Zabezpečení na úrovni řádků) k identifikaci uživatele, který žádost podává.

Základní syntaxe zásad:

CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);
  • policy_name: Popisný název zásady
  • table_name: Tabulka, na které se má zásada použít
  • TO role_name: Volitelné. Určuje roli pro tuto zásadu. Vynecháte tuto klauzuli, aby se zásady použily u všech rolí.
  • USING (podmínka):Podmínka, která určuje, které řádky jsou viditelné

RLS tutoriál

Následující kurz používá ukázkové schéma z této dokumentace (klienti, projekty, tabulky úkolů) k zobrazení způsobu implementace zabezpečení na úrovni řádků.

Scénář: Máte více uživatelů, kteří by měli vidět pouze přiřazené klienty a související projekty. Omezit přístup tak, aby:

  • alice@databricks.com může zobrazit pouze klienty s ID 1 a 2.
  • bob@databricks.com může zobrazit pouze klienty s ID 2 a 3.

Krok 1: Povolení RLS v tabulce klientů

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Krok 2: Vytvoření zásady pro Alice

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

Krok 3: Vytvoření zásady pro Boba

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

Krok 4: Testování zásad

Když Alice odešle požadavek rozhraní API:

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

Odpověď (Alice vidí pouze klienty 1 a 2):

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

Když Bob vytvoří požadavek rozhraní API:

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

Odpověď (Bob vidí pouze klienty 2 a 3):

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

Běžné vzory RLS

Tyto vzory pokrývají typické požadavky na zabezpečení pro rozhraní API pro data:

Vlastnictví uživatele – Omezuje řádky na ověřeného uživatele:

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

Izolace nájemce – Omezuje řádky na organizaci uživatele:

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

Členství v týmu – Omezuje řádky na uživatelovy týmy:

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

Přístup na základě role – Omezuje řádky na základě členství v rolích:

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

Jen pro čtení pro konkrétní role – různé politiky pro různé operace:

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

Dodatečné zdroje

Podrobné informace o implementaci zabezpečení na úrovni řádků, včetně typů zásad, osvědčených postupů zabezpečení a pokročilých vzorů, najdete v dokumentaci k zásadám zabezpečení řádků PostgreSQL.

Další informace o oprávněních najdete v tématu Správa oprávnění.

Referenční informace k rozhraní API

V této části se předpokládá, že jste dokončili kroky nastavení, nakonfigurovali oprávnění a implementovali zabezpečení na úrovni řádků. Následující části obsahují referenční informace o používání rozhraní DATA API, včetně běžných operací, pokročilých funkcí, aspektů zabezpečení a podrobností o kompatibilitě.

Základní operace

Dotazování záznamů

Načtení záznamů z tabulky pomocí protokolu HTTP GET:

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

Příklad odpovědi:

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

Filtrování výsledků

K filtrování výsledků použijte parametry dotazu. Tento příklad načte klienty s id větší nebo rovnou 2:

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

Příklad odpovědi:

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

Výběr konkrétních sloupců a spojení tabulek

Pomocí parametru select můžete načíst konkrétní sloupce a spojit související tabulky:

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

Příklad odpovědi:

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

Vložení záznamů

Vytváření nových záznamů pomocí 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"

Záznamy typu Aktualizace

Aktualizace existujících záznamů pomocí 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"

Odstranění záznamů

Odstraňte záznamy pomocí HTTP DELETE:

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

Pokročilé funkce

Stránkování

Pomocí parametrů můžete řídit počet vrácených limitoffset záznamů:

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

Řazení

Výsledky můžete seřadit pomocí parametru order :

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

Komplexní filtrování

Kombinovat více podmínek filtru:

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

Běžné operátory filtru:

  • eq -Rovná
  • gte - větší než nebo rovno
  • lte - menší než nebo rovno
  • neq - nerovná se
  • like - Rozpoznávání vzorů
  • in - odpovídá libovolné hodnotě v seznamu.

Další informace o podporovaných parametrech dotazu a funkcích rozhraní API najdete v referenčních informacích k rozhraní PostgREST API. Informace o kompatibilitě specifické pro Lakebase najdete v tématu Kompatibilita PostgREST.

Referenční informace k kompatibilitě funkcí

Tato část obsahuje seznam funkcí PostgREST, které mají jiné chování nebo nejsou podporovány v rozhraní Lakebase Data API.

Autentizace a autorizace

Vlastnost Stav Podrobnosti
Konfigurace JWT Není relevantní Rozhraní Lakebase Data API používá tokeny OAuth Azure Databricks místo ověřování JWT. Možnosti konfigurace specifické pro JWT (vlastní tajné kódy, klíče RS256, ověřování cílové skupiny) nejsou k dispozici.

Vkládání prostředků

Vlastnost Stav Podrobnosti
Vypočítané relace Není podporováno Vlastní relace definované prostřednictvím databázových funkcí, které vracejí SETOF nebo jednotlivé záznamy, nejsou podporovány. Pouze relace cizího klíče mohou být vloženy.
Vkládání vnitřních spojení (!inner tip) Není podporováno Pokyn !inner, který převádí levé spojení na vnitřní spojení pro filtrování řádků rodiče na základě kritérií potomka, není podporován. Příklad: ?select=*,clients!inner(*)&clients.id=eq.1

Formáty odpovědí

Vlastnost Stav Podrobnosti
Vlastní obslužné rutiny typů médií Není podporováno Vlastní výstupní formáty prostřednictvím agregací PostgreSQL (binární formáty, XML, vyrovnávací paměti protokolu) se nepodporují.
Odstraněné nulové hodnoty Není podporováno Parametr nulls=stripped typu média, který odebere pole null z odpovědí JSON, není podporován. Příklad: Accept: application/vnd.pgrst.object+json;nulls=stripped
PostGIS GeoJSON Částečně podporováno Sloupce geometrie PostGIS lze dotazovat, ale automatické formátování GeoJSON prostřednictvím Accept: application/geo+json záhlaví není k dispozici.

Stránkování a počítání

Vlastnost Stav Podrobnosti
Plánovaný počet Není podporováno Možnost Prefer: count=planned , která k odhadu počtu výsledků používá Plánovač dotazů PostgreSQL, se nepodporuje. Místo toho použijte Prefer: count=exact.
Odhadovaný počet Není podporováno Možnost Prefer: count=estimated , která používá statistiky PostgreSQL pro přibližné počty, není podporována. Místo toho použijte Prefer: count=exact.

Předvolby požadavků

Vlastnost Stav Podrobnosti
Předvolba časového pásma Částečně podporováno Zpracování časového pásma existuje, ale hlavička Prefer: timezone=America/Los_Angeles pro přepsání časového pásma serveru není podporována. Nakonfigurujte časové pásmo serveru nebo použijte funkce časového pásma na úrovni databáze.
Řízení transakcí Není podporováno Řízení transakcí prostřednictvím Prefer: tx=commit a Prefer: tx=rollback hlaviček není podporováno.
Režimy zpracování předvoleb Není podporováno Možnosti Prefer: handling=strict a Prefer: handling=lenient pro řízení zpracování neplatných předvoleb nejsou podporovány.

Observability

Rozhraní Lakebase Data API implementuje vlastní funkce pozorovatelnosti. Následující funkce pozorovatelnosti PostgREST se nepodporují:

Vlastnost Stav Podrobnosti
Vystavení plánu dotazů Není podporováno Hlavička Accept: application/vnd.pgrst.plan+json , která zveřejňuje výstup PostgreSQL EXPLAIN pro analýzu výkonu, se nepodporuje.
záhlaví Server-Timing Není podporováno Hlavička Server-Timing, která poskytuje rozpis časování požadavků, není podporovaná. Lakebase implementuje vlastní funkce pozorovatelnosti.
Šíření hlavičky trasování Není podporováno X-Request-Id a šíření vlastní traťové hlavičky pro distribuované trasování se nepodporuje. Lakebase implementuje vlastní funkce pozorovatelnosti.

Rozšířená konfigurace

Vlastnost Stav Podrobnosti
Nastavení aplikace (GUC) Není podporováno Předávání vlastních konfiguračních hodnot databázovým funkcím prostřednictvím guc PostgreSQL se nepodporuje.
Funkce předběžné žádosti Není podporováno Konfigurace db-pre-request, která umožňuje zadat funkci databáze ke spuštění před jednotlivými požadavky, není podporována.

Další informace o funkcích PostgREST najdete v dokumentaci k PostgREST.

Důležité informace o zabezpečení

Rozhraní DATA API vynucuje model zabezpečení vaší databáze na několika úrovních:

  • Ověřování: Všechny požadavky vyžadují platné ověřování tokenu OAuth.
  • Přístup na základě role: Oprávnění na úrovni databáze určují, ke kterým tabulkám a provozním uživatelům mají přístup
  • Zabezpečení na úrovni řádků: Zásady zabezpečení na úrovni řádků vynucují jemně odstupňované řízení přístupu, omezují, které konkrétní řádky můžou uživatelé zobrazit nebo upravit.
  • Kontext uživatele: Rozhraní API předpokládá identitu ověřeného uživatele, zajišťuje správné použití oprávnění a zásad databáze.

Pro produkční nasazení:

  1. Implementace zabezpečení na úrovni řádků: Pomocí zásad zabezpečení na úrovni řádků omezte přístup k datům na úrovni řádků. To je zvlášť důležité pro aplikace s více tenanty a data vlastněná uživatelem. Podívejte se na zabezpečení na úrovni řádků .
  2. Udělit minimální oprávnění: Udělte uživatelům oprávnění pouze potřebná oprávnění (SELECT, INSERT, UPDATE, DELETE) u konkrétních tabulek místo udělení širokého přístupu.
  3. Pro každou aplikaci používejte samostatné role: Místo sdílení jedné role vytvořte vyhrazené role pro různé aplikace nebo služby.
  4. Pravidelně auditovat přístup: Pravidelně kontrolujte udělená oprávnění a zásady zabezpečení na úrovni řádků, abyste měli jistotu, že odpovídají vašim požadavkům na zabezpečení.

Informace o správě rolí a oprávnění najdete v tématu:

  • Last updated on