Zaawansowane zapytania — filtrowanie, projekcja i paginacja w API

Trzy ścieżki w skrócie

Wszystkie trzy znajdują się w interaktywnej dokumentacji API (strona /developers), w sekcji Search, i wymagają uwierzytelnienia — zob. API Omniscol.

Filtr where (w stylu Mango / MongoDB)

Zarówno /api/search/entity, jak i /api/search/query przyjmują klauzulę where: ustrukturyzowany filtr o operatorach w stylu MongoDB. Pole odpowiada albo wartości bezpośredniej (niejawna równość), albo obiektowi operatorów; kilka operatorów na tym samym polu łączy się niejawnym I. Nazwy pól dopuszczają notację kropkową, aby dotrzeć do kontekstu nadrzędnego (na przykład sites.name).

Kilka przykładów:

{ "capacity": { "$gte": 20, "$lte": 50 } }
{ "level": { "$in": ["rok 1", "rok 2", "rok 3"] } }
{ "name": { "$regex": "^lab" } }
{ "city": { "$like": "kedzierzyn kozle" } }
{ "$or": [ { "capacity": { "$gte": 50 } }, { "specialisation": "chemistry" } ] }

Projekcja, sortowanie i paginacja

Na /api/search/query cztery dodatkowe dźwignie utrzymują odpowiedź zwartą i uporządkowaną — co ma znaczenie dla panelu zarządczego, a tym bardziej dla agenta AI rozliczanego za tokeny:

• project — lista pól do zachowania (notacja kropkowa jest dozwolona). Wszystko inne zostaje odrzucone.
• sort — jedno pole, asc albo desc. Pseudopole _count.<pole> sortuje według długości pola tablicowego.
• limit i offset — dzielą wyniki na strony.

Odpowiedź zwraca także blok meta: ile elementów istniało przed filtrowaniem, ile przeszło filtr i ile zostało zwróconych.

Pełny przykład

Znalezienie sal na co najmniej 30 miejsc, zachowanie wyłącznie ich nazwy i pojemności, od największej do najmniejszej, i pobranie pierwszych 20:

curl -X POST "https://nazwa-szkoly.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 to wewnętrzna nazwa punktu dostępu do odczytu, który ma zostać wykonany (taka, jaka widnieje na stronie /developers), params przenosi parametry właściwe temu punktowi dostępu, a extract_path wskazuje w razie potrzeby tablicę do filtrowania wewnątrz wyniku — pominięty tutaj, zostaje wykryty automatycznie.

Znalezienie wolnej sali lub wolnego nauczyciela

Najczęstsza integracja — zasilanie intranetu, narzędzia do rezerwacji lub ETL — to „kto lub co jest wolne w danym momencie?”. Punkty dostępu availability odpowiadają na to wprost: zwracają, dla każdej jednostki, wyłącznie wolne przedziały czasowe w żądanych datach, uwzględniając już lekcje, nieobecności i obowiązkową dostępność.

O dostępność pyta się na dwa sposoby:

• Z zakresem — GET /api/schedules/availability/{datesrange}/{entity} (w razie potrzeby /{entityId}) dla jednego typu jednostki — teachers, classrooms, groups, resources…
• Filtr jawny — GET /api/schedules/availability/{datesrange} z parametrem filter, którym zawęża się zbiór tym samym $where, co powyżej.

{datesrange} zapisuje się w formacie YYYYMMDD, a segmenty rozdzielone przecinkami pytają o daty rozproszone — idealnie do „dwóch wybranych poniedziałków”: 20261005,20261012. Każdy zwrócony przedział czasowy zawiera day, start, end i time (w minutach): „co najmniej 3 godziny” staje się więc testem time >= 180 po stronie integracji.

Nauczyciel wolny w konkretnym przedziale czasowym

„Którzy nauczyciele są wolni w poniedziałek 5 października?” — jedno wywołanie z zakresem:

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

Wolne przedziały czasowe wracają pogrupowane według rodzaju, a potem według nauczyciela — na przykład { "availability": { "teachers": { "a.kowalska": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } } — a narzędzie zewnętrzne zachowuje tego, który pokrywa żądany przedział czasowy.

Sale określonej wielkości, wolne w dwa poniedziałki

Filtr jednostek i dostępność można połączyć w jednym wywołaniu, używając użytecznego podzbioru składni — samego $where na pojemności:

curl -G "https://nazwa-szkoly.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 zwraca wolne przedziały czasowe, w oba poniedziałki, każdej sali na co najmniej 30 miejsc. ETL zachowuje następnie sale mające okno 3 godzin (time >= 180) w każdej z dat — składanie wyniku z kilku dni pozostaje po stronie integracji, co utrzymuje regułę jawną i możliwą do skontrolowania.

Parametr filter przyjmuje, dla każdego typu jednostki, prostą listę identyfikatorów ({"classrooms":["A101","B204"]}), znak wieloznaczny ({"teachers":"*"}), proste dopasowanie pola ({"teachers":[{"email":"…"}]}) albo ustrukturyzowany $where pokazany tutaj.

Wybór właściwej ścieżki

• „Gdzie pojawia się to słowo?” → POST /api/search.
• „Której jednostce odpowiada ta nazwa?” → POST /api/search/entity.
• „Proszę podać sale na ponad 30 miejsc, posortowane, pierwsza strona” → POST /api/search/query.
• „Kto lub co jest wolne w tym przedziale czasowym?” → GET /api/schedules/availability/….

Dla agenta AI

Te ścieżki istnieją w dużej mierze dla agentów AI. Wyszukiwanie pełnotekstowe i rozpoznawanie jednostek zamieniają sformułowanie użytkownika („nauczyciel Jan Kowalski”, „klasa 3A”) na precyzyjne identyfikatory; orkiestrator zapytań odpowiada następnie na filtrowane pytanie w jednym wywołaniu i zwraca tylko żądane pola — zamiast kilku wywołań i przewymiarowanej odpowiedzi. Po podłączeniu agenta przez MCP — podłączenie zewnętrznego agenta AI te narzędzia należą do tego, czym agent może się posługiwać.

Podłączenie do intranetu, ETL lub narzędzia partnerskiego

Te same ścieżki w trybie odczytu są tym, co narzędzie zewnętrzne wykorzystuje na co dzień. Typowe formy:

• Pobranie do intranetu lub panelu zarządczego — własna strona wywołuje punkty dostępu do odczytu (dostępność, punkt dostępu lekcji, panele zarządcze) z ograniczonym tokenem API i wyświetla wynik. Po stronie Omniscol nie ma nic do instalowania.
• Nocny ETL — zaplanowane zadanie pobiera to, czego potrzebuje (lekcje w oknie dat, godziny nauczyciela, obłożenie sal) i wczytuje to do własnego systemu informatycznego. search/query utrzymuje każde pobranie filtrowane, z projekcją i paginacją, dla zwartej odpowiedzi.
• Wysyłka z własnego systemu — kierunek odwrotny, aby utrzymać Omniscol zgodny z własnym źródłem prawdy: nocne zadanie może aktualizować klasy i nauczycieli (POST /api/external/classes, POST /api/external/teachers) albo wczytać listę przedmiotów niestandardowych (POST /api/admin/subjects/custom) z własnej bazy.
• Oprogramowanie SIS / ERP — dla Aurion, Auriga i podobnych właściwym narzędziem jest dedykowany konektor — zob. Synchronizacja z systemami zewnętrznymi.
• Sterowane zdarzeniami — aby otrzymywać powiadomienie o zmianie zamiast odpytywać w pętli, należy zarejestrować hook — zob. Personalizacja API.

Każdą integrację należy utrzymywać ograniczoną: token zawężony do rzeczywiście potrzebnych punktów dostępu, odnawiany regularnie i w trybie tylko do odczytu wszędzie tam, gdzie integracja jedynie czyta. Zob. API Omniscol.