Skip to main content
View as Markdown

Opérations en lot

Les points de terminaison en lot écrivent de nombreux enregistrements en une seule requête, afin que vous puissiez importer, synchroniser ou modifier des données en masse efficacement — et de façon atomique. Chaque lot s'exécute dans une seule transaction : si un enregistrement échoue à la validation, l'ensemble du lot est annulé et aucune ligne n'est écrite. Passez returnRecords: true pour recevoir les enregistrements affectés dans la réponse (sinon, seul un résumé est renvoyé).

Méthode et chemin Opération Max par lot
POST /api/tables/:tableId/records/batch Créer 1000
PATCH /api/tables/:tableId/records/batch Mettre à jour 100
DELETE /api/tables/:tableId/records/batch Suppression réversible 100
POST /api/tables/:tableId/records/batch/restore Restaurer 100
POST /api/tables/:tableId/records/upsert Upsert 100

Tous les corps en lot requièrent la forme enveloppée canonique ({ "fields": { ... } }) — le raccourci de corps plat accepté par la création d'un enregistrement unique n'est pas disponible dans les requêtes en lot. Chaque lot doit contenir au moins un enregistrement.

Création en lot

Envoyez un tableau records, chaque élément étant une enveloppe. Jusqu'à 1000 enregistrements par appel.

POST /api/tables/contacts/records/batch
{
  "records": [
    { "fields": { "email": "alice@example.com", "name": "Alice" } },
    { "fields": { "email": "bob@example.com", "name": "Bob" } }
  ],
  "returnRecords": true
}
Statut Signification
201 Created Tous les enregistrements créés
400 Bad Request Tableau vide, au-delà de la limite de 1000, ou un enregistrement échoue à la validation (tout le lot est annulé)
401 Unauthorized Aucune session active
404 Not Found Table introuvable ou non visible

Mise à jour en lot

Chaque élément nomme l'id de l'enregistrement (chaîne ou nombre) plus les fields à mettre à jour. Jusqu'à 100 enregistrements par appel.

PATCH /api/tables/contacts/records/batch
{
  "records": [
    { "id": "1", "fields": { "status": "active" } },
    { "id": 2, "fields": { "status": "archived" } }
  ],
  "returnRecords": true
}

Les mises à jour sont partielles par enregistrement — seuls les champs nommés sont écrits. Si un id est manquant ou une valeur invalide, la transaction est annulée.

Suppression en lot

Envoyez un tableau ids. Suppression réversible par défaut ; définissez permanent: true pour supprimer définitivement des enregistrements déjà supprimés de façon réversible (réservé aux administrateurs, appliqué dans la couche applicative). Jusqu'à 100 ID par appel.

DELETE /api/tables/contacts/records/batch
{
  "ids": ["1", "2", 3],
  "permanent": false
}

Restauration en lot

Récupérez plusieurs enregistrements supprimés de façon réversible en une seule fois. Les enregistrements qui ne sont pas actuellement supprimés sont ignorés ; un id manquant annule l'ensemble du lot.

POST /api/tables/contacts/records/batch/restore
{
  "ids": ["1", "2", "3"]
}

La restauration efface les champs deletedAt/deletedBy de chaque enregistrement et est consignée dans l'historique des modifications de l'enregistrement.

Upsert en lot

Créez ou mettez à jour de nombreux enregistrements correspondant à un ou plusieurs champs uniques, en une seule transaction. Nommez la ou les clés de fusion avec fieldsToMergeOn (alias : matchFields). Jusqu'à 100 enregistrements par appel.

POST /api/tables/contacts/records/upsert
{
  "records": [
    { "fields": { "email": "alice@example.com", "name": "Alice" } },
    { "fields": { "email": "carol@example.com", "name": "Carol" } }
  ],
  "fieldsToMergeOn": ["email"],
  "returnRecords": true
}

Chaque enregistrement est mis en correspondance sur les champs de fusion : une correspondance existante est mise à jour, sinon une nouvelle ligne est créée. L'upsert en lot est le chemin canonique pour la synchronisation idempotente depuis une source de vérité externe.

Résumé des limites et de la sémantique

Propriété Comportement
Atomicité Chaque lot est une seule transaction — tout ou rien
returnRecords false par défaut ; true renvoie les enregistrements affectés
Taille minimale Au moins un enregistrement/ID requis (400 sinon)
Auteur createdBy/updatedBy/deletedBy estampillés par enregistrement, comme pour les écritures uniques
Permissions RBAC et permissions au niveau des champs appliqués par enregistrement

Pages associées