API-ді дұрыс пайдалану: кэш, вебхуктер және сұраныс лимиттері
PremiumOmniscol-дан деректер өзгерген-өзгермегенін әр минут сайын тексеретін интеграция көбіне алдыңғы шақырудағы жауаптың дәл өзін алады. Ол өз квотасын бекер жұмсайды және жаңа ақпарат алмай-ақ серверді жүктейді.
Бұл бетте осындай артық шақыруларды болдырмайтын тетіктер мен API-ге қолданылатын сұраныс лимиттері сипатталған.
Өзгермеген деректерді қайта алмау
API-дің оқуға арналған жауаптарының көбінде ETag тақырыбы болады, ол жауаптың
нұсқасын анықтайды. Бұл идентификаторды алынған деректермен бірге сақтап, келесі
шақыруда If-None-Match тақырыбында жіберіңіз:
curl -i -G "https://your-school.omniscol.com/api/schedules/lessons/20261102-20261108" \
-H "Authorization: Bearer $TOKEN" \
-H 'If-None-Match: W/"os1.…"'
Деректер өзгермесе, Omniscol жауап денесінсіз 304 Not Modified қайтарады. Сонда
кэште сақталған деректерді қайта пайдалана аласыз. Өзгерсе, жаңа ETag-пен бірге
толық 200 OK жауабын аласыз.
ETag — мағынасы жасырын мән: оны өзгертпей, тырнақшалары мен W/ префиксін қоса
сақтап, дәл сол күйінде қайта жіберіңіз, оны өзіңіз құруға не талдауға тырыспаңыз.
Ол өзін шығарған сұрауға және пайдаланылған қол жеткізуге ғана тән: оны басқа URL
үшін де, басқа токенмен де қолданбаңыз.
Cache-Control: private, no-cache тақырыбы жауапты жеке кэште сақтауға болатынын,
бірақ қайта пайдаланар алдында Omniscol-да қайта тексеру керек екенін білдіреді.
If-None-Match дәл осы үшін қызмет етеді.
Кейбір жауаптарда ETag болмайды, әсіресе олар бүгінгі күнге байланысты болып, есептік жазбаның деректері өзгермесе де өзгеріп отырса. Мұндай жауаптарды әр шақыруда қайтадан алу керек.
Omniscol-дың жаңа нұсқасы орналастырылғаннан кейін деректер өзгермесе де ETag-тар
жаңарады. Сонда бірінші шақыру 200 жауабын алады, ал келесі шақырулар қайтадан
304 жауаптарының артықшылығын пайдалана алады.
304 сервер жағындағы өңдеуді де азайтады. Көп жағдайда есептік жазбаның
деректері соңғы шақырудан бері өзгермесе, Omniscol тиісті деректерді қайта
оқымай-ақ жауап бере алады, және мұндай 304 API кілтіңізге қатысты квотада
есептелмейді. Деректерді қайта оқығаннан кейін алынған 304 қарапайым жауап
ретінде есептеледі.
Сондықтан деректер өзгермегенде тұрақты қайта тексеру арзан болып қала береді. Алайда оған IP мекенжайы бойынша жалпы лимит әлі де қолданылады.
Жауаптарды кэште сақтау
Қолданбаңыздың бірнеше пайдаланушысы немесе бірнеше экраны бірдей деректерді қарастырса, Omniscol-ға олардың әрқайсысы үшін жеке сұрау жіберудің қажеті жоқ.
Жауаптар мен олардың ETag-тарын өзіңіз басқаратын қолданба кэшінде сақтаңыз,
мысалы, Redis, Memcached немесе дерекқор кестесінде. Сонда қолданбаңыз деректерді
осы кэштен бере алады, ал кэш оларды If-None-Match арқылы Omniscol-да тұрақты
аралықтармен немесе вебхук өзгеріс туралы хабарлаған кезде қайта тексереді.
Кэш кілтінде толық URL, пайдаланылатын аутентификация токені және, егер оларды
қолдансаңыз, GET сұрауының денесі мен жауап соларға байланысты өзгеретін
тақырыптар, мысалы Accept-Language, ескерілуі керек. Құқықтары әртүрлі екі токен
әртүрлі деректерге қол жеткізе алады: біреуімен алынған жауап деректерге қол
жеткізуге құқығы жоқ пайдаланушыға ешқашан берілмеуі тиіс.
Әр жауаптың денесін де оның ETag-ымен бірге сақтаңыз. Сәйкес деректерсіз 304
жауабы күтілген нәтижені қалпына келтіруге мүмкіндік бермейді.
Бұл қолданба кэші ортақ HTTP кэшінен бөлек: Cache-Control: private
директивасы соңғысына жауаптарды сақтауға тыйым салады.
Тұрақты сұраудың орнына хабарландыру алу
Деректердің өзгергенін мезгіл-мезгіл тексерудің орнына, өзгеріс болған кезде Omniscol-дан қолданбаңызды хабардар етуді сұрауға болады.
Бұл тетік API баптау экранында реттелетін вебхуктерге негізделген (API баптаулары бетін қараңыз). Вебхук нақты қол жеткізу нүктесін немесе бірнеше өзгерісті біріктіретін оқиғаны, мысалы кестенің өзгертілуін бақылай алады.
Вебхук алынғанда кэшті жарамсыз ету
Ең қарапайым қолдану тәсілі — вебхукты кэшті жарамсыз ету сигналы ретінде өңдеу.
Хабарландыру келгенде қолданбаңыз қатысты деректерді ескірген деп белгілеп, Omniscol-да қайта тексереді. Өзгерістің мазмұнын түсіндірудің қажеті жоқ: вебхук жаңа тексеру керектігін ғана көрсетеді.
Бұл жұмыс тәсілі жоғарыда сипатталған кэшпен табиғи түрде үйлеседі.
Сабақтарды айырма арқылы синхрондау
Сабақтардың синхрондалған көшірмесін жүргізсеңіз, кестені өзгерту оқиғасының Деректермен опциясы қосылған, өзгертілген және жойылған сабақтары бар айырманы алуға мүмкіндік береді.
Сонда қолданбаңыз кестенің барлығын қайта алмай-ақ, тек осы өзгерістерді ғана қолдана алады.
Хабарландыруларды алуды қамтамасыз ету
Omniscol әр вебхукті жіберуге тек бір рет әрекет жасайды. Ол ең көбі төрт секунд күтеді, сәтсіздікте қайталамайды және оны өз журналдарына жазады.
Сондықтан сервер қабылдағанын тез растауы керек: 200 OK немесе 202 Accepted
жауабымен, содан кейін қажетті өңдеуді асинхронды түрде орындауы керек.
Сондай-ақ мезгіл-мезгіл қайта тексеруді қосымша қамсыздандыру тетігі ретінде
сақтаңыз. Вебхук жіберілген кезде серверіңіз жауап бермесе, осы тексеру
жіберіліп кеткен өзгерістерді анықтауға көмектеседі. 304 жауаптарының арқасында
деректер өзекті болғанда ол арзан болып қала береді.
Вебхуктерді қорғау
Хабарландырудың шынымен Omniscol-дан келгенін тексеру үшін тек қолданбаңыз бен Omniscol-ға ғана белгілі құпия мәні бар арнаулы HTTP тақырыбын реттеңіз. Сервер күтілген мәні жоқ шақыруларды қабылдамауы керек.
Хабарландыру контексі туралы ақпаратты екі қосымша тақырып береді:
X-Schoolқатысты Omniscol есептік жазбасын анықтайды;X-OS-authөзгерісті бастаған пайдаланушының аутентификация токенін қамтиды.
X-OS-auth ішінде берілетін токен құпия. Оны журналдарыңызға жазбаңыз, басқа
қызметтерге бермеңіз және оған қол жеткізуді қатаң шектеңіз.
Тек қажетті деректерді сұрау
Деректері аз жауапты жасау, тасымалдау және кэште сақтау әдетте жылдамырақ болады.
Сабақтар үшін сұралатын кезеңді шектеп, нәтижелерді өзіңізге қажет нысандар бойынша сүзіңіз (Сабақтар API-і бетін қараңыз).
Іздеу үшін search/query қол жеткізу нүктесі сүзгілерді, өрістерді проекциялауды
және беттеуді ұсынады (Кеңейтілген сұраулар бетін қараңыз).
Бір түрлі элементтердің (сыныптар, кабинеттер, пәндер және т.б.) көп санын жаңарту үшін, егер олар OpenAPI құжаттамасында бар болса, толық жинақты бір сұраумен жіберуге мүмкіндік беретін қол жеткізу нүктелерін таңдаңыз, жеке шақыруларды көбейтпеңіз.
Сұраныс лимиттерін сақтау
API шақыруларына екі сұраныс лимиті қолданылады. Лимитке жеткенде Omniscol
429 Too Many Requests жауабын қайтарады, оған сұрауды қайталамас бұрын күтуге
қажетті секунд санын көрсететін Retry-After тақырыбы қоса беріледі.
IP мекенжайы бойынша лимит
Жалпы лимит — 10 секундтық кезеңде 300 сұрау, MCP мен ақпарат тақталарын қоса, API-дің барлық қол жеткізу нүктелері бойынша.
Бұл шек дұрыс жасалған интеграция үшін әдетте жеткілікті. Дегенмен оған үзіліссіз шақыру циклдері немесе тым көп параллель сұраулар арқылы жетуге болады.
API кілті бойынша лимит
Бір API кілтінен шыққан токендер екі квотаны ортақ пайдаланады:
- минутына 60 сұрау;
- тәулігіне 5 000 сұрау.
Жауаптарда тұтынуды қадағалауға мүмкіндік беретін мына тақырыптар болуы мүмкін:
RateLimit-Policyқолданылатын квоталарды көрсетеді, мысалы60;w=60, 5000;w=86400;RateLimit-Limitең жақын толатын лимитке сәйкес квотаны көрсетеді;RateLimit-Remainingосы квота бойынша әлі жіберуге болатын сұраулар санын көрсетеді;RateLimit-Resetоның жаңаруына дейінгі секунд санын көрсетеді.
Бұл тақырыптар, атап айтқанда, деректер қайта оқылмай алынған 304
жауаптарында болмайды: олардың болмауы квотаның таусылғанын білдірмейді.
Квота таусылғанда 429 жауабы күту уақытын да өз денесінде retry_after
өрісі арқылы көрсетеді.
Деректерді қайта оқымай алынған 304 жауаптары осы квоталарда есептелмейді,
бірақ IP мекенжайы бойынша жалпы лимитке бағынады.
Бұл лимиттер API-ді заңды пайдалануға кедергі келтірсе, кілттерді көбейтпей, бізбен байланысыңыз.
Қателер мен қайталау әрекеттерін өңдеу
429 жауабынан кейін
Сұрауды қайталамас бұрын Retry-After көрсеткен уақытты күтіңіз. Бірден қайталау
пайдасыз және жағдайды ұзартуы мүмкін, әсіресе қолданбаңыздың бірнеше процесі
бір мезгілде қайталап жатса.
Сервер қатесінен немесе күту уақыты асып кеткеннен кейін
5xx қатесінен немесе күту уақыты асып кеткеннен кейін оқу сұрауын әрекеттер
арасындағы өсіп отыратын кідіріспен қайталауға болады: мысалы, бір секунд, содан
кейін екі, содан кейін төрт, әрекеттердің ең көп санына дейін.
Жазу сұрауында жағдай басқаша: жауап сізге ешқашан жетпесе де, өзгеріс сақталған болуы мүмкін. Өзгерістердің екі рет жасалуын болдырмау үшін операцияны қайталамас бұрын деректердің нақты күйін тексеріңіз.
401 жауабынан кейін
401 Unauthorized жауабын әдетте сол токенмен жаңа әрекет жасау арқылы шешу
мүмкін емес. Ол токеннің мерзімі өткенін, оның API кілті жойылғанын немесе
мерзімі өткенін, не сұралған қол жеткізу нүктесі кілт рұқсат ететіндердің
қатарында еместігін білдіруі мүмкін.
Шақыруды қайталамас бұрын токен мен оған қатысты рұқсаттарды тексеріңіз (Omniscol API бетін қараңыз).