התאמה אישית של API: עקיפות של נקודות קצה ו-Webhook

Premium

התאמה אישית של API: מסך מתקדם, השמור למחלקת ה-IT, המאפשר להפנות נקודת קצה של ה-API לשרת אחר (פרוקסי, ניהול CORS, שרת פנימי) ולהפעיל Webhook — קריאות יוצאות למערכת שלכם — בכל שינוי של מערכת שעות, של מורה או של מקצוע. זמין בחשבונות Premium, מאחורי אימות מוגבר.

ההתאמה האישית של ה-API היא מסך טכני המיועד למחלקת ה-IT. הוא מאפשר להתאים את התנהגות ה-API של Omniscol עבור החשבון שלכם באמצעות שלושה מנופים:

  • תצורה כללית (כותרות HTTP משותפות);
  • עקיפה של נקודת קצה — הפניית יישום האינטרנט לכתובת URL אחרת, או השבתה של נקודת קצה;
  • Webhook — קריאות יוצאות ש-Omniscol שולח למערכת שלכם כשמתבצעת פעולה.

היכן למצוא אותו

במודול ניהול, במסך ייבוא/ייצוא, בקטע התאמות API, הכפתור API.

המסך שמור לחשבונות Premium ומוגן באימות מוגבר: Omniscol מבקש שוב את הסיסמה של מנהל המערכת לפני שהחלון נפתח. מכיוון שכל פעולה במסך זה משפיעה על החוזה הטכני של השילוב שלכם, ההטמעה שלו נעשית בתיאום עם Omniscol.

תצורה כללית

כאן מגדירים כותרות HTTP (בפורמט key1:value1;key2:value2) שחלות על כל ה-Webhook. זהו המקום הטבעי להעברת טוקן אימות לשרת שלכם (למשל Authorization: Bearer … שהשרת שלכם מצפה לו). לעומת זאת, בעקיפה האימות מועבר בכותרות הייחודיות לנקודת הקצה (ראו להלן).

עקיפה של נקודת קצה

עקיפה מגדירה מחדש נקודת קצה של ה-API של Omniscol, כך שיישום האינטרנט יפנה במקומה לכתובת URL אחרת. שלושה שימושים, מהחזק ביותר ועד הפשוט ביותר.

להגיש נתון בזמן אמת ממערכת המידע שלכם

זהו השימוש החזק ביותר. מפנים נקודת קצה לקריאה אל כתובת URL חיצונית — בדרך כלל ETL שמתממשק עם מערכת המידע הפנימית של המוסד שלכם. יישום האינטרנט שולף אז את הנתון ישירות מאותה מערכת, במקום מהעותק המקומי ש-Omniscol מחזיק.

הלכה למעשה: כשכתובת ההפניה היא כתובת חיצונית מוחלטת, יישום האינטרנט פונה אליה ישירות, בלי לעבור בשרתי Omniscol, וצורך את התשובה כמות שהיא — בדיוק כאילו הגיעה מ-Omniscol. המגבלה היחידה היא שהמערכת שלכם צריכה להשיב בפורמט ש-Omniscol מצפה לו עבור נקודת הקצה הזו (אותו מבנה JSON): אין שום המרה ביניים. עבור נקודת קצה זו, העותק המקומי של Omniscol אינו נשאל עוד; הנתון המוצג הוא הנתון החי של המערכת שלכם.

דוגמה: קטלוג המקצועות של המוסד המוגש בזמן אמת ממערכת המידע שלכם, כך שכל עדכון בצד בית הספר נראה מיד ב-Omniscol, בלי ייבוא מחדש.

האימות מול המערכת שלכם מועבר כאן בכותרות הייחודיות לנקודת הקצה (למשל Authorization: Bearer …), המוזנות בשורת העקיפה. גם שיטת ה-HTTP ניתנת לקביעה לכל נקודת קצה.

חיבור מחדש של נקודת קצה של היישום עצמו למקור חיצוני חי הוא אפשרות חזקה ותובענית כאחת: יש לטפל בה יחד עם מחלקת ה-IT שלכם, ובתיאום עם Omniscol.

להציב שרת משלכם או פרוקסי באמצע

ניתן גם להעביר את הקריאות דרך שרת משלכם או דרך פרוקסי — למשל כדי לאפשר שיתוף משאבים בין מקורות (CORS), או כדי להציב לוגיקה פנימית בין יישום האינטרנט לבין Omniscol.

להשבית נקודת קצה

משביתים נקודת קצה בכך שלא נותנים לה אף כתובת הפניה (שיטה null).

שימו לב להשפעה על הממשק. Omniscol הוא יישום אינטרנט בעמוד יחיד (SPA) שרכיבי הממשק שלו נשלטים על ידי נקודות הקצה הזמינות: כפתורים, לשוניות ותפריטים מוצגים רק אם נקודת הקצה שהם תלויים בה קיימת. השבתה של נקודת קצה גורמת אפוא להיעלמות דינמית, בתצוגה הבאה, של רכיבי הממשק התלויים בה — ואם משביתים את כל נקודות הקצה של מודול, המודול כולו נעלם מהניווט. הרכיבים האלה מוסרים ולא רק מוסתרים, וכל זה נעשה בלי שום התערבות בקוד: מספיק לשנות את התצורה ולטעון מחדש את היישום.

הטבלה מפרטת, לכל נקודת קצה: מפתח (הקוד הפנימי של הפעולה), כתובת ה-URL המקורית, שיטת ה-HTTP, כתובת ההפניה החדשה וכותרות ייחודיות. שדה חיפוש מאפשר למצוא את נקודת הקצה שרוצים לעקוף.

Webhook (קריאות יוצאות)

Webhook מבקש מ-Omniscol לשלוח בקשת HTTP לכתובת ה-URL שלכם אחרי שפעולה הצליחה. זהו המנגנון לעדכון מערכת חיצונית בזמן אמת — לוח תצוגה, סביבת עבודה דיגיטלית, מערכת משאבי אנוש, סנכרון פנימי…

Webhook מתחברים בשתי דרכים:

  • לפי נקודת קצה מסוימת (מפתח הפעולה);
  • לפי אירוע מקובץ, שמכסה בבת אחת משפחה של פעולות. קיימים שלושה אירועים מקובצים:
    • שינוי במערכת שעות — שינוי שנוגע למערכת השעות הפעילה, כולל תופעות לוואי: שמירת מערכת שעות, יצירה, העברה או מחיקה של שיעורים, פרסום מערכת שעות, היעדרויות של מורים או של כיתות ברגע שנוגעים בתאריך, והסרות מבניות (כיתת לימוד, מקצוע…) ממערכת שעות שפורסמה — הסרת מקצוע מוחקת את השיעורים שהשתמשו בו, וזה שינוי בפני עצמו. עריכות שמוגבלות לטיוטה שלא פורסמה אינן מפעילות אותו;
    • שינוי של מורה (הוספה, עדכון או מחיקה);
    • שינוי של מקצוע (מקצועות מותאמים אישית).

לכל Webhook מזינים את כתובת ה-URL לקריאה חוזרת, את שיטת ה-HTTP, את תיבת הסימון "עם נתונים" (האם לצרף את גוף הבקשה המקורית?) ואת הכותרות הייחודיות.

מה השרת שלכם מקבל

הקריאה נשלחת כ-application/json ונושאת, בנוסף לכותרות שלכם:

  • את גוף הבקשה המקורית אם האפשרות "עם נתונים" פעילה;
  • בלוק מטא-נתונים של Omniscol: כתובת ה-URL שנקראה, קוד נקודת הקצה, השיטה, הפרמטרים, טוקן האימות של המשתמש, מזהה המוסד והתצורה של ה-Webhook עצמו;
  • כותרות מעקב: X-OS-original-query, X-OS-original-endpoint, X-OS-auth ו-X-School.

באירוע שינוי במערכת שעות, כשהאפשרות "עם נתונים" פעילה, הקריאה כוללת בנוסף הפרשים של השיעורים (שיעורים שנוספו, שונו ונמחקו) — נוח כדי להפיץ רק את מה שהשתנה.

התנהגות

ה-Webhook יוצאים ברקע, אחרי שפעולת המשתמש הושלמה: הם אינם מאטים את הממשק ואינם חוסמים אותו אם השרת שלכם נכשל. קריאה יוצאת שלא הצליחה נרשמת ביומן, בלי להפריע לעבודה ב-Omniscol. לכל קריאה יש מגבלת זמן קצרה (כמה שניות): השרת שלכם צריך לאשר קבלה במהירות ולטפל בשאר בצד שלו.

טוב לדעת

  • ה-API של Omniscol חושף תת-קבוצה של פעולות; עקיפה או Webhook חלים רק על נקודות קצה שנחשפו בפועל. ראו את הדף Omniscol API לרשימה ולאימות.
  • עבור שילוב עם חבילת תוכנה (ERP, מערכת משאבי אנוש, סביבת עבודה דיגיטלית), הסנכרון הייעודי מתאים לרוב יותר — ראו את הדף סנכרון עם מערכות חיצוניות. מאחורי הקלעים נעשה שימוש באותה מערכת Webhook.
  • כדי שסוכן AI יעיין בנתונים שלכם בלי פיתוח, ראו את הדף MCP — חיבור סוכן AI חיצוני.

ראו גם