Кеңейтілген сұраулар — API-де сүзу, проекциялау және беттеу

Үш тәсілге жалпы шолу

Үшеуі де интерактивті API анықтамасында (/developers беті), Search бөлімінде көрсетілген және аутентификацияны талап етеді — Omniscol API бетін қараңыз.

where сүзгісі (Mango / MongoDB үлгісінде)

/api/search/entity және /api/search/query екеуі де where тармағын қабылдайды: MongoDB үлгісіндегі операторлары бар құрылымдық сүзгі. Өріс не тікелей мәнге (жасырын теңдік), не операторлар нысанына сәйкес келеді; бір өрістегі бірнеше оператор жасырын ЖӘНЕ арқылы біріктіріледі. Өріс атаулары жоғары контекске жету үшін нүктелі жазбаны қабылдайды (мысалы, sites.name).

Бірнеше мысал:

{ "capacity": { "$gte": 20, "$lte": 50 } }
{ "level": { "$in": ["7", "8", "9"] } }
{ "name": { "$regex": "^lab" } }
{ "city": { "$like": "алматы" } }
{ "$or": [ { "capacity": { "$gte": 50 } }, { "specialisation": "chemistry" } ] }

Проекция, сұрыптау және беттеу

/api/search/query нүктесінде тағы төрт тетік жауапты ықшам әрі реттелген етіп ұстайды — бұл бақылау тақтасы үшін маңызды, ал токенмен ақы алынатын ЖИ агенті үшін одан да маңызды:

• project — сақталатын өрістер тізімі (нүктелі жазбаға болады). Қалғанының бәрі алынып тасталады.
• sort — бір өріс, asc немесе desc. _count.<өріс> жалған өрісі массив өрісінің ұзындығы бойынша сұрыптайды.
• limit және offset — нәтижелерді беттейді.

Жауапта сондай-ақ meta блогы қайтарылады: сүзгіге дейін қанша элемент болғаны, қаншасы сүзгіден өткені және қаншасы қайтарылғаны.

Толық мысал

Кемінде 30 орындық кабинеттерді тауып, олардың тек атауы мен сыйымдылығын қалдыру, үлкенінен кішісіне қарай реттеп, алғашқы 20-сын алу:

curl -X POST "https://your-school.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 — орындалатын оқу нүктесінің ішкі атауы (/developers бетінде көрсетілгендей), params осы нүктеге тән параметрлерді береді, ал extract_path қажет болса нәтиже ішінде сүзілетін массивті көрсетеді — мұнда ол жазылмаған, сондықтан автоматты түрде анықталады.

Бос кабинетті немесе мұғалімді табу

Ең жиі кездесетін интеграция — интранетті, брондау құралын немесе ETL жүйесін толықтыру — «кім немесе не белгілі бір сәтте бос?» деген сұраққа жауап беру. availability қол жеткізу нүктелері бұған тікелей жауап береді: олар әр нысан бойынша сұралған күндердегі тек бос уақыт аралықтарын қайтарады, бұл ретте сабақтар, қатыспаулар және міндетті тілектер ескеріліп қойған.

Қолжетімділікті екі жолмен сұрауға болады:

• Аумақты — нысан түрі бойынша — teachers, classrooms, groups, resources… — GET /api/schedules/availability/{datesrange}/{entity} (қажет болса /{entityId}).
• Айқын сүзгі — GET /api/schedules/availability/{datesrange} жолын filter параметрімен қолдану, мұнда жиынды жоғарыда көрсетілген $where арқылы шектейді.

{datesrange} YYYYMMDD пішімінде жазылады, ал үтірмен бөлінген сегменттер жекелеген күндерді сұрайды — «берілген екі дүйсенбі» үшін өте ыңғайлы: 20261005,20261012. Қайтарылған әр уақыт аралығы day, start, end және time (минутпен) өрістерін қамтиды: сондықтан «кемінде 3 сағат» сіздің жағыңыздағы time >= 180 тексеруіне айналады.

Нақты уақыт аралығында бос мұғалім

«5 қазан, дүйсенбі күні қай мұғалімдер бос?» — аумақты бір шақыру:

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

Бос уақыт аралықтары түрі бойынша, содан кейін мұғалім бойынша топтастырылып оралады — мысалы { "availability": { "teachers": { "t.serikova": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } } — және сіздің құралыңыз қажетті уақыт аралығын қамтитынын таңдап алады.

Екі дүйсенбіде бос белгілі өлшемдегі кабинеттер

Нысан сүзгісі мен қолжетімділікті бір шақыруда біріктіріңіз, синтаксистің пайдалы жиыншасымен — тек сыйымдылық бойынша $where:

curl -G "https://your-school.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 кемінде 30 орындық әр кабинеттің екі дүйсенбідегі бос уақыт аралықтарын қайтарады. Содан кейін сіздің ETL жүйеңіз күндердің әрқайсысында 3 сағаттық (time >= 180) терезесі бар кабинеттерді қалдырады — бірнеше күн бойынша композиция сіздің жағыңызда қалады, бұл ережені айқын әрі тексеруге болатын етіп сақтайды.

filter нысан түрі бойынша идентификаторлардың қарапайым тізімін ({"classrooms":["A101","B204"]}), қойылмалы таңбаны ({"teachers":"*"}), қарапайым өріс сәйкестігін ({"teachers":[{"email":"…"}]}) немесе осында көрсетілген құрылымдық $where өрнегін қабылдайды.

Қолайлы тәсілді таңдау

• «Бұл сөз қайда кездеседі?» → POST /api/search.
• «Бұл атау қай нысанға сәйкес келеді?» → POST /api/search/entity.
• «30 орыннан артық кабинеттерді реттеп, бірінші беттен бер» → POST /api/search/query.
• «Осы уақыт аралығында кім немесе не бос?» → GET /api/schedules/availability/….

ЖИ агенті үшін

Бұл тәсілдер негізінен ЖИ агенттері үшін бар. Толық мәтінді іздеу мен нысанды анықтау пайдаланушының тұжырымын («мұғалім Н. Әбенов», «5А сыныбы») нақты идентификаторларға айналдырады; сұрау оркестраторы содан кейін сүзілген сұраққа бір шақырумен жауап береді және тек сұралған өрістерді қайтарады — бірнеше шақырудың және артық үлкен жауаптың орнына. Агентті MCP — сыртқы ЖИ агентін қосу арқылы қосқанда, бұл құралдар оның пайдалана алатындарының қатарына кіреді.

Оны интранетке, ETL жүйесіне немесе серіктес құралға қосу

Дәл осы оқу тәсілдерін үшінші тарап құралы күн сайын пайдаланады. Жиі кездесетін түрлері:

• Интранетке немесе бақылау тақтасына деректерді алу — сіздің бетіңіз оқу нүктелерін (қолжетімділік, сабақтар нүктесі, бақылау тақталары) шектелген API токенімен шақырады және нәтижені көрсетеді. Omniscol жағында ештеңе орнатудың қажеті жоқ.
• Түнгі ETL — жоспарланған тапсырма өзіне қажетінің бәрін (күндер терезесіндегі сабақтарды, мұғалімнің сағаттарын, кабинеттердің жүктемесін) алып, ақпараттық жүйеңізге жүктейді. search/query әр алуды сүзілген, проекцияланған және беттелген күйде ұстайды, сондықтан жауап ықшам болады.
• Сіздің жүйеңізден жіберу — кері бағыт, Omniscol-ды өзіңіздің дереккөзіңізбен үйлесімді ұстау үшін: түнгі тапсырма сыныптар мен мұғалімдерді жаңарта алады (POST /api/external/classes, POST /api/external/teachers) немесе дерекқорыңыздан теңшелген пәндер каталогын жүктей алады (POST /api/admin/subjects/custom).
• SIS / ERP бағдарламалық пакеті — Aurion, Auriga және соларға ұқсас жүйелер үшін арнайы коннектор лайықты құрал — Сыртқы жүйелермен синхрондау бетін қараңыз.
• Оқиғалармен басқарылатын — өзгеріс туралы айналдыра сұрап отырудың орнына хабарлама алу үшін вебхукті тіркеңіз — API баптаулары бетін қараңыз.

Әр интеграцияны шектеулі ұстаңыз: тек шынымен қажет қол жеткізу нүктелерімен шектелген, үнемі жаңартылып тұратын және тек оқитын жерде тек оқуға арналған токен. Omniscol API бетін қараңыз.