Requêtage avancé — filtrer, projeter et paginer l'API

Les trois surfaces en un coup d'œil

Les trois figurent dans la référence d'API interactive (la page /developers), sous la section Search, et exigent une authentification — voir API Omniscol.

Le filtre where (façon Mango / MongoDB)

/api/search/entity et /api/search/query acceptent tous deux une clause where : un filtre structuré à opérateurs façon MongoDB. Un champ correspond soit à une valeur directe (égalité implicite), soit à un objet d'opérateurs ; plusieurs opérateurs sur le même champ se combinent par un ET implicite. Les noms de champs acceptent la notation pointée pour atteindre un contexte parent (par exemple sites.name).

Quelques exemples :

{ "capacity": { "$gte": 20, "$lte": 50 } }
{ "level": { "$in": ["L1", "L2", "L3"] } }
{ "name": { "$regex": "^lab" } }
{ "city": { "$like": "ivry sur seine" } }
{ "$or": [ { "capacity": { "$gte": 50 } }, { "specialisation": "chemistry" } ] }

Projection, tri et pagination

Sur /api/search/query, quatre leviers de plus gardent la réponse compacte et ordonnée — ce qui compte pour un tableau de bord, et plus encore pour un agent IA facturé au jeton :

• project — la liste des champs à conserver (notation pointée autorisée). Tout le reste est écarté.
• sort — un champ, asc ou desc. Le pseudo-champ _count.<champ> trie selon la longueur d'un champ tableau.
• limit et offset — paginent les résultats.

La réponse renvoie aussi un bloc meta : combien d'éléments existaient avant filtrage, combien ont passé le filtre, et combien ont été renvoyés.

Un exemple complet

Trouver les salles d'au moins 30 places, ne garder que leur nom et leur capacité, de la plus grande à la plus petite, et prendre les 20 premières :

curl -X POST "https://votre-etablissement.omniscol.com/api/search/query" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "call": "os_dashboard_classrooms_get",
        "where": { "capacity": { "$gte": 30 } },
        "project": ["name", "capacity"],
        "sort": { "capacity": "desc" },
        "limit": 20
      }'

call est le nom interne du point d'accès en lecture à exécuter (tel qu'affiché sur la page /developers), params porte les paramètres propres à ce point d'accès, et extract_path désigne au besoin le tableau à filtrer à l'intérieur du résultat — omis ici, il est détecté automatiquement.

Trouver une salle ou un enseignant disponible

L'intégration la plus courante — alimenter un intranet, un outil de réservation ou un ETL — c'est « qui ou quoi est libre à tel moment ? ». Les points d'accès availability y répondent directement : ils renvoient, par entité, uniquement les créneaux libres sur les dates demandées, en tenant déjà compte des cours, des absences et des vœux obligatoires.

La disponibilité se demande de deux façons :

• Scopée — GET /api/schedules/availability/{datesrange}/{entity} (au besoin /{entityId}) pour un type d'entité — teachers, classrooms, groups, resources…
• Filtre explicite — GET /api/schedules/availability/{datesrange} avec un filter, où l'on restreint l'ensemble avec le même $where vu plus haut.

{datesrange} s'écrit en YYYYMMDD, et des segments séparés par des virgules demandent des dates éparses — parfait pour « deux lundis donnés » : 20261005,20261012. Chaque créneau renvoyé porte day, start, end et time (en minutes) : « au moins 3 heures » devient donc un test time >= 180 de votre côté.

Un enseignant libre sur un créneau précis

« Quels enseignants sont libres le lundi 5 octobre ? » — un seul appel scopé :

curl -G "https://votre-etablissement.omniscol.com/api/schedules/availability/20261005/teachers" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode "with_entities=true"

Les créneaux libres reviennent groupés par nature, puis par enseignant — par exemple { "availability": { "teachers": { "t.dupont": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } } — et votre outil retient celui qui couvre le créneau voulu.

Des salles d'une certaine taille, libres sur deux lundis

Combinez un filtre d'entité et la disponibilité en un seul appel, avec un sous-ensemble utile de la syntaxe — juste $where sur la capacité :

curl -G "https://votre-etablissement.omniscol.com/api/schedules/availability/20261005,20261012" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode 'filter={"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}' \
  --data-urlencode "with_entities=true"

Omniscol renvoie les créneaux libres, sur les deux lundis, de chaque salle d'au moins 30 places. Votre ETL retient ensuite les salles ayant une fenêtre de 3 heures (time >= 180) sur chacune des dates — la composition sur plusieurs jours reste de votre côté, ce qui garde la règle explicite et vérifiable.

Le filter accepte, par type d'entité, une simple liste d'identifiants ({"classrooms":["A101","B204"]}), un joker ({"teachers":"*"}), une correspondance de champ simple ({"teachers":[{"email":"…"}]}) ou le $where structuré montré ici.

Choisir la bonne surface

• « Où ce mot apparaît-il ? » → POST /api/search.
• « À quelle entité correspond ce nom ? » → POST /api/search/entity.
• « Donne-moi les salles de plus de 30 places, triées, première page » → POST /api/search/query.
• « Qui ou quoi est libre sur ce créneau ? » → GET /api/schedules/availability/….

Pour un agent IA

Ces surfaces existent en grande partie pour les agents IA. La recherche plein texte et la résolution d'entité transforment la formulation d'un utilisateur (« enseignant Jean Dupont », « classe 6A ») en identifiants précis ; l'orchestrateur de requêtes répond ensuite à une question filtrée en un seul appel et ne renvoie que les champs demandés — au lieu de plusieurs appels et d'une réponse surdimensionnée. Lorsque vous connectez un agent via MCP — connecter un agent IA externe, ces outils font partie de ce qu'il peut utiliser.

Le brancher sur un intranet, un ETL ou un outil partenaire

Ces mêmes surfaces en lecture sont ce qu'un outil tiers consomme au quotidien. Formes courantes :

• Un tirage vers un intranet ou un tableau de bord — votre page appelle les points d'accès en lecture (disponibilité, le point d'accès des séances, les tableaux de bord) avec un jeton d'API restreint, et affiche le résultat. Rien à installer côté Omniscol.
• Un ETL nocturne — une tâche planifiée récupère ce dont elle a besoin (les séances sur une fenêtre de dates, les heures d'un enseignant, l'occupation des salles) et le charge dans votre système d'information. search/query garde chaque tirage filtré, projeté et paginé, pour une réponse compacte.
• Une poussée depuis votre système — le sens inverse, pour garder Omniscol aligné sur votre source de vérité : une tâche nocturne peut mettre à jour classes et enseignants (POST /api/external/classes, POST /api/external/teachers) ou charger un catalogue de matières personnalisées (POST /api/admin/subjects/custom) depuis votre base.
• Un progiciel SIS / ERP — pour Aurion, Auriga et consorts, le connecteur dédié est l'outil adapté — voir Synchronisation avec des systèmes externes.
• Piloté par événements — pour être notifié d'un changement plutôt que d'interroger en boucle, enregistrez un hook — voir Personnalisation d'API.

Gardez chaque intégration restreinte : un jeton limité aux points d'accès réellement utiles, renouvelé régulièrement, et en lecture seule partout où elle ne fait que lire. Voir API Omniscol.