API баптаулары: қол жеткізу нүктелерін қайта анықтау және вебхуктер

Оны қайдан табуға болады

Әкімшілік модулі, Импорт/Экспорт экраны, API баптаулары бөлімі, API батырмасы.

Экран тек Premium есептік жазбаларына арналған және күшейтілген аутентификациямен қорғалған: терезені ашпас бұрын Omniscol администратордың құпиясөзін қайта сұрайды. Бұл экрандағы кез келген әрекет интеграцияңыздың техникалық келісіміне әсер ететіндіктен, оны орнату Omniscol-мен байланыста жүргізіледі.

Жалпы конфигурация

Мұнда барлық вебхуктерге қолданылатын HTTP тақырыптарын (кілт1:мән1;кілт2:мән2 пішімі) анықтайсыз. Бұл өз серверіңізге арналған аутентификация токенін (мысалы, серверіңіз күтетін Authorization: Bearer …) көтеретін табиғи орын. Қайта анықтау үшін, керісінше, аутентификация қол жеткізу нүктесінің өз тақырыптарында беріледі (төменде қараңыз).

Қол жеткізу нүктесін қайта анықтау

Қайта анықтау Omniscol API-інің қол жеткізу нүктесін қайта белгілейді, сонда веб-қосымша оның орнына басқа URL-ді шақырады. Үш қолданыс бар, ең қуаттысынан ең қарапайымына дейін.

Деректерді ақпараттық жүйеңізден тікелей беру

Бұл ең қуатты қолданыс. Сіз оқу қол жеткізу нүктесін сыртқы URL-ге бағыттайсыз — әдетте мекемеңіздің ішкі ақпараттық жүйесімен байланыстыратын ETL жүйесіне. Сонда веб-қосымша деректі Omniscol сақтайтын жергілікті көшірмеден емес, осы жүйеден тікелей алады.

Нақтырақ айтсақ: бағыттау URL-і абсолютті сыртқы мекенжай болғанда, веб-қосымша оны Omniscol серверлері арқылы өтпей-ақ тікелей шақырады және жауапты сол күйінде пайдаланады — дәл Omniscol-дан келгендей. Бірден-бір шарт — жүйеңіз осы қол жеткізу нүктесі үшін Omniscol күтетін пішімде (дәл сондай JSON құрылымымен) жауап беруі: аралық түрлендіру жоқ. Осы қол жеткізу нүктесі үшін Omniscol-дың жергілікті көшірмесі енді сұралмайды; көрсетілетін дерек — сіздің жүйеңіздің тірі деректері.

Мысал: мекеменің пәндер каталогы ақпараттық жүйеңізден жедел беріледі, сондықтан мектеп жағындағы кез келген жаңарту Omniscol-да қайта импорттаусыз бірден көрінеді.

Жүйеңізге аутентификация мұнда қайта анықтау жолында енгізілетін қол жеткізу нүктесінің өз тақырыптарында беріледі (мысалы, Authorization: Bearer …). HTTP әдісін де әр қол жеткізу нүктесі үшін міндеттеуге болады.

Қосымшаның өзінің қол жеткізу нүктесін сыртқы тірі дереккөзге қайта қосу — қаншалықты қуатты болса, соншалықты талапты мүмкіндік: оны ІТ қызметіңізбен бірлесіп және Omniscol-мен байланыста пайдаланыңыз.

Өз серверіңізді немесе проксиді қосу

Шақыруларды өз серверіңіз немесе прокси арқылы да жіберуге болады — мысалы, әртүрлі көздер арасында ресурстарды бөлісуге (CORS) рұқсат беру үшін немесе веб-қосымша мен Omniscol арасына өз логикаңызды енгізу үшін.

Қол жеткізу нүктесін өшіру

Қол жеткізу нүктесін оған ешқандай бағыттау URL-ін бермеу арқылы (null әдісі) өшіресіз.

Мұның интерфейске әсерін ескеріңіз. Omniscol — интерфейс элементтері қолжетімді қол жеткізу нүктелерімен басқарылатын бір беттік веб-қосымша (SPA): батырмалар, қойындылар және мәзірлер өздері тәуелді қол жеткізу нүктесі болғанда ғана көрсетіледі. Сондықтан қол жеткізу нүктесін өшіру келесі көрсетуде оған тәуелді интерфейс элементтерін динамикалық түрде жоғалтады — ал модульдің барлық қол жеткізу нүктелерін өшірсеңіз, навигациядан бүкіл модуль жоғалады. Бұл элементтер жай жасырылмайды, жойылады, ал бәрі кодқа еш араласпай орындалады: конфигурацияны өзгертіп, қосымшаны қайта жүктеу жеткілікті.

Деректер кестесі әр қол жеткізу нүктесі бойынша мыналарды тізеді: оның кілтін (операцияның ішкі коды), бастапқы URL-ін, HTTP әдісін, бағыттаудың жаңа URL-ін және арнайы тақырыптарды. Іздеу өрісі қайта анықтайтын қол жеткізу нүктесін табуға мүмкіндік береді.

Вебхуктер (шығыс шақырулар)

Вебхук Omniscol-дан операция сәтті аяқталғаннан кейін сіздің URL-іңізге HTTP сұрауын жіберуді сұрайды. Бұл сыртқы жүйені нақты уақытта хабардар ұстаудың тетігі — ақпарат тақтасы, цифрлық жұмыс кеңістігі, кадр жүйесі, өз синхрондауыңыз…

Вебхук екі жолмен қосылады:

• нақты қол жеткізу нүктесіне (операцияның кілті);
• бір мезетте операциялар тобын қамтитын топтастырылған оқиғаға. Үш топтастырылған оқиға бар:
  • кестенің өзгеруі — қолданыстағы кестеге әсер ететін, жанама әсерлерін қоса алғандағы өзгеріс: кестені сақтау, сабақтарды құру, жылжыту немесе жою, кестені жариялау, күнге әсер етсе — мұғалімдер мен сыныптардың қатыспаулары және жарияланған кестедегі құрылымдық алып тастаулар (кабинет, пән…) — пәнді алып тастау оны пайдаланған сабақтарды жояды, бұл өз алдына өзгеріс. Жарияланбаған жобамен шектелген өңдеулер оны іске қоспайды;
  • мұғалімнің өзгеруі (қосу, жаңарту немесе жою);
  • пәннің өзгеруі (теңшелген пәндер).

Әр вебхук үшін кері шақыру URL-ін, HTTP әдісін, «Деректермен» құсбелгісін (бастапқы сұраудың денесін қосу керек пе?) және өз тақырыптарын толтырасыз.

Серверіңіз не алады

Шақыру application/json түрінде жіберіледі және сіздің тақырыптарыңыздан басқа мыналарды қамтиды:

• «Деректермен» опциясы қосулы болса, бастапқы сұраудың денесі;
• Omniscol метадеректер блогы: шақырылған URL, қол жеткізу нүктесінің коды, әдіс, параметрлер, пайдаланушының аутентификация токені, мекеменің идентификаторы және вебхуктің өз конфигурациясы;
• қадағалау тақырыптары: X-OS-original-query, X-OS-original-endpoint, X-OS-auth және X-School.

Кестенің өзгеруі оқиғасы үшін, «Деректермен» опциясы белсенді болғанда, шақыру қосымша сабақтардың айырмасын (қосылған, өзгертілген, жойылған сабақтар) қамтиды — тек өзгергенді тарату үшін ыңғайлы.

Жұмыс тәртібі

Вебхуктер пайдаланушы операциясы сәтті аяқталғаннан кейін фондық режимде жіберіледі: олар интерфейсті баяулатпайды және серверіңіз сәтсіз болса, оны бөгемейді. Сәтсіз шығыс шақыру Omniscol-дағы жұмысты үзбей журналға жазылады. Әр шақыруда қысқа күту уақыты (бірнеше секунд) бар: серверіңіз тез растауы және қалғанын өз жағында өңдеуі керек.

Білген жөн

• Omniscol API-і операциялардың жиыншасын ұсынады; қайта анықтау немесе вебхук тек шын мәнінде ашылған қол жеткізу нүктелеріне қолданылады. Тізім мен аутентификация үшін Omniscol API бетін қараңыз.
• Бағдарламалық пакетпен (ERP, кадр жүйесі, цифрлық жұмыс кеңістігі) интеграция үшін арнайы синхрондау жиі қолайлырақ — Сыртқы жүйелермен синхрондау бетін қараңыз. Ішкі жағынан дәл сол вебхук жүйесі пайдаланылады.
• ЖИ агенті деректеріңізді әзірлеусіз қарап шығуы үшін MCP — сыртқы ЖИ агентін қосу бетін қараңыз.