Dela via

Lakebase Data API

Viktigt!

Lakebase Autoscaling finns i Beta i följande regioner: eastus2, westeurope, westus.

Lakebase Autoscaling är den senaste versionen av Lakebase med automatisk skalningsberäkning, skalning till noll, förgrening och omedelbar återställning. För funktionsjämförelse med Lakebase Provisioned, se välja mellan versioner.

Lakebase Data API är ett PostgREST-kompatibelt RESTful-gränssnitt som gör att du kan interagera direkt med din Lakebase Postgres-databas med hjälp av vanliga HTTP-metoder. Det erbjuder API-slutpunkter som härletts från ditt databasschema, vilket möjliggör säkra CRUD-åtgärder (Skapa, Läsa, Uppdatera, Ta bort) på dina data utan att behöva utveckla anpassade serverdelar.

Översikt

Data-API:et genererar automatiskt RESTful-slutpunkter baserat på ditt databasschema. Varje tabell i databasen blir tillgänglig via HTTP-begäranden så att du kan:

  • Fråga efter data med hjälp av HTTP-begäranden GET med flexibel filtrering, sortering och sidnumrering
  • Infoga poster med HTTP POST-begäranden
  • Uppdatera poster med HTTP PATCH- eller PUT-begäranden
  • Ta bort poster med HTTP DELETE-begäranden
  • Köra funktioner som RPC:er med HTTP POST-begäranden

Den här metoden eliminerar behovet av att skriva och underhålla anpassad API-kod så att du kan fokusera på programlogik och databasschema.

PostgREST-kompatibilitet

Lakebase Data API är kompatibelt med PostgREST-specifikationen . Du kan:

  • Använda befintliga PostgREST-klientbibliotek och -verktyg
  • Följ PostgREST-konventioner för filtrering, ordning och sidnumrering
  • Anpassa dokumentation och exempel från PostgREST-communityn

Anmärkning

Lakebase Data API är Azure Databricks implementering utformad för att vara kompatibel med PostgREST-specifikationen. Eftersom data-API:et är en oberoende implementering ingår inte vissa PostgREST-funktioner som inte gäller för Lakebase-miljön. Mer information om funktionskompatibilitet finns i Referens för funktionskompatibilitet.

Omfattande information om API-funktioner, frågeparametrar och funktioner finns i referensen för PostgREST API.

Användningsfall

Lakebase Data API är perfekt för:

  • Webbprogram: Skapa klientdelar som interagerar direkt med databasen via HTTP-begäranden
  • Mikrotjänster: Skapa enkla tjänster som har åtkomst till databasresurser via REST-API:er
  • Serverlösa arkitekturer: Integrera med serverlösa funktioner och plattformar för gränsberäkning
  • Mobilappar: Ge mobilappar direkt databasåtkomst via ett RESTful-gränssnitt
  • Integrering från tredje part: Aktivera externa system för att läsa och skriva data på ett säkert sätt

Konfigurera data-API:et

Det här avsnittet vägleder dig genom att konfigurera data-API:et, från att skapa nödvändiga roller till att göra din första API-begäran.

Förutsättningar

Data-API:et kräver ett Lakebase Postgres Autoscaling-databasprojekt. Om du inte har något kan du läsa Komma igång med databasprojekt.

Tips/Råd

Om du behöver exempeltabeller för att testa data-API:et skapar du dem innan du aktiverar data-API:et. Se Exempelschema för ett komplett exempelschema.

Aktivera data-API:et

Data-API:et ger all databasåtkomst via en enda Postgres-roll med namnet authenticator, vilket inte kräver några behörigheter förutom att logga in. När du aktiverar data-API:et via Lakebase-appen skapas den här rollen och nödvändig infrastruktur automatiskt.

Så här aktiverar du data-API:et:

  1. Gå till sidan Data-API i projektet.
  2. Klicka på Aktivera data-API.

Aktivera data-API-knapp

Detta utför automatiskt alla installationssteg, inklusive att skapa authenticator rollen, konfigurera pgrst schemat och exponera public schemat via API:et.

Anmärkning

Om du behöver exponera ytterligare scheman (utöver public) kan du ändra de tillgängliga schemana i API-inställningarna för avancerade data.

När du har aktiverat data-API:et

När du har aktiverat data-API:et visar Lakebase-appen sidan Data-API med två flikar: API och Inställningar.

Sidan Data-API som visar API-URL och säkerhetsalternativ

Fliken API innehåller:

  • API-URL: REST-slutpunkts-URL:en som ska användas i programkoden och API-begäranden. Url:en som visas innehåller inte schemat, så du måste lägga till schemanamnet (till exempel /public) i URL:en när du gör API-begäranden.
  • Uppdatera schemacache: En knapp för att uppdatera API:ets schemacache när du har ändrat databasschemat. Se Uppdatera schemacache.
  • Skydda dina data: Alternativ för att aktivera Postgres säkerhet på radnivå (RLS) för dina tabeller. Se Aktivera säkerhet på radnivå.

Fliken Inställningar innehåller alternativ för att konfigurera API-beteende, till exempel exponerade scheman, maximalt antal rader, CORS-inställningar med mera. Se Inställningar för Api för avancerade data.

Exempelschema (valfritt)

Exemplen i den här dokumentationen använder följande schema. Du kan skapa egna tabeller eller använda det här exempelschemat för testning. Kör dessa SQL-instruktioner med Lakebase SQL-redigeraren eller någon SQL-klient:

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

Konfigurera användarbehörigheter

Du måste autentisera alla Data API-begäranden med hjälp av Azure Databricks OAuth-ägartoken som skickas via Authorization-huvudet. Data-API:et begränsar åtkomsten till autentiserade Azure Databricks-identiteter, med Postgres som styr de underliggande behörigheterna.

Rollen authenticator förutsätter identiteten för den begärande användaren vid bearbetning av API-begäranden. För att detta ska fungera måste varje Azure Databricks-identitet som har åtkomst till data-API:et ha en motsvarande Postgres-roll i databasen. Om du behöver lägga till användare i ditt Azure Databricks-konto först kan du läsa Lägga till användare i ditt konto.

Lägga till Postgres-roller

databricks_auth Använd tillägget för att skapa Postgres-roller som motsvarar Azure Databricks-identiteter:

Skapa tillägget:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

Lägg till en Postgres-roll:

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

Detaljerade anvisningar finns i Skapa en OAuth-roll för en Azure Databricks-identitet med sql.

Viktigt!

Använd inte ditt databasägarkonto (Azure Databricks-identiteten som skapade Lakebase-projektet) för att få åtkomst till data-API:et. Rollen authenticator kräver möjligheten att anta din roll och den behörigheten kan inte beviljas för konton med förhöjd behörighet.

Om du försöker bevilja databasens ägarroll får authenticatordu följande fel:

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.

Bevilja behörigheter till användare

Nu när du har skapat motsvarande Postgres-roller för dina Azure Databricks-identiteter måste du bevilja behörigheter till postgres-rollerna. Dessa behörigheter styr vilka databasobjekt (scheman, tabeller, sekvenser, funktioner) som varje användare kan interagera med via API-begäranden.

Bevilja behörigheter med sql-standardinstruktioner GRANT . I det här public exemplet används schemat; om du exponerar ett annat schema, ersätter du public med ditt schemanamn.

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

Det här exemplet ger fullständig åtkomst till public schemat för identiteten user@databricks.com . Ersätt detta med den faktiska Azure Databricks-identiteten och justera behörigheterna baserat på dina krav.

Viktigt!

Implementera säkerhet på radnivå: Behörigheterna ovan beviljar åtkomst på tabellnivå, men de flesta API-användningsfall kräver begränsningar på radnivå. I program med flera klientorganisationer bör användarna till exempel bara se sina egna data eller organisationens data. Använd PostgreSQL-principer för säkerhet på radnivå (RLS) för att framtvinga detaljerad åtkomstkontroll på databasnivå. Se Implementera säkerhet på radnivå.

Autentisering

För att få åtkomst till data-API:et måste du ange en Azure Databricks OAuth-token i Authorization rubriken för din HTTP-begäran. Den autentiserade Azure Databricks-identiteten måste ha en motsvarande Postgres-roll (skapad i föregående steg) som definierar dess databasbehörigheter.

Hämta en OAuth-token

Anslut till din arbetsyta som den Azure Databricks-identitet för vilken du skapade en Postgres-roll i föregående steg och erhåll en OAuth-token. Anvisningar finns i Autentisering .

Göra en begäran

Med din OAuth-token och API-URL (tillgänglig från FLIKEN API i Lakebase-appen) kan du göra API-begäranden med curl eller någon HTTP-klient. Kom ihåg att lägga till schemanamnet (till exempel /public) i API-URL:en. I följande exempel förutsätts att du har exporterat DBX_OAUTH_TOKEN miljövariablerna och REST_ENDPOINT .

Här är ett exempelanrop med förväntade utdata (med hjälp av exempelklienter/projekt/uppgiftsschema):

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

Exempelsvar:

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

Fler exempel och detaljerad information om API-åtgärder finns i AVSNITTET API-referens . Omfattande information om frågeparametrar och API-funktioner finns i referensen för PostgREST API. Information om Lakebase-specifik kompatibilitet finns i PostgREST-kompatibilitet.

Innan du använder API:et i stor utsträckning konfigurerar du säkerhet på radnivå för att skydda dina data.

Hantera data-API:et

När du har aktiverat data-API:et kan du hantera schemaändringar och säkerhetsinställningar via Lakebase-appen.

Uppdatera schemacache

När du gör ändringar i databasschemat (lägger till tabeller, kolumner eller andra schemaobjekt) måste du uppdatera schemacachen. Detta gör dina ändringar omedelbart tillgängliga via data-API:et.

Så här uppdaterar du schemacachen:

  1. Gå till Data-API i avsnittet App-serverdel i projektet.
  2. Klicka på Uppdatera schemacache.

Data-API:et återspeglar nu dina senaste schemaändringar.

Aktivera säkerhet på radnivå

Lakebase-appen är ett snabbt sätt att aktivera säkerhet på radnivå (RLS) för tabeller i databasen. När tabeller finns i schemat visar fliken API avsnittet Skydda dina data som visar:

  • Tabeller med RLS aktiverat
  • Tabeller med RLS inaktiverat (med varningar)
  • Knappen Aktivera RLS för att aktivera RLS för alla tabeller

Viktigt!

Om du aktiverar RLS via Lakebase-appen aktiveras säkerhet på radnivå för dina tabeller. När RLS är aktiverat blir alla rader otillgängliga för användare som standard (förutom tabellägare, roller med attributet BYPASSRLS och superanvändare , även om superanvändare inte stöds på Lakebase). Du måste skapa RLS-principer för att bevilja åtkomst till specifika rader baserat på dina säkerhetskrav. Mer information om hur du skapar principer finns i Säkerhet på radnivå .

Så här aktiverar du RLS för dina tabeller:

  1. Gå till Data-API i avsnittet App-serverdel i projektet.
  2. I avsnittet Skydda dina data granskar du tabellerna som inte har RLS aktiverat.
  3. Klicka på Aktivera RLS för att aktivera säkerhet på radnivå för alla tabeller.

Du kan också aktivera RLS för enskilda tabeller med hjälp av SQL. Mer information finns i Säkerhet på radnivå .

Api-inställningar för avancerade data

Avsnittet Avancerade inställningar på fliken API i Lakebase-appen styr säkerheten, prestandan och beteendet för data-API-slutpunkten.

Exponerade scheman

Standard:public

Definierar vilka PostgreSQL-scheman som exponeras som REST API-slutpunkter. Som standard är endast public schemat tillgängligt. Om du använder andra scheman (till exempel api, v1) väljer du dem i listrutan för att lägga till dem.

Anmärkning

Behörigheter gäller: När du lägger till ett schema här exponeras slutpunkterna, men databasrollen som används av API:et måste fortfarande ha USAGE behörighet för schemat och SELECT behörigheterna i tabellerna.

Maximalt antal rader

Standard: Tom

Tillämpar en hård gräns för hur många rader som ska returneras i ett enda API-svar. Detta förhindrar oavsiktlig prestandaförsämring från stora frågor. Klienter bör använda sidnumreringsgränser för att hämta data inom det här tröskelvärdet. Detta förhindrar också oväntade utgående kostnader från stora dataöverföringar.

CORS-tillåtet ursprung

Standard: Tom (tillåter alla ursprung)

Styr vilka webbdomäner som kan hämta data från ditt API med hjälp av en webbläsare.

  • Tom: Tillåter * (valfri domän). Användbart för utveckling.
  • Produktion: Visa en lista över dina specifika domäner (till exempel https://myapp.com) för att förhindra att obehöriga webbplatser frågar ditt API.

OpenAPI-specifikation

Standard: Inaktiverad

Styr om ett automatiskt genererat OpenAPI 3-schema är tillgängligt på /openapi.json. Det här schemat beskriver dina tabeller, kolumner och REST-slutpunkter. När du är aktiverad kan du använda den för att:

  • Generera API-dokumentation (Swagger UI, Redoc)
  • Skapa inskrivna klientbibliotek (TypeScript, Python, Go)
  • Importera ditt API till Postman
  • Integrera med API-gatewayer och andra OpenAPI-baserade verktyg

Sidhuvuden för servertidsinställningar

Standard: Inaktiverad

När Data-API:et är aktiverat, innehåller det rubriker i varje svar. Dessa rubriker visar hur lång tid det tog att bearbeta olika delar av begäran (till exempel körningstid för databas och intern bearbetningstid). Du kan använda den här informationen för att felsöka långsamma frågor, mäta prestanda och felsöka problem med svarstid i ditt program.

Anmärkning

När du har gjort ändringar i avancerade inställningar klickar du på Spara för att tillämpa dem.

Säkerhet på radnivå

Principer för säkerhet på radnivå (RLS) ger detaljerad åtkomstkontroll genom att begränsa vilka rader som användare kan komma åt i en tabell.

Så här fungerar RLS med data-API:et: När en användare gör en API-begäran authenticator förutsätter rollen att användarens identitet. Alla RLS-principer som definierats för användarens roll framtvingas automatiskt av PostgreSQL, vilket filtrerar de data som de kan komma åt. Detta sker på databasnivå, så även om programkoden försöker köra frågor mot alla rader returnerar databasen endast rader som användaren har behörighet att se. Detta ger djupskyddssäkerhet utan att du behöver filtreringslogik i programkoden.

Varför RLS är viktigt för API:er: Till skillnad från direkta databasanslutningar där du styr anslutningskontexten exponerar HTTP-API:er databasen för flera användare via en enda slutpunkt. Enbart behörigheter på tabellnivå innebär att om en användare kan komma åt clients tabellen kan de komma åt alla klientposter om du inte implementerar filtrering. RLS-principer säkerställer att varje användare automatiskt endast ser sina auktoriserade data.

RLS är viktigt för:

  • Program för flera klientorganisationer: Isolera data mellan olika kunder eller organisationer
  • Användarägda data: Se till att användarna endast får åtkomst till sina egna register
  • Teambaserad åtkomst: Begränsa synligheten för gruppmedlemmar eller specifika grupper
  • Efterlevnadskrav: Framtvinga dataåtkomstbegränsningar på databasnivå

Aktivera RLS

Du kan aktivera RLS via Lakebase-appen eller med hjälp av SQL-instruktioner. Anvisningar om hur du använder Lakebase-appen finns i Aktivera säkerhet på radnivå.

Varning

Om du har tabeller utan RLS aktiverat visar FLIKEN API i Lakebase-appen en varning om att autentiserade användare kan visa alla rader i dessa tabeller. Data-API:et interagerar direkt med ditt Postgres-schema och eftersom API:et är tillgängligt via Internet är det viktigt att tillämpa säkerhet på databasnivå med postgreSQL-säkerhet på radnivå.

Om du vill aktivera RLS med SQL kör du följande kommando:

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Skapa RLS-policyer

När du har aktiverat RLS i en tabell måste du skapa principer som definierar åtkomstregler. Utan principer kan användarna inte komma åt några rader (alla rader är dolda som standard).

Så här fungerar principer: När RLS är aktiverat i en tabell kan användarna bara se rader som matchar minst en princip. Alla andra rader filtreras bort. Tabellägare, roller med BYPASSRLS attributet och superanvändare kan kringgå radsäkerhetssystemet (även om superanvändare inte stöds på Lakebase).

Anmärkning

I Lakebase current_user returnerar den autentiserade användarens e-postadress (till exempel user@databricks.com). Använd detta i dina RLS-principer för att identifiera vilken användare som gör begäran.

Grundläggande principsyntax:

CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);
  • policy_name: Ett beskrivande namn för principen
  • table_name: Tabellen som principen ska tillämpas på
  • ATT role_name: Valfritt. Anger rollen för den här policyn. Utelämna den här satsen för att tillämpa principen på alla roller.
  • USING (condition): Villkoret som avgör vilka rader som visas

Handledning RLS

I följande självstudie används exempelschemat från den här dokumentationen (klienter, projekt, uppgiftstabeller) för att visa hur du implementerar säkerhet på radnivå.

Scenario: Du har flera användare som bara ska se sina tilldelade klienter och relaterade projekt. Begränsa åtkomsten så att:

  • alice@databricks.com kan bara visa klienter med ID 1 och 2
  • bob@databricks.com kan bara visa klienter med ID 2 och 3

Steg 1: Aktivera RLS i tabellen klienter

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Steg 2: Skapa en princip för Alice

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

Steg 3: Skapa en princip för Bob

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

Steg 4: Testa principerna

När Alice gör en API-begäran:

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

Svar (Alice ser bara klienterna 1 och 2):

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

När Bob gör en API-begäran:

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

Svar (Bob ser bara klienterna 2 och 3):

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

Vanliga RLS-mönster

Dessa mönster omfattar vanliga säkerhetskrav för data-API:et:

Användarägarskap – Begränsar rader till den autentiserade användaren:

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

Hyresgästisolering – Begränsar rader till organisationen användaren tillhör:

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

Teammedlemskap – Begränsar rader till användarens team:

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

Rollbaserad åtkomst – Begränsar rader baserat på rollmedlemskap:

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

Skrivskyddad för specifika roller – Olika policyer för olika operationer:

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

Ytterligare resurser

Omfattande information om hur du implementerar RLS, inklusive principtyper, metodtips för säkerhet och avancerade mönster finns i dokumentationen om PostgreSQL-radsäkerhetsprinciper.

Mer information om behörigheter finns i Hantera behörigheter.

API-referens

Det här avsnittet förutsätter att du har slutfört installationsstegen, konfigurerat behörigheter och implementerat säkerhet på radnivå. Följande avsnitt innehåller referensinformation för användning av data-API:et, inklusive vanliga åtgärder, avancerade funktioner, säkerhetsöverväganden och kompatibilitetsinformation.

Grundläggande åtgärder

Sök i poster

Hämta poster från en tabell via HTTP GET:

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

Exempelsvar:

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

Filtrera resultat

Använd frågeparametrar för att filtrera resultat. Det här exemplet hämtar klienter med id större än eller lika med 2:

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

Exempelsvar:

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

Välj specifika kolumner och koppla tabeller

Använd parametern select för att hämta specifika kolumner och koppla relaterade tabeller:

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

Exempelsvar:

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

Infoga poster

Skapa nya poster med 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"

Uppdateringsposter

Uppdatera befintliga poster med 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"

Ta bort poster

Ta bort poster med HTTP DELETE:

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

Avancerade funktioner

Paginering

Kontrollera antalet poster som returneras med parametrarna limit och offset :

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

Sortering

Sortera resultat med hjälp av parametern order :

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

Komplex filtrering

Kombinera flera filtervillkor:

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

Vanliga filteroperatorer:

  • eq -Motsvarar
  • gte - större än eller lika med
  • lte - mindre än eller lika med
  • neq - inte lika med
  • like - mönstermatchning
  • in – matchar valfritt värde i listan

Mer information om frågeparametrar och API-funktioner som stöds finns i referensen för PostgREST API. Information om Lakebase-specifik kompatibilitet finns i PostgREST-kompatibilitet.

Referens för funktionskompatibilitet

I det här avsnittet visas PostgREST-funktioner som har olika beteende eller som inte stöds i Lakebase Data API.

Autentisering och auktorisering

Egenskap Läge Detaljer
JWT-konfiguration Ej tillämpligt Lakebase Data API använder Azure Databricks OAuth-token i stället för JWT-autentisering. JWT-specifika konfigurationsalternativ (anpassade hemligheter, RS256-nycklar, målgruppsvalidering) är inte tillgängliga.

Inbäddning av resurser

Egenskap Läge Detaljer
Beräknade relationer Stöds inte Anpassade relationer som definieras via databasfunktioner som returnerar SETOF eller enskilda poster stöds inte. Endast främmande nyckelrelationer kan bäddas in.
Inbäddning av inre koppling (!inner ledtråd) Stöds inte Tipset !inner som konverterar vänsterkopplingar till inre kopplingar för filtrering av överordnade rader baserat på underordnade villkor stöds inte. Exempel: ?select=*,clients!inner(*)&clients.id=eq.1

Svarsformat

Egenskap Läge Detaljer
Hanterare av anpassad medietyp Stöds inte Anpassade utdataformat via PostgreSQL-aggregeringar (binära format, XML, protokollbuffertar) stöds inte.
Avskalade null-värden Stöds inte Den nulls=stripped medietypsparameter som tar bort null-fält från JSON-svar stöds inte. Exempel: Accept: application/vnd.pgrst.object+json;nulls=stripped
PostGIS GeoJSON Delvis stöd PostGIS-geometrikolumner kan efterfrågas, men automatisk GeoJSON-formatering via Accept: application/geo+json sidhuvud är inte tillgänglig.

Sidnumrering och räkning

Egenskap Läge Detaljer
Planerat antal Stöds inte Det Prefer: count=planned alternativ som använder PostgreSQL:s frågeplanering för att uppskatta resultatantal stöds inte. Använd Prefer: count=exact i stället.
Uppskattat antal Stöds inte Alternativet Prefer: count=estimated som använder PostgreSQL-statistik för ungefärligt antal stöds inte. Använd Prefer: count=exact i stället.

Inställningar för begäran

Egenskap Läge Detaljer
Tidszonsinställningar Delvis stöd Tidszonshantering finns, men Prefer: timezone=America/Los_Angeles rubriken för att åsidosätta serverns tidszon stöds inte. Konfigurera serverns tidszon eller använd tidszonsfunktioner på databasnivå.
Transaktionskontroll Stöds inte Transaktionskontroll via Prefer: tx=commit och Prefer: tx=rollback rubriker stöds inte.
Inställningshanteringslägen Stöds inte Alternativen Prefer: handling=strict och Prefer: handling=lenient för att styra hur ogiltiga inställningar hanteras stöds inte.

Observability

Lakebase Data API implementerar sina egna observerbarhetsfunktioner. Följande postgREST-observerbarhetsfunktioner stöds inte:

Egenskap Läge Detaljer
Exponering av frågeplan Stöds inte Huvudet Accept: application/vnd.pgrst.plan+json som exponerar PostgreSQL-utdata EXPLAIN för prestandaanalys stöds inte.
Server-Timing rubrik Stöds inte Server-Timing-rubriken, som tillhandahåller uppdelning av tid för begäran, stöds inte. Lakebase implementerar sina egna observerbarhetsfunktioner.
Spridning av spårhuvud Stöds inte X-Request-Id och anpassad spårningshuvudspridning för distribuerad spårning stöds inte. Lakebase implementerar sina egna observerbarhetsfunktioner.

Avancerad konfiguration

Egenskap Läge Detaljer
Programinställningar (GUCs) Stöds inte Det går inte att skicka anpassade konfigurationsvärden till databasfunktioner via PostgreSQL GUCs.
Funktion före förfrågan Stöds inte Den db-pre-request konfiguration som gör det möjligt att ange en databasfunktion som ska köras innan varje begäran stöds inte.

Mer information om PostgREST-funktioner finns i PostgREST-dokumentationen.

Säkerhetshänsyn

Data-API:et tillämpar databasens säkerhetsmodell på flera nivåer:

  • Autentisering: Alla begäranden kräver giltig OAuth-tokenautentisering
  • Rollbaserad åtkomst: Behörigheter på databasnivå styr vilka tabeller och åtgärder som användare kan komma åt
  • Säkerhet på radnivå: RLS-principer tillämpar detaljerad åtkomstkontroll, vilket begränsar vilka specifika rader som användare kan se eller ändra
  • Användarkontext: API:et förutsätter den autentiserade användarens identitet, vilket säkerställer att databasbehörigheter och principer tillämpas korrekt

För produktionsdistributioner:

  1. Implementera säkerhet på radnivå: Använd RLS-principer för att begränsa dataåtkomsten på radnivå. Detta är särskilt viktigt för program med flera klientorganisationer och användarägda data. Se Säkerhet på radnivå.
  2. Bevilja minimal behörighet: Bevilja endast de behörigheter som användarna behöver (SELECT, , INSERTUPDATE, DELETE) för specifika tabeller i stället för att ge bred åtkomst.
  3. Använd separata roller per program: Skapa dedikerade roller för olika program eller tjänster i stället för att dela en enda roll.
  4. Granska åtkomst regelbundet: Granska beviljade behörigheter och RLS-principer regelbundet för att säkerställa att de matchar dina säkerhetskrav.

Information om hur du hanterar roller och behörigheter finns i:

  • Last updated on