Delen via

Lakebase Data-API

Belangrijk

Lakebase Autoscaling bevindt zich in de bètaversie van de volgende regio's: eastus2, , westeuropewestus.

Lakebase Autoscaling is de nieuwste versie van Lakebase met automatisch schalen van rekenkracht, schalen naar nul, vertakkingen en direct herstellen. Zie voor functievergelijking met Lakebase Ingerichthet kiezen tussen versies.

De Lakebase Data-API is een met PostgREST compatibele RESTful-interface waarmee u rechtstreeks met uw Lakebase Postgres-database kunt communiceren met behulp van standaard HTTP-methoden. Het biedt API-eindpunten die zijn afgeleid van uw databaseschema, waardoor beveiligde CRUD-bewerkingen (Maken, Lezen, Bijwerken, Verwijderen) op uw gegevens kunnen worden uitgevoerd zonder dat aangepaste back-endontwikkeling nodig is.

Overzicht

De Gegevens-API genereert automatisch RESTful-eindpunten op basis van uw databaseschema. Elke tabel in uw database wordt toegankelijk via HTTP-aanvragen, zodat u het volgende kunt doen:

  • Gegevens opvragen met HTTP-verzoeken GET en flexibel filteren, sorteren en pagineren
  • Records invoegen met HTTP POST-aanvragen
  • Records bijwerken met HTTP PATCH- of PUT-aanvragen
  • Records verwijderen met HTTP DELETE-aanvragen
  • Functies uitvoeren als RPC's met HTTP POST-aanvragen

Deze aanpak elimineert de noodzaak om aangepaste API-code te schrijven en te onderhouden, zodat u zich kunt richten op uw toepassingslogica en databaseschema.

PostgREST-compatibiliteit

De Lakebase Data-API is compatibel met de PostgREST-specificatie . U kunt:

  • Bestaande PostgREST-clientbibliotheken en hulpprogramma's gebruiken
  • Volg postgREST-conventies voor filteren, ordenen en pagineren
  • Documentatie en voorbeelden van de PostgREST-community aanpassen

Opmerking

De Lakebase Data-API is de implementatie van Azure Databricks die is ontworpen om compatibel te zijn met de PostgREST-specificatie. Omdat de Gegevens-API een onafhankelijke implementatie is, zijn sommige PostgREST-functies die niet van toepassing zijn op de Lakebase-omgeving niet opgenomen. Zie Naslaginformatie over functiecompatibiliteit voor meer informatie over functiecompatibiliteit.

Zie de Naslaginformatie over de PostgREST-API voor uitgebreide informatie over API-functies, queryparameters en mogelijkheden.

Gebruiksscenario's

De Lakebase Data-API is ideaal voor:

  • Webtoepassingen: front-ends bouwen die rechtstreeks met uw database communiceren via HTTP-aanvragen
  • Microservices: Lichtgewicht services maken die toegang hebben tot databasebronnen via REST API's
  • Serverloze architecturen: integreren met serverloze functies en edge-computingplatforms
  • Mobiele toepassingen: mobiele apps directe databasetoegang bieden via een RESTful-interface
  • Integraties van derden: externe systemen inschakelen om gegevens veilig te lezen en te schrijven

De Gegevens-API instellen

In deze sectie wordt u begeleid bij het instellen van de gegevens-API, van het maken van vereiste rollen tot het maken van uw eerste API-aanvraag.

Voorwaarden

Voor de Gegevens-API is een Lakebase Postgres-databaseproject voor automatisch schalen vereist. Zie Aan de slag met databaseprojecten als u er nog geen hebt.

Aanbeveling

Als u voorbeeldtabellen nodig hebt om de Gegevens-API te testen, maakt u deze voordat u de Gegevens-API inschakelt. Zie Voorbeeldschema voor een volledig voorbeeldschema.

De gegevens-API inschakelen

De Gegevens-API maakt alle databasetoegang via één Postgres-rol met de naam authenticator, waarvoor geen machtigingen nodig zijn, behalve om u aan te melden. Wanneer u de Gegevens-API inschakelt via de Lakebase-app, worden deze rol en de benodigde infrastructuur automatisch gemaakt.

De gegevens-API inschakelen:

  1. Navigeer naar de pagina Gegevens-API in uw project.
  2. Klik op Gegevens-API inschakelen.

Gegevens-API-knop inschakelen

Hiermee worden automatisch alle installatiestappen uitgevoerd, waaronder het maken van de authenticator rol, het configureren van het pgrst schema en het weergeven van het public schema via de API.

Opmerking

Als u aanvullende schema's (verder public) wilt weergeven, kunt u de weergegeven schema's wijzigen in de instellingen van de Advanced Data-API.

Na het inschakelen van de Gegevens-API

Nadat u de Gegevens-API hebt ingeschakeld, geeft de Lakebase-app de pagina Gegevens-API weer met twee tabbladen: API en Instellingen.

Pagina Gegevens-API met API-URL en beveiligingsopties

Het tabblad API biedt:

  • API-URL: de REST-eindpunt-URL die moet worden gebruikt in uw toepassingscode en API-aanvragen. De weergegeven URL bevat het schema niet, dus u moet de schemanaam (bijvoorbeeld /public) toevoegen aan de URL bij het maken van API-aanvragen.
  • Schemacache vernieuwen: een knop om de schemacache van de API te vernieuwen nadat u wijzigingen in het databaseschema hebt aangebracht. Zie Schemacache vernieuwen.
  • Bescherm uw gegevens: opties voor het inschakelen van beveiliging op rijniveau (RLS) van Postgres voor uw tabellen. Zie Beveiliging op rijniveau inschakelen.

Het tabblad Instellingen biedt opties voor het configureren van API-gedrag, zoals weergegeven schema's, maximumrijen, CORS-instellingen en meer. Zie Geavanceerde gegevens-API-instellingen.

Voorbeeldschema (optioneel)

In de voorbeelden in deze documentatie wordt het volgende schema gebruikt. U kunt uw eigen tabellen maken of dit voorbeeldschema gebruiken om te testen. Voer deze SQL-instructies uit met behulp van de Lakebase SQL Editor of een WILLEKEURIGE SQL-client:

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

Gebruikersmachtigingen configureren

U moet alle Data API-aanvragen verifiëren met behulp van Azure Databricks OAuth Bearer-tokens, die worden verzonden via de Authorization header. De Data-API beperkt de toegang tot geverifieerde Azure Databricks-identiteiten, waarbij Postgres de onderliggende machtigingen beheert.

De authenticator rol gaat uit van de identiteit van de aanvragende gebruiker bij het verwerken van API-aanvragen. Dit werkt alleen als elke Azure Databricks-identiteit die toegang heeft tot de Data-API, een bijbehorende Postgres-rol in uw database heeft. Als u eerst gebruikers wilt toevoegen aan uw Azure Databricks-account, raadpleegt u Gebruikers toevoegen aan uw account.

Postgres-rollen toevoegen

Gebruik de databricks_auth extensie om Postgres-rollen te maken die overeenkomen met Azure Databricks-identiteiten:

Maak de extensie:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

Een Postgres-rol toevoegen:

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

Zie Een OAuth-rol maken voor een Azure Databricks-identiteit met behulp van SQL voor gedetailleerde instructies.

Belangrijk

Gebruik uw database-eigenaaraccount (de Azure Databricks-identiteit die het Lakebase-project heeft gemaakt) niet voor toegang tot de Data-API. De authenticator rol vereist de mogelijkheid om uw rol uit te nemen en die machtiging kan niet worden verleend voor accounts met verhoogde bevoegdheden.

Als u probeert de rol van database-eigenaar toe te kennen aan authenticator, wordt deze fout weergegeven:

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.

Machtigingen verlenen aan gebruikers

Nu u de bijbehorende Postgres-rollen voor uw Azure Databricks-identiteiten hebt gemaakt, moet u machtigingen verlenen aan deze Postgres-rollen. Deze machtigingen bepalen met welke databaseobjecten (schema's, tabellen, reeksen, functies) elke gebruiker kan communiceren via API-aanvragen.

Machtigingen verlenen met behulp van standaard SQL-instructies GRANT . In dit voorbeeld wordt het public-schema gebruikt; als u een ander schema weergeeft, vervang dan public door uw schemanaam.

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

In dit voorbeeld verleent u volledige toegang tot het public schema voor de user@databricks.com identiteit. Vervang dit door de werkelijke Azure Databricks-identiteit en pas machtigingen aan op basis van uw vereisten.

Belangrijk

Beveiliging op rijniveau implementeren: de bovenstaande machtigingen verlenen toegang op tabelniveau, maar voor de meeste API-use cases zijn beperkingen op rijniveau vereist. In toepassingen met meerdere tenants moeten gebruikers bijvoorbeeld alleen hun eigen gegevens of de gegevens van hun organisatie zien. Gebruik beleid voor beveiliging op rijniveau (RLS) van PostgreSQL om gedetailleerd toegangsbeheer af te dwingen op databaseniveau. Zie Beveiliging op rijniveau implementeren.

Authenticatie

Voor toegang tot de Gegevens-API moet u een Azure Databricks OAuth-token opgeven in de Authorization header van uw HTTP-aanvraag. De geverifieerde Azure Databricks-identiteit moet een bijbehorende Postgres-rol hebben (gemaakt in de vorige stappen) die de databasemachtigingen definieert.

Een OAuth-token ophalen

Maak verbinding met uw werkruimte door de identiteit van Azure Databricks te gebruiken waarvoor u in de vorige stappen een Postgres-rol hebt gemaakt en haal een OAuth-token op. Zie Verificatie voor instructies.

Een aanvraag indienen

Met uw OAuth-token en API-URL (beschikbaar via het tabblad API in de Lakebase-app), kunt u API-aanvragen doen met behulp van curl of een HTTP-client. Vergeet niet om de schemanaam (bijvoorbeeld /public) toe te voegen aan de API-URL. In de volgende voorbeelden wordt ervan uitgegaan dat u de DBX_OAUTH_TOKEN en REST_ENDPOINT omgevingsvariabelen hebt geëxporteerd.

Hier volgt een voorbeeldaanroep met de verwachte uitvoer (met behulp van het schema voorbeeldclients/projecten/taken):

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

Voorbeeldantwoord:

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

Zie de sectie API-naslaginformatie voor meer voorbeelden en gedetailleerde informatie over API-bewerkingen. Zie de PostgREST-API-verwijzing voor uitgebreide informatie over queryparameters en API-mogelijkheden. Zie PostgREST-compatibiliteit voor specifieke compatibiliteitsinformatie over Lakebase.

Voordat u de API uitgebreid gebruikt, configureert u beveiliging op rijniveau om uw gegevens te beveiligen.

De gegevens-API beheren

Nadat u de Gegevens-API hebt ingeschakeld, kunt u schemawijzigingen en beveiligingsinstellingen beheren via de Lakebase-app.

Schemacache vernieuwen

Wanneer u wijzigingen aanbrengt in uw databaseschema (tabellen, kolommen of andere schemaobjecten toevoegen), moet u de schemacache vernieuwen. Hierdoor worden uw wijzigingen onmiddellijk beschikbaar via de Gegevens-API.

De schemacache vernieuwen:

  1. Navigeer naar de gegevens-API in de sectie App-back-end van uw project.
  2. Klik op Schemacache vernieuwen.

De Gegevens-API weerspiegelt nu de meest recente schemawijzigingen.

Beveiliging op rijniveau inschakelen

De Lakebase-app biedt een snelle manier om beveiliging op rijniveau (RLS) in te schakelen voor tabellen in uw database. Wanneer er tabellen in uw schema aanwezig zijn, wordt op het tabblad API een sectie Gegevens beveiligen weergegeven waarin het volgende wordt weergegeven:

  • Tabellen met RLS ingeschakeld
  • Tabellen met uitgeschakelde rijniveau-beveiliging (met waarschuwingen)
  • Een RLS inschakeln knop om RLS in te schakelen voor alle tabellen

Belangrijk

Als u beveiliging op rijniveau inschakelt via de Lakebase-app, wordt beveiliging op rijniveau voor uw tabellen ingeschakeld. Wanneer RLS is ingeschakeld, worden alle rijen standaard niet toegankelijk voor gebruikers (met uitzondering van tabeleigenaren, rollen met het kenmerk BYPASSRLS en superusers, hoewel supergebruikers niet worden ondersteund op Lakebase). U moet RLS-beleid maken om toegang te verlenen tot specifieke rijen op basis van uw beveiligingsvereisten. Zie Beveiliging op rijniveau voor informatie over het maken van beleid.

RLS inschakelen voor uw tabellen:

  1. Navigeer naar de gegevens-API in de sectie App-back-end van uw project.
  2. Controleer in de sectie Uw gegevens beveiligen de tabellen waarvoor RLS niet is ingeschakeld.
  3. Klik op RLS inschakelen om beveiliging op rijniveau voor alle tabellen in te schakelen.

U kunt RLS ook inschakelen voor afzonderlijke tabellen met behulp van SQL. Zie Beveiliging op rijniveau voor meer informatie.

Geavanceerde gegevens-API-instellingen

De sectie Geavanceerde instellingen op het tabblad API in de Lakebase-app bepaalt de beveiliging, prestaties en het gedrag van uw Data API-eindpunt.

Weergegeven schema's

Verstek:public

Hiermee definieert u welke PostgreSQL-schema's worden weergegeven als REST API-eindpunten. Standaard is alleen het public schema toegankelijk. Als u andere schema's gebruikt (bijvoorbeeld api, v1), selecteert u deze in de vervolgkeuzelijst om ze toe te voegen.

Opmerking

Machtigingen zijn van toepassing: Als u hier een schema toevoegt, worden de eindpunten weergegeven, maar de databaserol die door de API wordt gebruikt, moet nog steeds bevoegdheden hebben USAGE voor het schema en SELECT de bevoegdheden voor de tabellen.

Maximaal aantal rijen

Standaard: Leeg

Hiermee wordt een vaste limiet afgedwongen voor het aantal rijen dat moet worden geretourneerd in één API-antwoord. Dit voorkomt dat de prestaties per ongeluk afnemen van grote query's. Clients moeten pagineringslimieten gebruiken om gegevens binnen deze drempelwaarde op te halen. Dit voorkomt ook onverwachte uitgaande kosten van grote gegevensoverdrachten.

Toegestane CORS-oorsprongen

Standaard: Leeg (staat alle oorsprongen toe)

Hiermee bepaalt u welke webdomeinen gegevens uit uw API kunnen ophalen met behulp van een browser.

  • Leeg: Hiermee staat u * (elk domein) toe. Nuttig voor ontwikkeling.
  • Productie: Vermeld uw specifieke domeinen (bijvoorbeeld https://myapp.com) om te voorkomen dat onbevoegde websites query's uitvoeren op uw API.

OpenAPI-specificatie

Standaard: Uitgeschakeld

Hiermee bepaalt u of een automatisch gegenereerd OpenAPI 3-schema beschikbaar is op /openapi.json. In dit schema worden uw tabellen, kolommen en REST-eindpunten beschreven. Wanneer deze optie is ingeschakeld, kunt u het volgende gebruiken:

  • API-documentatie genereren (Swagger UI, Redoc)
  • Getypte clientbibliotheken bouwen (TypeScript, Python, Go)
  • Uw API importeren in Postman
  • Integreren met API-gateways en andere op OpenAPI gebaseerde hulpprogramma's

Server timing headers

Standaard: Uitgeschakeld

Wanneer ingeschakeld, bevat de Data-API Server-Timing headers in elk antwoord. Deze headers laten zien hoe lang verschillende onderdelen van de aanvraag hebben geduurd om te verwerken (bijvoorbeeld de uitvoeringstijd van de database en de interne verwerkingstijd). U kunt deze informatie gebruiken om trage query's op te sporen, prestaties te meten en latentieproblemen in uw toepassing op te lossen.

Opmerking

Nadat u de geavanceerde instellingen hebt gewijzigd, klikt u op Opslaan om deze toe te passen.

Beveiliging op rijniveau

Beleidsregels voor beveiliging op rijniveau (RLS) bieden gedetailleerd toegangsbeheer door te beperken waartoe gebruikers toegang hebben in een tabel.

Hoe RLS werkt met de gegevens-API: wanneer een gebruiker een API-aanvraag doet, wordt de identiteit van die gebruiker aangenomen door de authenticator rol. Elk RLS-beleid dat is gedefinieerd voor de rol van die gebruiker, wordt automatisch afgedwongen door PostgreSQL, waarbij de gegevens worden gefilterd waartoe ze toegang hebben. Dit gebeurt op databaseniveau, dus zelfs als toepassingscode alle rijen probeert op te vragen, retourneert de database alleen rijen die de gebruiker mag zien. Dit biedt diepgaande beveiliging zonder filterlogica in uw toepassingscode.

Waarom RLS essentieel is voor API's: in tegenstelling tot directe databaseverbindingen waarin u de verbindingscontext beheert, maken HTTP-API's uw database beschikbaar voor meerdere gebruikers via één eindpunt. Machtigingen op tabelniveau betekenen alleen dat als een gebruiker toegang heeft tot de clients tabel, toegang heeft tot alle clientrecords, tenzij u filters implementeert. RLS-beleid zorgt ervoor dat elke gebruiker automatisch alleen de geautoriseerde gegevens ziet.

RLS is essentieel voor:

  • Toepassingen met meerdere tenants: gegevens isoleren tussen verschillende klanten of organisaties
  • Gegevens die eigendom zijn van de gebruiker: ervoor zorgen dat gebruikers alleen toegang hebben tot hun eigen records
  • Toegang op basis van een team: zichtbaarheid beperken tot teamleden of specifieke groepen
  • Nalevingsvereisten: Beperkingen voor gegevenstoegang afdwingen op databaseniveau

Beveiliging op rijniveau inschakelen

U kunt RLS inschakelen via de Lakebase-app of met behulp van SQL-instructies. Zie Beveiliging op rijniveau inschakelen voor instructies over het gebruik van de Lakebase-app.

Waarschuwing

Als u tabellen hebt zonder dat RLS ingeschakeld is, wordt op het API-tabblad in de Lakebase-app een waarschuwing weergegeven dat geverifieerde gebruikers alle rijen van die tabellen kunnen bekijken. De Gegevens-API communiceert rechtstreeks met uw Postgres-schema en omdat de API toegankelijk is via internet, is het van cruciaal belang om beveiliging af te dwingen op databaseniveau met postgreSQL-beveiliging op rijniveau.

Voer de volgende opdracht uit om rij-niveau beveiliging in te schakelen met behulp van SQL:

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

RLS-beleid maken

Nadat u RLS hebt ingeschakeld voor een tabel, moet u beleidsregels maken die de toegangsregels definiëren. Zonder beleid hebben gebruikers geen toegang tot rijen (alle rijen zijn standaard verborgen).

Hoe beleidsregels werken: wanneer RLS is ingeschakeld voor een tabel, kunnen gebruikers alleen rijen zien die overeenkomen met ten minste één beleid. Alle andere rijen worden weggefilterd. Tabeleigenaren, rollen met het kenmerk BYPASSRLS, en supergebruikers kunnen het beveiligingssysteem voor rijen omzeilen (hoewel supergebruikers niet worden ondersteund op Lakebase).

Opmerking

Retourneert in Lakebase current_user het e-mailadres van de geverifieerde gebruiker (bijvoorbeeld user@databricks.com). Gebruik dit in uw RLS-beleid om te bepalen welke gebruiker de aanvraag indient.

Syntaxis van basisbeleid:

CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);
  • policy_name: een beschrijvende naam voor het beleid
  • table_name: De tabel voor het toepassen van het beleid op
  • TO role_name: Optioneel. Hiermee specificeert u de rol voor dit beleid. Laat deze component weg om het beleid toe te passen op alle rollen.
  • USING (voorwaarde): de voorwaarde die bepaalt welke rijen zichtbaar zijn

RLS-handleiding voor beveiliging op rijniveau

In de volgende zelfstudie wordt het voorbeeldschema uit deze documentatie (clients, projecten, takentabellen) gebruikt om te laten zien hoe u beveiliging op rijniveau implementeert.

Scenario: U hebt meerdere gebruikers die alleen hun toegewezen clients en gerelateerde projecten moeten zien. Beperk de toegang zodat:

  • alice@databricks.com kan alleen clients met id's 1 en 2 weergeven
  • bob@databricks.com kan alleen clients met id's 2 en 3 weergeven

Stap 1: RLS inschakelen in de tabel clients

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Stap 2: Een beleid maken voor Alice

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

Stap 3: Een beleid maken voor Bob

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

Stap 4: Het beleid testen

Wanneer Alice een API-aanvraag doet:

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

Antwoord (Alice ziet alleen clients 1 en 2):

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

Wanneer Bob een API-aanvraag doet:

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

Antwoord (Bob ziet alleen clients 2 en 3):

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

Algemene RLS-patronen

Deze patronen hebben betrekking op typische beveiligingsvereisten voor de Gegevens-API:

Eigendom van de gebruiker: hiermee beperkt u rijen tot de geverifieerde gebruiker:

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

Tenantisolatie : beperkt rijen tot de organisatie van de gebruiker:

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

Teamlidmaatschap : beperkt rijen tot de teams van de gebruiker:

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

Op rollen gebaseerde toegang - Beperkt rijen op basis van rollidmaatschap:

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

Alleen-lezen voor specifieke rollen : verschillende beleidsregels voor verschillende bewerkingen:

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

Aanvullende bronnen

Zie de PostgreSQL-rijbeveiligingsbeleid documentatie voor uitgebreide informatie over het implementeren van RLS, waaronder beleidstypen, aanbevolen beveiligingsprocedures en geavanceerde patronen.

Zie Machtigingen beheren voor meer informatie over machtigingen.

API-verwijzing

In deze sectie wordt ervan uitgegaan dat u de installatiestappen, geconfigureerde machtigingen hebt voltooid en beveiliging op rijniveau hebt geïmplementeerd. De volgende secties bevatten naslaginformatie over het gebruik van de Gegevens-API, waaronder algemene bewerkingen, geavanceerde functies, beveiligingsoverwegingen en compatibiliteitsgegevens.

Basisbewerkingen

Queryrecords

Records ophalen uit een tabel met HTTP GET:

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

Voorbeeldantwoord:

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

Resultaten filteren

Gebruik queryparameters om resultaten te filteren. In dit voorbeeld worden klanten opgehaald met id meer dan of gelijk aan 2:

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

Voorbeeldantwoord:

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

Specifieke kolommen en samenvoegtabellen selecteren

Gebruik de select parameter om specifieke kolommen op te halen en gerelateerde tabellen samen te voegen:

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

Voorbeeldantwoord:

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

Records invoegen

Nieuwe records maken met 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"

Records bijwerken

Bestaande records bijwerken met 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"

Records verwijderen

Records verwijderen met HTTP DELETE:

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

Geavanceerde functies

Pagina-indeling

Bepaal het aantal records dat wordt geretourneerd met behulp van de limit en offset parameters:

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

Sorteervolgorde

Resultaten sorteren met behulp van de order parameter:

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

Complexe filtering

Meerdere filtervoorwaarden combineren:

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

Algemene filteroperators:

  • eq - is gelijk aan
  • gte - groter dan of gelijk aan
  • lte - kleiner dan of gelijk aan
  • neq - niet gelijk aan
  • like -Patroonherkenning
  • in - komt overeen met een willekeurige waarde in de lijst

Zie de PostgREST-API-verwijzing voor meer informatie over ondersteunde queryparameters en API-functies. Zie PostgREST-compatibiliteit voor specifieke compatibiliteitsinformatie over Lakebase.

Referentie voor functiecompatibiliteit

In deze sectie worden PostgREST-functies vermeld die verschillend gedrag hebben of die niet worden ondersteund in de Lakebase Data-API.

Authenticatie en autorisatie

Feature Toestand Bijzonderheden
JWT-configuratie Niet van toepassing De Lakebase Data-API maakt gebruik van Azure Databricks OAuth-tokens in plaats van JWT-verificatie. JWT-specifieke configuratieopties (aangepaste geheimen, RS256-sleutels, doelgroepvalidatie) zijn niet beschikbaar.

Insluiten van middelen

Feature Toestand Bijzonderheden
Berekende relaties Niet ondersteund Aangepaste relaties die via databasefuncties zijn gedefinieerd en één record of SETOF retourneren, worden niet ondersteund. Alleen relaties met foreign keys kunnen worden ingesloten.
Inner join embedding (!inner hint) Niet ondersteund De !inner hint waarmee left joins worden omgezet in inner joins om ouderrijen te filteren op basis van kindcriteria, wordt niet ondersteund. Voorbeeld: ?select=*,clients!inner(*)&clients.id=eq.1

Antwoordindelingen

Feature Toestand Bijzonderheden
Handlers voor aangepast mediatype Niet ondersteund Aangepaste uitvoerindelingen via PostgreSQL-aggregaties (binaire indelingen, XML, protocolbuffers) worden niet ondersteund.
Verwijderde nullen Niet ondersteund De nulls=stripped parameter mediatype waarmee null-velden uit JSON-antwoorden worden verwijderd, wordt niet ondersteund. Voorbeeld: Accept: application/vnd.pgrst.object+json;nulls=stripped
PostGIS GeoJSON Gedeeltelijk ondersteund PostGIS geometriekolommen kunnen worden opgevraagd, maar automatische GeoJSON-opmaak via Accept: application/geo+json koptekst is niet beschikbaar.

Paginering en nummering

Feature Toestand Bijzonderheden
Gepland aantal Niet ondersteund De Prefer: count=planned optie die gebruikmaakt van de queryplanner van PostgreSQL om het aantal resultaten te schatten, wordt niet ondersteund. Gebruik in plaats daarvan Prefer: count=exact.
Geschat aantal Niet ondersteund De Prefer: count=estimated optie die gebruikmaakt van PostgreSQL-statistieken voor geschatte aantallen wordt niet ondersteund. Gebruik in plaats daarvan Prefer: count=exact.

Voorkeuren aanvragen

Feature Toestand Bijzonderheden
Tijdzonevoorkeur Gedeeltelijk ondersteund De afhandeling van tijdzones bestaat, maar de header voor het Prefer: timezone=America/Los_Angeles overschrijven van servertijdzone wordt niet ondersteund. Configureer de tijdzone van de server of gebruik tijdzonefuncties op databaseniveau.
Transactiebeheer Niet ondersteund Transactiebeheer via Prefer: tx=commit en Prefer: tx=rollback headers wordt niet ondersteund.
Modi voor afhandeling van voorkeuren Niet ondersteund De Prefer: handling=strict opties en Prefer: handling=lenient opties voor het beheren van hoe ongeldige voorkeuren worden verwerkt, worden niet ondersteund.

Observability

De Lakebase Data-API implementeert zijn eigen waarneembaarheidsfuncties. De volgende postgREST-waarneembaarheidsfuncties worden niet ondersteund:

Feature Toestand Bijzonderheden
Blootstelling van queryplan Niet ondersteund De Accept: application/vnd.pgrst.plan+json header waarmee PostgreSQL-uitvoer EXPLAIN voor prestatieanalyse wordt weergegeven, wordt niet ondersteund.
Server-Timing koptekst Niet ondersteund De Server-Timing header die een uitsplitsing van de tijdsinstelling voor aanvragen biedt, wordt niet ondersteund. Lakebase implementeert zijn eigen waarneembaarheidsfuncties.
Headerpropagatie van traceringen Niet ondersteund X-Request-Id en propagatie van aangepaste traceerheaders voor gedistribueerde tracering worden niet ondersteund. Lakebase implementeert zijn eigen waarneembaarheidsfuncties.

Geavanceerde configuratie

Feature Toestand Bijzonderheden
Toepassingsinstellingen (GUC's) Niet ondersteund Het doorgeven van aangepaste configuratiewaarden aan databasefuncties via PostgreSQL GUCs wordt niet ondersteund.
Functie vooraf aanvragen Niet ondersteund De db-pre-request-configuratie waarmee je kunt aangeven dat een databasefunctie vóór elke aanvraag moet worden uitgevoerd, wordt niet ondersteund.

Zie de PostgREST-documentatie voor meer informatie over PostgREST-functies.

Beveiligingsoverwegingen

De gegevens-API dwingt het beveiligingsmodel van uw database af op meerdere niveaus:

  • Verificatie: voor alle aanvragen is geldige OAuth-tokenverificatie vereist
  • Op rollen gebaseerde toegang: Machtigingen op databaseniveau bepalen welke tabellen en bewerkingen gebruikers toegang hebben
  • Beveiliging op rijniveau: RLS-beleid dwingt fijnmazig toegangsbeheer af, waardoor wordt beperkt welke specifieke rijen gebruikers kunnen zien of wijzigen
  • Gebruikerscontext: Bij de API wordt ervan uitgegaan dat de identiteit van de geverifieerde gebruiker wordt gebruikt, zodat databasemachtigingen en -beleidsregels correct worden toegepast

Voor productie-implementaties:

  1. Beveiliging op rijniveau implementeren: gebruik RLS-beleid om de toegang tot gegevens op rijniveau te beperken. Dit is vooral belangrijk voor toepassingen met meerdere tenants en gegevens die eigendom zijn van gebruikers. Zie beveiliging op regelniveau.
  2. Minimale machtigingen verlenen: alleen de machtigingen verlenen die gebruikers nodig hebben (SELECT, INSERT, UPDATE, DELETE) voor specifieke tabellen in plaats van brede toegang te verlenen.
  3. Gebruik afzonderlijke rollen per toepassing: Maak toegewezen rollen voor verschillende toepassingen of services in plaats van één rol te delen.
  4. Regelmatig toegang controleren: Controleer de verleende machtigingen en RLS-beleidsregels regelmatig om ervoor te zorgen dat deze voldoen aan uw beveiligingsvereisten.

Zie voor meer informatie over het beheren van rollen en machtigingen:

  • Last updated on