התקנת ממשק האינטרנט Html + API של הייפר

על מנת להתקין את יישום האינטרנט, יש לבצע את השלבים הבאים:
  1. הפעל את יישומון ההתקנה והתמיכה SYE Setup
  2. לחץ על הכפתור "Server Side Applications" (בצד שמאל), ובחר את הפריט "Hyper RAP Web-API" מהרשימה (בצד ימין). לחץ על הכפתור
    Continue
    .
  3. בחר את נתיב התיקיות המתאים להתקנה ולחץ על הכפתור
    DOWNLOAD & INSTALL
    .
    המתן לסוף ההתקנה.
  4. אנו ממליצים להתקין את יישומי האינטרנט בנתיב שיהיה לכם נוח לגשת אליו ולערוך בו קבצים בעת הצורך.
    ודאו שיש הרשאות קריאה וכתיבה מלאות (READ AND WRITE PRIVILEGES) למשתמש המריץ על תיקיית ההתקנה, כולל תתי-התיקיות שלה.
    לאחר התקנת היישום, הקבצים הבאים יימצאו בתיקיית ההתקנה:
    שם הקובץ תיאור
    Hyper_Website_API.exe יישום ה-"SYE Hyper Website API" עצמו. כל המערכת מקומפלת בקובץ הפעלה יחיד של Windows.
    Appl_Self_Upgrade.exe כלי שירות עבור אתחול ושדרוג אוטומטי של היישום (קובץ הפעלה של Windows).
    ChilkatDelphi.dll ספריית הצפנה ותקשורת בפרוטוקול SSL/TLS מיצרן מורשה בארה"ב. גרסאות 32/64 ביט.
    Hyper ERP Translation.json קובץ התרגומים המקורי התומך בריבוי שפות עבור כלל יישומי Hyper.
    Http_New_Setup.zip
    Http_Updates.zip     		קבצי CSS, JS וגופנים בקוד פתוח מבית SYE. זהו חלק מקוד המקור של ממשק המשתמש (UI).
    כאשר היישום נטען לראשונה, הוא יחלץ קבצים אלו לתוך תת-תיקייה בשם HTTP, ולאחר מכן ימחק את קבצי ה-zip הללו מהשרת.
  5. חיבור למסד הנתונים של Hyper: העתק קובץ
    .lic
    בודד, לתיקייה הראשית של היישום.
  6. הפעל את היישום בפעם הראשונה. הוא ייטען במצב הגדרות ראשוניות (Setup mode) ויציג תיבת דו-שיח המבקשת להזין את הגדרות החובה.
    מלא את כל שדות התצורה הבסיסית בחלון זה ולחץ על "OK" (ראה הדרכה על השדות בהמשך העמוד הזה).
    כתוצאה מכך, ייווצר קובץ בשם "Hyper_Website_API.ini" באותה התיקייה של קובץ ה-exe.
  7. התקן את SYE HTTP Server (במידה וטרם הותקן), בממשק הניהול הוסף שורה חדשה והתחל בבחירת תיקיית ה-HTTP שנוצרה !
    השרת יקרא את ההגדרות ישירות מקובץ ה-.ini, מה שיחסוך לך עבודה ויקל על תהליך החיבור.

הגדרות תצורה ראשיות (Main Configuration)

בהתקנה חדשה חלון זה יקפוץ ראשון.
כדי לערוך הגדרות אלו בשנית ולפתוח את חלון ההגדרות, יש להריץ את הקובץ "Hyper_Website_API.exe" יחד עם הפרמטר
-setup
.
ערכים אלו נשמרים בקובץ
Hyper_Website_API.ini
(בקידוד UTF-8). ניתן לערוך את הקובץ ידנית באמצעות עורך טקסט, אך יש לזכור להפעיל מחדש את היישום כדי שהשינויים יכנסו לתוקף.

Setup Window
שם השדה (Field Name) תיאור
Hyper Username שם המשתמש של היישום כפי שהוא מוגדר במסד הנתונים. שם המשתמש חייב להתחיל במחרוזת
"website_"
ואחריה טקסט לבחירתכם.
לדוגמה "Website_English" או "Website_Android_Json". כל פעולות פרסום הנתונים למערכת זו נשלחות לכתובות המתחילות ב-
"website_*"

אפשר (לא חובה) להגדיר את שם המשתמש הזה במאגר המשתמשים של הייפר ואז לשלוט על ההרשאות שלו לגישה לטבלאות ושדות (חבוי / קריאה בלבד).
Custom Hyper Database IP יש להשאיר שדה זה ריק, אלא אם שרת מסד הנתונים מוסתר בתוך רשת פנימית וסגורה, ובמקרה זה יש להזין את כתובת ה-IP המקומית שלו.
Incoming Proxy IP:Port הכתובת והפורט (Socket) שעליהם יישום האינטרנט מאזין לבקשות משרת ה-Proxy.
ה-"SYE HTTP Server" מתפקד כשרת Proxy. הוא מטפל בהגשת קבצים סטטיים (כמו מדיה ו-CSS) ומנהל את תקשורת ה-TLS (הצפנה).
בתוך השרת הפיזי (מכונת windows), ה- HTTP Server מתחבר לכל Hyper WebApp דרך כתובת IP ופורט פנימיים ללא הצפנה.
לדוגמה: הרשת החיצונית (WAN) יושבת על
10.0.0.x
בעוד שהיישומים הפנימיים מאזינים על
192.168.0.x

אם אינך זוכר או מכיר את מבנה הרשת המומלץ, חזור לעמוד הראשון התקנת יישומים בצד השרת ובחן את הסכמות השונות.
Domain Address כתובת המתחם הנקייה (בדרך כלל sub-domain).
לדוגמה:
portal.sye.co.il
, אין לרשום "http" או קווי לוכסן.
This Domain Purpose שדה זה קובע את ייעוד הדומיין והוא קריטי לאופן פעולת היישום ולניתוב הבקשות:
  • Default Web Portal: זהו ערך ברירת המחדל. היישום יופעל כפורטל שירות עצמי ללקוחות וגם CRM בסיסי למשתמשי הייפר.
  • API mode: זהה לאפשרות הראשונה, אך בפורמט Json API במקום דפי HTML. כל קריאה לכתובת HTML תענה בהודעת שגיאה מסוג "No Page".
  • Data Port Only: קליטת לידים / לקוחות / קריאות שירות / הזמנות, בגישה ציבורית המתאימה לדפי נחיתה וממשקים שאינם מאובטחים (לכן נחוצה התקנה נפרדת).
  • Database Connection: משמש ליצירת צינור נתונים ישיר בפורמט Json מול הטבלאות של הייפר. הרשאות הגישה מוגדרות בהייפר על פי שם המשתמש וקבוצות ההרשאה !
Http Media Path כאשר נדרש להצביע על שטח אחסון נוסף (בד"כ דיסק פיזי אחר), בו מאוחסנים קבצים פאסיביים נוספים אשר מבחינת השרת נמצאים באותו level כמו התיקייה HTTP הראשית.
לדוגמה: קבצי הדרכה בוידאו.
הקוד של יישום הייפר אינו צריך את ההפניה הזו, היא נדרשת להרחבות באמצעות script או להעלאת קבצי מדיה חדשים דרך ה WebApp עצמו.
Max Tenants מספר ה-Tenants המקסימלי שהיישום שומר בזיכרון בו זמנית.
Tenant הוא מצב עבודה זמני של משתמש / לקוח / ישות במערכת, למשל סשן HTML פעיל, קריאת API שצריכה לשמור הקשר, או תהליך תשלום שמחזיק token זמני.
כאשר נוצר Tenant חדש, השרת מחפש מקום פנוי במאגר. אם כל המקומות תפוסים, לא ניתן לפתוח Tenant נוסף עד שאחד מה-Tenants הקיימים יתפנה לפי זמן ה-Session Timeout.
ערך גבוה מאפשר יותר משתמשים או תהליכים פעילים במקביל, אך צורך יותר זיכרון בשרת.
ברירת המחדל היא 500. הטווח המותר להגדרה הוא 10 עד 250000.
חשוב בעיקר ב-Portal, אך גם ב-API-ים שיוצרים session או token זמני.
Max Threads מספר תתי-התהליכים המקסימלי שהיישום מפעיל במקביל לטיפול בבקשות שמגיעות מה-Proxy.
כל בקשת HTTP / API שנכנסת ליישום משויכת ל-thread מתוך מאגר ה-threads של השרת. לכן ערך זה קובע בעיקר את כמות הבקשות שיכולות להיות מטופלות באותו רגע.
אם כל ה-threads עסוקים ואין מקום פנוי במאגר, השרת מחזיר תשובת עומס מסוג HTTP 429 Too Many Requests.
ערך גבוה עשוי לשפר טיפול בעומס רגעי, אך גם מגדיל צריכת CPU, זיכרון וחיבורים למסד הנתונים. אין להגדיל אותו ללא צורך וללא בדיקה של משאבי השרת.
ברירת המחדל היא 5. הטווח המותר להגדרה הוא 2 עד 300.
חשוב בכל סוגי ההפעלה, במיוחד כאשר יש הרבה קריאות API קצרות או עומס רגעי גבוה.

ההבדל בין Max Threads לבין Max Tenants

שתי ההגדרות קשורות לעומס ולזיכרון של יישום ה-Web API, אך הן אינן מודדות את אותו הדבר.
Thread הוא תהליך עבודה שמטפל בבקשה שנכנסה עכשיו. Tenant הוא מצב Session שנשמר בזיכרון כדי לזהות משתמש / לקוח / תהליך גם בבקשות הבאות.

חשוב להבין: Tenant אינו Thread.
בקשה נכנסת מטופלת על ידי Thread, ולאחר סיום הבקשה ה-Thread משתחרר. אם הבקשה קשורה ל-session, ה-Tenant יכול להישאר בזיכרון גם אחרי שהבקשה הסתיימה.
לכן ייתכן מצב שבו יש מעט Threads אך הרבה Tenants: למשל 2 בקשות מטופלות כרגע, אך 1000 משתמשים / sessions שמורים בזיכרון.

התאמה לפי סוג הפעלת היישום

סוג הפעלה הגדרה מרכזית המלצה כללית
Default Web Portal גם Max Threads וגם Max Tenants להגדיר מספיק Tenants לפי מספר המשתמשים / לקוחות שיכולים להיות פעילים במקביל.
את Threads להגדיר לפי עומס הבקשות בפועל ולא לפי מספר המשתמשים הרשומים.
API mode בעיקר Max Threads אם ה-API הוא Stateless, כלומר כל קריאה עומדת בפני עצמה, אין צורך ב-Max Tenants גבוה במיוחד.
אם קיימים tokens זמניים או תהליכים רב-שלביים, יש להשאיר מספיק Tenants גם עבורם.
Data Port Only בעיקר Max Threads מתאים לקליטת טפסים / לידים / פניות חד-פעמיות.
בדרך כלל אין צורך בהרבה Tenants, אלא אם המימוש יוצר session ייעודי.
Database Connection בעיקר Max Threads בדרך כלל העבודה מתבצעת כקריאות API ישירות.
יש להגדיל Tenants רק אם קיימת לוגיקה ששומרת session בין קריאות.

כיצד להגדיר בצורה יעילה ובטוחה

  • התחל מערכים שמרניים, ולא מערכים גבוהים מדי “ליתר ביטחון”.
  • הגדל Max Threads כאשר יש הרבה בקשות שממתינות או מתקבלות תשובות עומס.
  • הגדל Max Tenants כאשר יש הרבה משתמשי Portal פעילים או הרבה תהליכים זמניים שנשמרים כ-session.
  • אל תחשב Threads לפי מספר המשתמשים. משתמשים רבים יכולים להיות מחוברים, אך רק חלק קטן מהם שולח בקשה באותה שנייה.
  • אל תגדיר Tenants לפי כמות הבקשות. Tenant מייצג session שנשמר בזיכרון, לא בקשה בודדת.
  • בסביבה עמוסה, עדיף להעלות ערכים בהדרגה ולבדוק צריכת CPU, זיכרון, זמני תגובה ושגיאות עומס.

תיקיית ה-HTTP

בצמוד לנתיב שבו מותקן "Hyper_Website_API.exe", תמצא תת-תיקייה בשם "HTTP" המכילה תמונות, מדיה, CSS, JS, גופנים ועוד קבצים פאסיביים.
"SYE HTTP Server" קורא את הקבצים הללו ישירות מהדיסק כדי להגיש אותם לדפדפנים. הם אינם רלוונטים ב- "Domain Purpose" מסוג API או DB.
היישום הנ"ל עלול לדרוס קבצים בתיקייה הזו, במסגרת עדכוני גרסה (בהם כלול הקובץ Http_Updates.zip), לכן עליך להכיר את המבנה ולדעת היכן מותר לך להתערב...
להלן פירוט של תוכן תתי התיקיות השונות ואופן הניהול שלהן:
שם התיקייה תיאור
CSS מכילה קבצי עיצוב (CSS), גופנים, ותמונות המשמשות לכפתורי הממשק.
אין לשנות את תוכן תיקייה זו! קבצים אלו הם חלק מובנה ממוצר המדף ועתידים להידרס במסגרת עדכון.
JS קבצי JavaScript. המערכת משתמשת בספריות jQuery המגיעות עם קבצי העיצוב והתמונות שלהן.
הקובץ "sye.js" מכיל קוד לעמודי HTML של מוצר המדף (לוגיקת צד-הלקוח).
אין לשנות את תוכן תיקייה זו! קבצים אלו הם חלק מובנה ממוצר המדף ועתידים להידרס במסגרת עדכון.
Media קבצי המדיה של הלקוח (כגון לוגו, אייקונים לתפריטים, תמונות רקע) שמורים בתיקייה זו.
באפשרותך לשנות את הקבצים הקיימים בתיקייה זו או להוסיף קבצים משלך.
* התוכן לתיקייה הזו נפרס רק פעם אחת במסגרת ההתקנה הראשונה (מתוך "Http_New_Setup.zip") עם תמונות ברירת מחדל שאנחנו מצפים מהלקוח להחליפן במסגרת עיצוב והטמעה.
Media\CSS תיקייה זו מיועדת לקבצי CSS מותאמים אישית של הלקוח כדי לשנות את עיצוב ה-HTML. צרו בה רק את הקבצים הדרושים לכם.
אלו הם שמות הקבצים האפשריים:
Custom_LTR.css     Custom_LTR_PC.css     Custom_LTR_Mobile.css
Custom_RTL.css     Custom_RTL_PC.css     Custom_RTL_Mobile.css

כיוון הטקסט נקבע לפי שפת המשתמש: LTR = משמאל לימין; RTL = מימין לשמאל;
PC הוא מסך ברירת המחדל; Mobile יטען כאשר מזוהה דפדפן נייד (Android / iOS).
Media\JS קוד JavaScript מותאם אישית לשינוי לוגיקת ממשק ה-HTML, או להוספת אנימציות מתקדמות.
שם הקובץ חייב להיות custom.js, ומתוכו תוכלו לטעון כל ספריית JS חיצונית שתרצו.
EMail Body Related Images תיקייה זו תיווצר באופן אוטומטי על ידי יישום הרשת בהפעלה הראשונה.
כל תמונה או קובץ שתניחו בתיקייה זו יצורפו אוטומטית להודעות דוא"ל יוצאות, בתנאי ששם הקובץ נרשם ומשולב בגוף ההודעה (לדוגמה: תמונות המוטמעות בעזרת cid).

* כל קבצי הגופנים, ה-JavaScript והתמונות המסופקים על ידי SYE, כפופים לרישיון שימוש חופשי או ברישיון קנייני השייך לחברת SYE software.