Aller au contenu principal
Dernière mise à jour le

API de données Lakebase

L'API de données Lakebase est une interface RESTful compatible PostgREST qui vous permet d'interagir directement avec votre base de données Lakebase Postgres en utilisant des méthodes HTTP standard. Il offre des endpoints API dérivés de votre schéma de base de données, permettant des opérations CRUD (création, lecture, mise à jour, suppression) sécurisées sur vos données sans nécessiter de développement de backend personnalisé.

Présentation​

L’API de données génère automatiquement des endpoints RESTful basés sur votre schéma de base de données. Chaque table de votre base de données devient accessible via des requêtes HTTP, vous permettant de :

  • Query data à l'aide de requêtes HTTP GET avec un filtrage, un tri et une pagination flexibles
  • Insérer des enregistrements à l'aide de requêtes HTTP POST
  • Mettre à jour les enregistrements à l'aide de requêtes HTTP PATCH ou PUT
  • Supprimer les enregistrements à l'aide de requêtes HTTP DELETE
  • Exécuter des fonctions comme RPC à l'aide de requêtes HTTP POST

Cette approche élimine la nécessité d'écrire et de maintenir du code API personnalisé, ce qui vous permet de vous concentrer sur votre logique d'application et votre schéma de base de données.

Compatibilité PostgREST​

L'API de données Lakebase est compatible avec la PostgREST spécification. Vous pouvez :

  • Utilisez les bibliothèques et outils clients PostgREST existants.
  • Suivez les conventions PostgREST pour le filtrage, le tri et la pagination
  • Adapter la documentation et les exemples de la communauté PostgREST
remarque

L'API de données Lakebase est l'implémentation de Databricks conçue pour être compatible avec la spécification PostgREST. Étant donné que l'API de données est une implémentation indépendante, certaines fonctionnalités PostgREST qui ne sont pas applicables à l'environnement Lakebase ne sont pas incluses. Pour plus de détails sur la compatibilité des fonctionnalités, consultez Référence sur la compatibilité des fonctionnalités.

Pour des informations complètes sur les fonctionnalités de l'API, les paramètres de requête et les capacités, consultez la référence de l'API PostgREST.

Cas d'usage​

Le Data API Lakebase est idéal pour :

  • Applications web : Créez des interfaces qui interagissent directement avec votre base de données via des requêtes HTTP.
  • Microservices : Créez des services légers qui accèdent aux Ressources de la base de données via les APIs REST
  • Architectures Serverless : Intégrez-vous à des fonctions Serverless et à des plateformes de edge computing
  • Applications mobiles : fournissez aux applications mobiles un accès direct à la base de données via une interface RESTful
  • Intégrations tierces : permettent aux systèmes externes de lire et d'écrire des données en toute sécurité.

Configurer l'API Data​

Cette section vous guide à travers la configuration de l'API de données, de la création des rôles requis à la réalisation de votre première requête API.

Prérequis​

L'API de données requiert un projet de base de données Lakebase Postgres Autoscaling. Si vous n’en avez pas, consultez start avec les projets de base de données.

astuce

Si vous avez besoin d'exemples de tables pour tester l'API de données, créez-les avant d'activer l'API de données. Voir un exemple de schéma pour un schéma complet.

Activer l'API Data​

L'API de données permet tout accès à la base de données via un seul rôle Postgres nommé authenticator, ce qui ne nécessite aucune permission, sauf pour la connexion. Lorsque vous activez l'API de données via l'application Lakebase, ce rôle et l'infrastructure nécessaire sont créés automatiquement.

Pour activer l'API de données :

  1. Accédez à la page Data API de votre projet.
  2. Cliquez sur **Activer l'API de données**.

Bouton Activer l'API de données

Ceci effectue automatiquement toutes les étapes de configuration, y compris la création du rôle authenticator, la configuration du schéma pgrst et l'exposition du schéma public via l'API.

remarque

Si vous devez exposer des schémas supplémentaires (au-delà de public), vous pouvez modifier les schémas exposés dans les paramètres de l'API de données avancée.

Après avoir activé l'API de données​

Après avoir activé l'API de données, l'application Lakebase affiche la page API de données avec deux onglets : API et Paramètres .

Page Data API affichant l'URL de l'API et les options de sécurité

L'onglet API fournit :

  • **URL de l'API** : L'URL de l'endpoint REST à utiliser dans le code de votre application et les requêtes d'API. L'URL affichée n'inclut pas le schéma, vous devez donc ajouter le nom du schéma (par exemple, /public) à l'URL lors de l'envoi de requêtes API.
  • refresh schema cache : Un bouton pour actualiser le cache du schéma de l'API après avoir apporté des modifications au schéma de votre base de données. Voir refresh le cache du schéma.
  • Protégez vos données : options pour activer la sécurité au niveau des lignes (RLS) Postgres pour vos tables. Voir Activer la sécurité au niveau des lignes.

L'onglet Paramètres offre des options pour configurer le comportement de l'API, telles que les schémas exposés, le nombre maximal de lignes, les paramètres CORS, etc. Voir les paramètres avancés de l'API de données.

Exemple de schéma (facultatif)​

Les exemples de cette documentation utilisent le schéma suivant. Vous pouvez créer vos propres tables ou utiliser ce schéma d'exemple pour les tests. Exécutez ces instructions SQL à l'aide de l'éditeur SQL Lakebase ou de tout client SQL :

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

Configurer les autorisations utilisateur​

Vous devez authentifier toutes les requêtes d'API de données en utilisant les jetons de porteur OAuth de Databricks, qui sont envoyés via l'en-tête Authorization. La Data API restreint l'accès aux identités Databricks authentifiées, Postgres régissant les autorisations sous-jacentes.

Le rôle authenticator assume l'identité de l'utilisateur demandeur lors du traitement des requêtes API. Pour que cela fonctionne, chaque identité Databricks qui accède à l'API de données doit avoir un rôle Postgres correspondant dans votre base de données. Si vous devez d'abord ajouter des utilisateurs à votre compte Databricks, consultez Ajouter des utilisateurs à votre compte.

Ajouter des rôles Postgres​

important

N'utilisez pas votre compte de propriétaire de base de données (l'identité Databricks qui a créé le projet Lakebase) pour accéder à l'API de données. Le rôle authenticator requiert la capacité d'assumer votre rôle, et cette permission ne peut pas être accordée aux comptes ayant des privilèges élevés. Utilisez plutôt un service principal (recommandé) ou un autre compte utilisateur Databricks.

Créez le rôle en suivant les étapes SQL ci-dessous. Un rôle ajouté via l'interface utilisateur Roles & Databases > Ajouter un rôle ne peut pas être octroyé à authenticator, la prochaine étape échoue donc avec une erreur d'autorisation refusée. Voir Dépannage.

À l'aide de l'Éditeur SQL de Lakebase, créez un rôle Postgres pour chaque identité Databricks ayant besoin d'accéder à l'API de données :

  1. Créez l'extension databricks_auth. Chaque base de données Postgres doit avoir sa propre extension.

    SQL
    CREATE EXTENSION IF NOT EXISTS databricks_auth;

  2. Utilisez databricks_create_role pour ajouter un rôle Postgres pour l'identité Databricks :

    Pour un utilisateur :

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

    Pour un Service Principal , utilisez l'ID d'application (UUID) comme nom d'identité. Retrouvez-le dans votre Workspace Databricks sous Paramètres > Identité et accès > Service principals :

    SQL
    SELECT databricks_create_role('8c01cfb1-62c9-4a09-88a8-e195f4b01b08', 'SERVICE_PRINCIPAL');

Accorder des autorisations aux utilisateurs​

Maintenant que vous avez créé les rôles Postgres correspondants pour vos identités Databricks, vous devez accorder des autorisations à ces rôles Postgres. Ces autorisations contrôlent les objets de base de données (schémas, tables, séquences, fonctions) avec lesquels chaque utilisateur peut interagir via des requêtes API.

Accorder des autorisations à l'aide d'instructions SQL standard GRANT. Cet exemple utilise le schéma public ; si vous exposez un schéma différent, remplacez public par le nom de votre schéma :

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

Cet exemple accorde un accès complet au schéma public pour l'identité user@databricks.com. Remplacez ceci par l'identité Databricks réelle et ajustez les autorisations en fonction de vos besoins. Pour les Service Principals, utilisez l'ID d'application (UUID) comme nom de rôle Postgres dans les déclarations GRANT au lieu d'une adresse e-mail.

important

Implémenter la sécurité au niveau des lignes : Les autorisations ci-dessus accordent un accès au niveau de la table, mais la plupart des cas d'utilisation de l'API nécessitent des restrictions au niveau des lignes. Par exemple, dans les applications multi-tenant, les utilisateurs ne devraient voir que leurs propres données ou les données de leur organisation. Utilisez les stratégies de sécurité au niveau des lignes (RLS) de PostgreSQL pour appliquer un contrôle d'accès précis au niveau de la base de données. Consultez Implémenter la sécurité au niveau des lignes.

Authentification​

Pour accéder à l’API Data, vous devez fournir un jeton OAuth Databricks dans l'en-tête Authorization de votre requête HTTP. L'identité Databricks authentifiée doit disposer d'un rôle Postgres correspondant (créé lors des étapes précédentes) qui définit ses autorisations de base de données.

Obtenir un jeton OAuth​

Connectez-vous à votre Workspace en tant qu'identité Databricks pour laquelle vous avez créé un rôle Postgres au cours des étapes précédentes et obtenez un jeton OAuth. Consultez l'authentification pour obtenir des instructions.

Faire une demande​

Avec votre jeton OAuth et l'URL de l'API (disponibles dans le tab API de l'application Lakebase), vous pouvez effectuer des requêtes API à l'aide de curl ou de tout client HTTP. N'oubliez pas d'ajouter le nom du schéma (par exemple, /public) à l'URL de l'API. Les exemples suivants supposent que vous avez exporté les variables d'environnement DBX_OAUTH_TOKEN et REST_ENDPOINT.

Voici un exemple d'appel avec la sortie attendue (en utilisant le schéma clients/projets/tâches échantillon) :

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

Exemple de réponse :

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

Pour plus d'exemples et d'informations détaillées sur les opérations de l'API, consultez la section référence de l'API. Pour des détails complets sur les paramètres de requête et les capacités de l'API, consultez la documentation de référence de l'API PostgREST. Pour plus d'informations sur la compatibilité spécifique à Lakebase, consultez compatibilité PostgREST.

Avant d'utiliser l'API de manière approfondie, configurez la sécurité au niveau des lignes pour protéger vos données.

Gérer l’API de données​

Après avoir activé l'API de données, vous pouvez gérer les modifications de schéma et les paramètres de sécurité via l'application Lakebase.

refresh le cache de schéma​

Lorsque vous apportez des modifications à votre schéma de base de données (ajout de tables, de colonnes ou d'autres objets de schéma), vous devez refresh le cache de schéma. Cela rend vos modifications immédiatement disponibles via l'API de données.

Pour refresh le cache du schéma :

  1. Accédez à l’ API de données dans la section Back-end de l’application de votre projet.
  2. Cliquez sur **refresh schema cache**.

L’API de données reflète désormais vos dernières modifications de schéma.

Activer la sécurité au niveau des lignes​

L'application Lakebase offre un moyen rapide d'activer la sécurité au niveau des lignes (RLS) pour les tables de votre base de données. Lorsque des tables existent dans votre schéma, l'onglet API affiche une section Protégez vos données qui indique :

  • Tables avec RLS activé
  • Tables avec RLS désactivé (avec avertissements)
  • Un bouton **Activer RLS** pour activer RLS pour toutes les tables
important

L'activation de la sécurité au niveau des lignes (RLS) via l'application Lakebase active la sécurité au niveau des lignes pour vos tables. Lorsque la RLS est activée, toutes les lignes deviennent inaccessibles aux utilisateurs par default (sauf pour les propriétaires de table, les rôles avec l'attribut BYPASSRLS et les super-utilisateurs — bien que les super-utilisateurs ne soient pas pris en charge sur Lakebase). Vous devez créer des stratégies RLS pour octroyer l'accès à des lignes spécifiques en fonction de vos exigences de sécurité. Consultez Sécurité au niveau des lignes pour plus d'informations sur la création de politiques.

Pour activer le RLS pour vos tables :

  1. Accédez à l’ API de données dans la section Back-end de l’application de votre projet.
  2. Dans la section Proteger vos données , examinez les tables qui n'ont pas le RLS activé.
  3. Cliquez sur Activer la RLS pour activer la sécurité au niveau des lignes pour toutes les tables.

Vous pouvez également activer le RLS pour les tables individuelles en utilisant SQL. Consultez la sécurité au niveau des lignes pour plus de détails.

Dépannage​

autorisation refusée d'accorder un rôle (SQLSTATE 42501)​

ERROR: permission denied to grant role "<identity>" (SQLSTATE 42501)

Cela se produit lorsque vous exécutez GRANT "<identity>" TO authenticator et que :

  • **Le rôle a été ajouté via l'interface utilisateur Rôles & Bases de données.** Créez le rôle avec databricks_create_role dans l'éditeur SQL à la place. Voir Ajouter des rôles Postgres.
  • La cible est votre compte propriétaire de la base de données. Utilisez un Service Principal ou un autre utilisateur Databricks non propriétaire.

L'API de données n'est pas activée pour cet endpoint.​

Si vous ajoutez des réplicas en lecture avant d’activer l’API de données, les Endpoint peuvent renvoyer brièvement cette erreur. Activez d’abord l’API de données, puis ajoutez des réplicas en lecture.

Paramètres avancés de l'API de données​

La section Paramètres avancés de la tab API de l'application Lakebase contrôle la sécurité, les performances et le comportement de votre endpoint Data API.

Schémas exposés​

default: public

Définit les schémas PostgreSQL exposés en tant qu'Endpoint de l'API REST. Par default, seul le schéma public est accessible. Si vous utilisez d'autres schémas (par exemple, api, v1), sélectionnez-les dans la liste déroulante pour les ajouter.

remarque

Les autorisations s'appliquent : l'ajout d'un schéma ici expose les Endpoint, mais le rôle de base de données utilisé par l'API doit toujours avoir les privilèges USAGE sur le schéma et les privilèges SELECT sur les tables.

Nombre maximal de lignes​

Default : Vide

Applique une limite stricte sur le nombre de lignes à renvoyer dans une seule réponse API. Cela empêche la dégradation accidentelle des performances due aux requêtes volumineuses. Les clients devraient utiliser les limites de pagination pour récupérer les données dans ce threshold. Cela empêche également les coûts de sortie inattendus liés aux transferts de données volumineux.

Origines CORS autorisées​

Default: Vide (Autorise toutes les origines)

Contrôle les domaines web qui peuvent récupérer des données de votre API à l'aide d'un navigateur.

  • Vide : autorise * (n'importe quel domaine). Utile pour le développement.
  • Production : Listez vos domaines spécifiques (par exemple, https://myapp.com) afin d'empêcher les sites web non autorisés d'interroger votre API.

Spécification OpenAPI​

Default : Désactivé

Contrôle si un schéma OpenAPI 3 auto-généré est disponible à l’adresse /openapi.json. Ce schéma décrit vos tables, colonnes et points de terminaison REST. Lorsqu'il est activé, vous pouvez l'utiliser pour :

  • Générer la documentation de l'API (Swagger UI, Redoc)
  • Créez des bibliothèques clientes typées (TypeScript, Python, Go).
  • Importez votre API dans Postman.
  • Intégrer avec des passerelles API et d'autres outils basés sur OpenAPI.

En-têtes de synchronisation du serveur​

Default : Désactivé

Lorsqu'elle est activée, l'API de données inclut Server-Timing en-têtes dans chaque réponse. Ces en-têtes indiquent le temps que différentes parties de la requête ont mis pour être traitées (par exemple, le temps d'exécution de la base de données et le temps de traitement interne). Vous pouvez utiliser ces informations pour déboguer les query lentes, mesurer les performances et dépanner les problèmes de latence dans votre application.

remarque

Après avoir apporté des modifications à des paramètres avancés, cliquez sur Enregistrer pour les appliquer.

Sécurité au niveau des lignes​

Les stratégies de sécurité au niveau des lignes (RLS) offrent un contrôle d'accès précis en limitant les lignes auxquelles les utilisateurs peuvent accéder dans une table.

Fonctionnement de RLS avec l'API de données : Lorsqu'un utilisateur effectue une requête API, le rôle authenticator assume l'identité de cet utilisateur. Toutes les politiques RLS définies pour le rôle de cet utilisateur sont automatiquement appliquées par PostgreSQL, filtrant les données auxquelles ils peuvent accéder. Cela se produit au niveau de la base de données, donc même si le code de l’application tente d’interroger toutes les lignes, la base de données ne renvoie que les lignes que l’utilisateur est autorisé à voir. Cela fournit une sécurité en profondeur sans nécessiter de logique de filtrage dans le code de votre application.

Pourquoi le RLS est essentiel pour les APIs : contrairement aux connexions directes aux bases de données où vous contrôlez le contexte de connexion, les APIs HTTP exposent votre base de données à plusieurs utilisateurs via un seul Endpoint. Les autorisations au niveau de la table signifient à elles seules que si un utilisateur peut accéder à la clients table, il peut accéder à **tous** les enregistrements clients, à moins que vous n’implémentiez un filtrage. Les politiques RLS garantissent que chaque utilisateur voit automatiquement uniquement les données auxquelles il est autorisé.

RLS est essentiel pour :

  • Applications multi-tenant : isolez les données entre différents clients ou organisations
  • Données détenues par l'utilisateur : assurez-vous que les utilisateurs n'accèdent qu'à leurs propres enregistrements.
  • Accès basé sur l’équipe : Limitez la visibilité aux membres de l’équipe ou à des groupes spécifiques.
  • **Exigences de conformité** : Appliquer les restrictions d'accès aux données au niveau de la base de données

RLS et vues : les politiques RLS sont appliquées au niveau de la table. Vous ne pouvez pas définir de politique RLS directement sur une vue. By default, lorsqu'un utilisateur interroge une vue, Postgres évalue les politiques RLS par rapport au propriétaire de la vue , et non à l'utilisateur qui interroge. Cela signifie que si le propriétaire de la vue est le propriétaire de la table ou un superutilisateur, la RLS sur la table sous-jacente est effectivement contournée pour quiconque peut SELECT sur la vue.

Pour appliquer les politiques RLS contre l'utilisateur qui exécute réellement la query, créez la vue avec security_invoker = true:

SQL
CREATE VIEW my_view WITH (security_invoker = true) AS
SELECT * FROM clients;

Ou mettez à jour une vue existante :

SQL
ALTER VIEW my_view SET (security_invoker = true);

Autre solution, utilisez FORCE ROW LEVEL SECURITY sur la table sous-jacente afin que la RLS s'applique également au propriétaire de la table :

SQL
ALTER TABLE clients FORCE ROW LEVEL SECURITY;

Pour restreindre l'accès à la vue elle-même (contrôlant qui peut la query), utilisez les autorisations de rôle Postgres (GRANT/REVOKE) plutôt que les politiques RLS.

Activer RLS.​

Vous pouvez activer le RLS via l'application Lakebase ou à l'aide d'instructions SQL. Pour obtenir des instructions sur l'utilisation de l'application Lakebase, consultez Activer la sécurité au niveau des lignes.

attention

Si vous avez des tables sans RLS activé, l'onglet API dans l'application Lakebase affiche un avertissement indiquant que les utilisateurs authentifiés peuvent consulter toutes les lignes de ces tables. L'API de données interagit directement avec votre schéma Postgres, et parce que l'API est accessible via Internet, il est crucial d'appliquer la sécurité au niveau de la base de données en utilisant la sécurité au niveau des lignes de PostgreSQL.

Pour activer RLS à l'aide de SQL, exécutez la commande suivante :

SQL
ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Créer des politiques RLS​

Après avoir activé RLS sur une table, vous devez créer des politiques qui définissent des règles d'accès. Sans stratégies, les utilisateurs ne peuvent accéder à aucune ligne (toutes les lignes sont masquées par default).

Fonctionnement des politiques : Lorsque RLS est activé sur une table, les utilisateurs ne peuvent voir que les lignes qui correspondent au moins à une politique. Toutes les autres lignes sont filtrées. Les propriétaires de tables, les rôles avec l'attribut BYPASSRLS et les super-utilisateurs peuvent contourner le système de sécurité des lignes (bien que les super-utilisateurs ne soient pas pris en charge sur Lakebase).

remarque

Dans Lakebase, current_user retourne l'adresse e-mail de l'utilisateur authentifié (par exemple, user@databricks.com). Utilisez ceci dans vos stratégies RLS pour identifier quel utilisateur effectue la requête.

Syntaxe de base :

SQL
CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);
  • **policy_name** : Un nom descriptif pour la politique
  • table_name : Table à laquelle appliquer la politique
  • À role_name : facultatif. Spécifie le rôle pour cette politique. Omettez cette clause pour appliquer la politique à tous les rôles.
  • USING (condition) : La condition qui détermine quelles lignes sont visibles

Didacticiel RLS​

Le tutoriel suivant utilise le schéma d'exemple de cette documentation (tables clients, projets, tâches) pour montrer comment implémenter la sécurité au niveau des lignes.

**Scénario** : vous avez plusieurs utilisateurs qui ne devraient voir que leurs clients assignés et les projets connexes. Restreindre l'accès afin que :

  • alice@databricks.com peut uniquement afficher les clients avec les ID 1 et 2
  • bob@databricks.com peut uniquement afficher les clients avec les ID 2 et 3

Étape 1 : Activez RLS sur la table des clients

SQL
ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Étape 2 : Créer une politique pour Alice

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

Étape 3 : Créez une politique pour Bob

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

Étape 4 : Tester les stratégies

Lorsque Alice effectue une requête API :

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

Réponse (Alice ne voit que les clients 1 et 2) :

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

Lorsque Bob effectue une requête API :

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

Réponse (Bob ne voit que les clients 2 et 3) :

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

Modèles RLS courants​

Ces modèles répondent aux exigences de sécurité typiques pour l'API de données :

Propriété de l'utilisateur - Restreint les lignes à l'utilisateur authentifié :

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

Isolement du tenant : restreint les lignes à l'organisation de l'utilisateur :

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

Appartenance à une équipe – Restreint les lignes aux équipes de l’utilisateur :

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

Accès basé sur les rôles - Restreint les lignes en fonction de l'appartenance au rôle :

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

Lecture seule pour des rôles spécifiques – Différentes politiques pour différentes opérations :

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

Ressources supplémentaires​

Pour des informations complètes sur l'implémentation de RLS, y compris les types de stratégies, les bonnes pratiques de sécurité et les modèles avancés, consultez la documentation sur les stratégies de sécurité des lignes PostgreSQL.

Pour plus d’informations sur les autorisations, consultez Gérer les autorisations.

Référence de l'API​

Cette section suppose que vous avez terminé les étapes de configuration, configuré les autorisations et implémenté la sécurité au niveau des lignes. Les sections suivantes fournissent des informations de référence pour l'utilisation de l'API de données, y compris les Opérations courantes, les fonctionnalités avancées, les considérations de sécurité et les détails de compatibilité.

Opérations de base​

Interroger les enregistrements​

Récupérer les enregistrements d'une table à l'aide de HTTP GET :

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

Exemple de réponse :

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

Filtrer les résultats​

Utilisez les paramètres de query pour filtrer les résultats. Cet exemple récupère les clients avec id supérieur ou égal à 2 :

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

Exemple de réponse :

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

Sélectionnez des colonnes spécifiques et joignez des tables​

Utilisez le paramètre select pour récupérer des colonnes spécifiques et joindre les tables associées :

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

Exemple de réponse :

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

Insérer des enregistrements​

Créez de nouveaux enregistrements à l'aide de HTTP POST :

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

Mettre à jour les enregistrements​

Mettez à jour les enregistrements existants à l'aide de HTTP PATCH :

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

Supprimer les enregistrements​

Supprimer les enregistrements à l'aide de HTTP DELETE :

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

Fonctionnalités avancées​

Pagination​

Contrôler le nombre d'enregistrements renvoyés à l'aide des paramètres limit et offset :

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

Tri​

Triez les résultats à l'aide du paramètre order :

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

Filtrage complexe​

Combinez plusieurs conditions de filtre :

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

Opérateurs de filtre courants :

  • eq – égal à
  • gte - supérieur ou égal à
  • lte inférieur ou égal à
  • neq - non égal
  • like - Correspondance des modèles
  • in - correspond à toute valeur de la liste

Pour plus d'information sur les paramètres de query et les fonctionnalités de l'API pris en charge, consultez la référence de l'API PostgREST. Pour les informations de compatibilité spécifiques à Lakebase, consultez la compatibilité PostgREST.

Référence de compatibilité des fonctionnalités​

L'API de données Lakebase est entièrement compatible avec la spécification PostgREST, y compris l'intégration des ressources (clé étrangère et relations calculées, indices de jointure interne/gauche), les formats de réponse (JSON, CSV, GeoJSON, types de médias personnalisés), le filtrage, la pagination, les modes de comptage (exact, planned, estimated), les préférences de requête (handling, timezone, tx), l'exposition du plan de requête et les fonctionnalités RPC.

Les fonctionnalités PostgREST suivantes ne sont pas applicables ou disponibles dans l'environnement Lakebase :

Authentification​

Fonctionnalité

Statut

Détails

Configuration JWT

Non applicable

L'API Lakebase Data utilise des jetons OAuth Databricks au lieu de l'authentification JWT. Options de configuration spécifiques à JWT (secrets personnalisés, clés RS256, validation de l'audience) ne sont pas disponibles.

Fonctionnalité

Statut

Détails

Configuration JWT

Non applicable

L'API Lakebase Data utilise des jetons OAuth Databricks au lieu de l'authentification JWT. Options de configuration spécifiques à JWT (secrets personnalisés, clés RS256, validation de l'audience) ne sont pas disponibles.

Configuration avancée​

Fonctionnalité

Statut

Détails

Paramètres d'application (GUCs)

Non pris en charge

Le passage de valeurs de configuration personnalisées aux fonctions de base de données via les GUC PostgreSQL n'est pas pris en charge.

Fonction de pré-requête

Non pris en charge

La configuration db-pre-request qui permet de spécifier une fonction de base de données à exécuter avant chaque requête n'est pas prise en charge.

Fonctionnalité

Statut

Détails

Paramètres d'application (GUCs)

Non pris en charge

Le passage de valeurs de configuration personnalisées aux fonctions de base de données via les GUC PostgreSQL n'est pas pris en charge.

Fonction de pré-requête

Non pris en charge

La configuration db-pre-request qui permet de spécifier une fonction de base de données à exécuter avant chaque requête n'est pas prise en charge.

Observabilité​

Fonctionnalité

Statut

Détails

Propagation de l'en-tête de trace

Non applicable

Lakebase implémente ses propres fonctionnalités d'observabilité au lieu de la propagation des en-têtes X-Request-Id et de trace personnalisée de PostgREST.

Fonctionnalité

Statut

Détails

Propagation de l'en-tête de trace

Non applicable

Lakebase implémente ses propres fonctionnalités d'observabilité au lieu de la propagation des en-têtes X-Request-Id et de trace personnalisée de PostgREST.

Pour plus d'informations sur les fonctionnalités de PostgREST, consultez la documentation de PostgREST.

Considérations de sécurité​

Le Data API applique le modèle de sécurité de votre base de données à plusieurs niveaux :

  • Authentification : toutes les requêtes nécessitent une authentification par jeton OAuth valide
  • Accès basé sur les rôles : les autorisations au niveau de la base de données contrôlent les tables et les Opérations auxquelles les utilisateurs peuvent accéder.
  • Sécurité au niveau des lignes : les stratégies RLS appliquent un contrôle d'accès granulaire, limitant les lignes spécifiques que les utilisateurs peuvent voir ou modifier.
  • Contexte utilisateur : l'API assume l'identité de l'utilisateur authentifié, garantissant que les autorisations et les politiques de la base de données s'appliquent correctement.

Bonnes pratiques de sécurité recommandées​

Pour les déploiements en production :

  1. Implémenter la sécurité au niveau des lignes : Utilisez les politiques RLS pour restreindre l'accès aux données au niveau des lignes. Ceci est particulièrement important pour les applications multi-tenant et les données appartenant aux utilisateurs. Consultez Sécurité au niveau des lignes.
  2. Accorder des autorisations minimales : N'accordez que les autorisations dont les utilisateurs ont besoin (SELECT, INSERT, UPDATE, DELETE) sur des tables spécifiques plutôt qu'un accès général.
  3. **Utilisez des rôles distincts par application** : Créez des rôles dédiés pour différentes applications ou services plutôt que de partager un seul rôle.
  4. Auditez régulièrement l'accès : Examinez périodiquement les autorisations accordées et les politiques RLS afin de vous assurer qu'elles correspondent à vos exigences de sécurité.

Pour en savoir plus sur la gestion des rôles et des autorisations, consultez :

Sur cette page