Erweiterte Abfragen — die API filtern, projizieren und paginieren

Die drei Suchflächen auf einen Blick

Alle drei erscheinen in der interaktiven API-Referenz (die Seite /developers), im Abschnitt Search, und erfordern eine Authentifizierung — siehe Omniscol-API.

Der Filter where (im Mango-/MongoDB-Stil)

/api/search/entity und /api/search/query akzeptieren beide eine where-Klausel: einen strukturierten Filter mit Operatoren im MongoDB-Stil. Ein Feld entspricht entweder einem direkten Wert (implizite Gleichheit) oder einem Operatoren-Objekt; mehrere Operatoren auf demselben Feld werden durch ein implizites UND kombiniert. Die Feldnamen akzeptieren die Punktnotation, um einen übergeordneten Kontext zu erreichen (zum Beispiel sites.name).

Einige Beispiele:

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

Projektion, Sortierung und Paginierung

Auf /api/search/query halten vier weitere Hebel die Antwort kompakt und geordnet — was für ein Dashboard zählt und noch mehr für einen KI-Agenten, der pro Token abgerechnet wird:

• project — die Liste der zu behaltenden Felder (Punktnotation erlaubt). Alles Übrige wird verworfen.
• sort — ein Feld, asc oder desc. Das Pseudofeld _count.<feld> sortiert nach der Länge eines Array-Felds.
• limit und offset — paginieren die Ergebnisse.

Die Antwort gibt außerdem einen meta-Block zurück: wie viele Elemente vor der Filterung existierten, wie viele den Filter passiert haben und wie viele zurückgegeben wurden.

Ein vollständiges Beispiel

Räume mit mindestens 30 Plätzen finden, nur ihren Namen und ihre Kapazität behalten, von der größten zur kleinsten, und die ersten 20 nehmen:

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 ist der interne Name des auszuführenden Lese-Endpunkts (so, wie er auf der Seite /developers angezeigt wird), params trägt die endpunkteigenen Parameter, und extract_path bezeichnet bei Bedarf das innerhalb des Ergebnisses zu filternde Array — hier weggelassen, wird es automatisch erkannt.

Einen freien Raum oder eine freie Lehrkraft finden

Die häufigste Integration — ein Intranet, ein Reservierungswerkzeug oder ein ETL speisen — lautet „wer oder was ist zu einem bestimmten Zeitpunkt frei?“. Die availability-Endpunkte beantworten dies direkt: Sie geben pro Entität nur die auf die angefragten Daten freien Zeitfenster zurück und berücksichtigen dabei bereits die Unterrichtsstunden, die Abwesenheiten und die verbindlichen Verfügbarkeiten.

Die Verfügbarkeit wird auf zwei Arten abgefragt:

• Skopiert — GET /api/schedules/availability/{datesrange}/{entity} (bei Bedarf /{entityId}) für einen Entitätstyp — teachers, classrooms, groups, resources …
• Expliziter Filter — GET /api/schedules/availability/{datesrange} mit einem filter, mit dem man die Menge über dasselbe oben gesehene $where einschränkt.

{datesrange} wird in YYYYMMDD geschrieben, und durch Kommas getrennte Segmente fordern verstreute Daten an — perfekt für „zwei bestimmte Montage“: 20261005,20261012. Jedes zurückgegebene Zeitfenster trägt day, start, end und time (in Minuten): „mindestens 3 Stunden“ wird auf Ihrer Seite also zu einem Test time >= 180.

Eine Lehrkraft, die in einem bestimmten Zeitfenster frei ist

„Welche Lehrkräfte sind am Montag, den 5. Oktober frei?“ — ein einziger skopierter Aufruf:

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

Die freien Zeitfenster kommen gruppiert nach Art, dann nach Lehrkraft zurück — zum Beispiel { "availability": { "teachers": { "t.dupont": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } } — und Ihr Werkzeug behält dasjenige, das das gewünschte Zeitfenster abdeckt.

Räume einer bestimmten Größe, frei an zwei Montagen

Kombinieren Sie einen Entitätsfilter und die Verfügbarkeit in einem einzigen Aufruf, mit einer nützlichen Teilmenge der Syntax — nur $where auf der Kapazität:

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 gibt die freien Zeitfenster jedes Raums mit mindestens 30 Plätzen an den beiden Montagen zurück. Ihr ETL behält anschließend die Räume, die an jedem der Daten ein 3-Stunden-Fenster (time >= 180) haben — die Zusammensetzung über mehrere Tage bleibt auf Ihrer Seite, was die Regel explizit und überprüfbar hält.

Der filter akzeptiert pro Entitätstyp eine einfache Liste von Kennungen ({"classrooms":["A101","B204"]}), einen Joker ({"teachers":"*"}), eine einfache Feldübereinstimmung ({"teachers":[{"email":"…"}]}) oder das hier gezeigte strukturierte $where.

Die richtige Suchfläche wählen

• „Wo taucht dieses Wort auf?“ → POST /api/search.
• „Welcher Entität entspricht dieser Name?“ → POST /api/search/entity.
• „Gib mir die Räume mit mehr als 30 Plätzen, sortiert, erste Seite“ → POST /api/search/query.
• „Wer oder was ist in diesem Zeitfenster frei?“ → GET /api/schedules/availability/….

Für einen KI-Agenten

Diese Suchflächen existieren zu einem großen Teil für KI-Agenten. Die Volltextsuche und die Entitätsauflösung verwandeln die Formulierung eines Benutzers („Lehrkraft Jean Dupont“, „Klasse 6A“) in präzise Kennungen; der Abfrage-Orchestrator beantwortet anschließend eine gefilterte Frage in einem einzigen Aufruf und gibt nur die angeforderten Felder zurück — statt mehrerer Aufrufe und einer überdimensionierten Antwort. Wenn Sie einen Agenten über MCP — einen externen KI-Agenten verbinden verbinden, gehören diese Werkzeuge zu dem, was er nutzen kann.

An ein Intranet, ein ETL oder ein Partnerwerkzeug anbinden

Dieselben Lese-Suchflächen sind das, was ein Drittwerkzeug täglich konsumiert. Gängige Formen:

• Ein Abzug in ein Intranet oder ein Dashboard — Ihre Seite ruft die Lese-Endpunkte (Verfügbarkeit, den Endpunkt der Unterrichtsstunden, die Dashboards) mit einem eingeschränkten API-Token auf und zeigt das Ergebnis an. Nichts auf Omniscol-Seite zu installieren.
• Ein nächtliches ETL — eine geplante Aufgabe holt sich, was sie braucht (die Unterrichtsstunden über ein Datumsfenster, die Stunden einer Lehrkraft, die Raumbelegung), und lädt es in Ihr Informationssystem. search/query hält jeden Abzug gefiltert, projiziert und paginiert, für eine kompakte Antwort.
• Ein Push aus Ihrem System — die umgekehrte Richtung, um Omniscol an Ihrer Quelle der Wahrheit ausgerichtet zu halten: Eine nächtliche Aufgabe kann Klassen und Lehrkräfte aktualisieren (POST /api/external/classes, POST /api/external/teachers) oder einen Katalog benutzerdefinierter Fächer (POST /api/admin/subjects/custom) aus Ihrer Datenbank laden.
• Eine SIS-/ERP-Softwarelösung — für Aurion, Auriga und Konsorten ist der dedizierte Konnektor das passende Werkzeug — siehe Synchronisierung mit externen Systemen.
• Ereignisgesteuert — um über eine Änderung benachrichtigt zu werden, statt in einer Schleife abzufragen, registrieren Sie einen Hook — siehe API-Anpassung.

Halten Sie jede Integration eingeschränkt: ein Token, das auf die tatsächlich nützlichen Endpunkte begrenzt ist, regelmäßig erneuert und überall dort schreibgeschützt, wo sie nur liest. Siehe Omniscol-API.