שיטות מומלצות לפיתוח ולעיצוב של שרת proxy ל-API

אתם צופים במסמכי העזרה של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info

מטרת המסמך הזה היא לספק קבוצה של סטנדרטים ושיטות מומלצות לפיתוח באמצעות Apigee Edge. הנושאים שבהם נעסוק כאן כוללים תכנון, תכנות, שימוש במדיניות, מעקב וניפוי באגים. המידע נאסף על סמך הניסיון של מפתחים שעובדים עם Apigee כדי להטמיע תוכניות API מוצלחות. זהו מסמך דינמי שיעודכן מדי פעם.

בנוסף להנחיות שמפורטות כאן, כדאי לעיין גם בפוסט בקהילה בנושא דוגמאות לאופן העבודה הלא נכון ב-Apigee Edge.

תקני פיתוח

תגובות ומסמכי תיעוד

  • מוסיפים הערות בתוך הטקסט בהגדרות של ProxyEndpoint ו-TargetEndpoint. תגובות משפרות את הקריאוּת של תהליך, במיוחד במקרים שבהם שמות קובצי המדיניות לא מתארים בצורה מספקת את הפונקציונליות הבסיסית של התהליך.
  • התגובות צריכות להיות מועילות. הימנעו מתגובות מובנות מאליהן.
  • להשתמש בהקפדה על עקביות במדדים כמו הכנסה, רווחים, יישור אנכי וכו'.

תכנות בסגנון של מסגרת

כתיבה בסגנון מסגרת כוללת אחסון של משאבי שרת proxy של API במערכת הבקרה של הגרסאות שלכם, לשימוש חוזר בסביבות פיתוח מקומיות. לדוגמה, כדי לעשות שימוש חוזר במדיניות, אפשר לאחסן אותה במערכת לניהול גרסאות כדי שמפתחים יוכלו לסנכרן אותה ולהשתמש בה בסביבות הפיתוח שלהם.

  • כדי להפעיל את העיקרון DRY ('אל תחזרו על עצמכם'), במידת האפשר, צריך להטמיע בסקריפטים ובהגדרות המדיניות פונקציות מיוחדות שאפשר להשתמש בהן שוב. לדוגמה, אפשר לקרוא למדיניות ייעודית לחילוץ של פרמטרים של שאילתות מהודעות בקשה בשם ExtractVariables.ExtractRequestParameters. אפשר לקרוא למדיניות ייעודית להחדרת כותרות CORS בשם AssignMessage.SetCORSHeaders. לאחר מכן תוכלו לאחסן את כללי המדיניות האלה במערכת בקרת הגרסאות ולהוסיף אותם לכל שרת proxy של API שצריך לחלץ פרמטרים או להגדיר כותרות CORS, בלי שתצטרכו ליצור הגדרות יתירות (ולכן קשות יותר לניהול).
  • ניקיון של מדיניות ומשאבים שלא בשימוש (JavaScript,‏ Java,‏ XSLT וכו') משרתי proxy של API, במיוחד משאבים גדולים שעשויים להאט את תהליכי הייבוא והפריסה.

מוסכמות למתן שמות

  • מאפיין המדיניות name ושם קובץ המדיניות ב-XML חייבים להיות זהים.
  • מאפיין name של מדיניות Script ו-ServiceCallout צריך להיות זהה לשם של קובץ המשאב.
  • DisplayName צריך לתאר במדויק את הפונקציה של המדיניות למי שלא עבד עם שרת ה-API הזה בעבר.
  • נותנים שמות לכללי המדיניות בהתאם לתפקידם. מומלץ להשתמש ב-Apigee במוסכמה עקבית למתן שמות למדיניות. לדוגמה, השתמשו בקידומות קצרות ואחריהן רצף של מילים תיאוריות המופרדות בקו מפריד. לדוגמה, AM-xxx למדיניות AssignMessage. מידע נוסף זמין בכלי apigeelint.
  • יש להשתמש בסיומות המתאימות לקובצי המשאבים: .js ל-JavaScript,‏ .py ל-Python ו-.jar לקובצי JAR של Java.
  • שמות המשתנים צריכים להיות עקביים. אם בוחרים סגנון, כמו camelCase או under_score, צריך להשתמש בו בכל שרת ה-proxy של ה-API.
  • במידת האפשר, כדאי להשתמש בתחילית של משתנים כדי לארגן אותם לפי המטרה שלהם, לדוגמה, Consumer.username ו-Consumer.password.

פיתוח של proxy ל-API

שיקולים ראשוניים בתכנון

  • לקבלת הנחיות לעיצוב ממשקי API ל-REST, אפשר להוריד את הספר האלקטרוני עיצוב Web API: החוליה החסרה.
  • נעזרים במדיניות ובפונקציונליות של Apigee Edge ככל האפשר כדי ליצור שרתי proxy ל-API. מומלץ להימנע מכתיבה של כל הלוגיקה של שרת ה-proxy במשאבים של JavaScript,‏ Java או Python.
  • ליצור תהליכים בצורה מאורגנת. עדיף להשתמש במספר תהליכים, שבכל אחד מהם יש תנאי אחד, במקום להשתמש בכמה קבצים מצורפים מותנים לאותו תהליך מקדים ותהליך לאחר.
  • כ 'אמצעי הגנה מפני כשל', יוצרים שרת proxy ל-API שמוגדר כברירת מחדל עם נתיב בסיס של ProxyEndpoint‏ /. אפשר להשתמש באפשרות הזו כדי להפנות מחדש בקשות API בסיסיות לאתר של מפתחים, כדי להחזיר תגובה מותאמת אישית או כדי לבצע פעולה אחרת שימושית יותר מאשר החזרת messaging.adaptors.http.flow.ApplicationNotFound שמוגדרת כברירת מחדל.
  • שימוש במשאבים של TargetServer כדי לבטל את הקישור בין הגדרות TargetEndpoint לכתובות URL ספציפיות, כדי לתמוך בקידום מכירות בסביבות שונות.
    איך מבצעים איזון עומסים בין שרתי קצה עורפי
  • אם יש לכם כמה כללי RouteRule, צריך ליצור אחד בתור 'ברירת המחדל', כלומר בתור RouteRule ללא תנאי. מוודאים ש-RouteRule שמוגדרת כברירת מחדל מופיעה אחרונה ברשימת ה-Routes התנאי. הערכת כללי RouteRules מתבצעת מלמעלה למטה ב-ProxyEndpoint.
    הפנייה לנושא הגדרת שרת proxy ל-API
  • גודל החבילה של שרת ה-proxy ל-API: החבילות של שרת ה-proxy ל-API לא יכולות להיות גדולות מ-15MB. ב-Apigee Edge for Private Cloud, אפשר לשנות את מגבלת הגודל על ידי שינוי המאפיין thrift_framed_transport_size_in_mb במיקומים הבאים: cassandra.yaml (ב-Cassandra) ו-conf/apigee/management-server/repository.properties.
  • ניהול גרסאות API: כדי לקרוא את ההמלצות של Apigee בנושא ניהול גרסאות API, תוכלו לעיין בקטע 'ניהול גרסאות' בספר האלקטרוני עיצוב Web API: החוליה החסרה.

הפעלת CORS

לפני פרסום ממשקי ה-API, צריך להפעיל את CORS בשרתי ה-proxy של ה-API כדי לתמוך בבקשות מצד הלקוח ממקורות שונים.

CORS (שיתוף משאבים בין מקורות) הוא מנגנון סטנדרטי שמאפשר לקריאות XMLHttpRequest ‏ (XHR) של JavaScript שמבוצעות בדף אינטרנט לקיים אינטראקציה עם משאבים מדומיינים שאינם המקור. CORS הוא פתרון נפוץ למדיניות המקור הזהה שאוכפת על ידי כל הדפדפנים. לדוגמה, אם אתם מבצעים קריאה של XHR ל-Twitter API מקוד JavaScript שפועל בדפדפן, הקריאה תיכשל. הסיבה לכך היא שהדומיין שמציג את הדף לדפדפן שלכם הוא לא זהה לדומיין שמציג את Twitter API. הפתרון לבעיה הזו הוא CORS, שמאפשר לשרתים להביע הסכמה אם הם רוצים לספק שיתוף משאבים בין מקורות.

למידע על הפעלת CORS בשרתי ה-proxy של ה-API לפני פרסום ממשקי ה-API, ראו הוספת תמיכה ב-CORS לשרת proxy של API.

גודל המטען הייעודי של ההודעה

כדי למנוע בעיות זיכרון ב-Edge, גודל המטען הייעודי של ההודעה מוגבל ל-10MB. אם תחרגו מהגדלים האלה, תקבלו את השגיאה protocol.http.TooBigBody.

הבעיה הזו מופיעה גם בפוסט הזה בקהילה של Apigee.

ריכזנו כאן את השיטות המומלצות לטיפול בהודעות גדולות ב-Edge:

  • שידור בקשות ותגובות. חשוב לזכור: כשאתם משדרים, למדיניות אין יותר גישה לתוכן ההודעה. בקשות ותשובות בסטרימינג
  • ב-Edge for Private Cloud בגרסה 4.15.07 וגרסאות קודמות, עורכים את הקובץ http.properties של מעבד ההודעות כדי להגדיל את המגבלה בפרמטר HTTPResponse.body.buffer.limit. חשוב לבדוק את השינוי לפני הפריסה בסביבת הייצור.
  • ב-Edge for Private Cloud בגרסה 4.16.01 ואילך, בקשות עם מטען שימושי חייבות לכלול את הכותרת Content-Length, או במקרה של סטרימינג את הכותרת Transfer-Encoding: chunked. בבקשת POST לשרת proxy של API עם עומס נתונים ריק, צריך להעביר את הערך 0 עבור Content-Length.
  • ב-Edge for Private Cloud בגרסה 4.16.01 ואילך, כדי לשנות את המגבלות, מגדירים את המאפיינים הבאים ב-‎/opt/apigee/router.properties או ב-message-processor.properties. למידע נוסף, ראו הגדרת מגבלת גודל ההודעה בנתב או במעבד ההודעות.

    ערך ברירת המחדל של שני המאפיינים הוא '10m', שתואם ל-10MB‎:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

טיפול בכשלים

  • שימוש ב-FaultRules לטיפול בכל טיפול בכשלים. (מדיניות RaiseFault משמשת להפסקת תהליך העברת ההודעה ולשליחת העיבוד לתהליך FaultRules).
  • בתהליך FaultRules, משתמשים במדיניות AssignMessage כדי ליצור את תגובת השגיאה, ולא במדיניות RaiseFault. ביצוע מותנה של כללי מדיניות AssignMessage על סמך סוג השגיאה שמתרחשת.
  • תמיד כולל טיפול שגיאות 'catch-all' שמוגדר כברירת מחדל, כדי שאפשר יהיה למפות שגיאות שנוצרו על ידי המערכת לפורמטים של תגובות לשגיאות שהוגדרו על ידי הלקוח.
  • אם אפשר, תמיד כדאי לוודא שהתשובות לשגיאות תואמות לפורמטים הרגילים שזמינים בחברה או בפרויקט.
  • שימוש בהודעות שגיאה בעלות משמעות שאנשים יכולים לקרוא, עם הצעה לפתרון לתנאי השגיאה.

טיפול בכשלים

שיטות מומלצות בתחום מפורטות במאמר עיצוב תגובות שגיאה ב-REST.

התמדה

מפות מפתח/ערך

  • מומלץ להשתמש במפות מפתח/ערך רק למערכי נתונים מוגבלים. הן לא מיועדות לאחסון נתונים לטווח ארוך.
  • כשמשתמשים במפות מפתח/ערך, חשוב להביא בחשבון את הביצועים, כי המידע הזה מאוחסן במסד הנתונים של Cassandra.

המדיניות בנושא פעולות במפות של מפתחות וערכים

שמירת תגובות במטמון

  • לא מאכלסים את המטמון של התשובה אם התגובה לא מוצלחת או אם הבקשה היא לא בקשת GET. לא כדאי לשמור בזיכרון פעילות של יצירה, עדכון ומחיקה. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • לאכלס את המטמון בסוג תוכן אחד עקבי (לדוגמה, XML או JSON). אחרי שמאחזרים רשומה של responseCache, ממירים אותה לסוג התוכן הנדרש באמצעות JSONtoXML או XMLToJSON. כך לא יאוחסנו נתונים כפולים, משולשים או יותר.
  • מוודאים שמפתח המטמון מספיק לדרישות השמירה במטמון. ברוב המקרים אפשר להשתמש ב-request.querystring בתור המזהה הייחודי.
  • לא כוללים את מפתח ה-API (client_id) במפתח המטמון, אלא אם נדרש באופן מפורש. בדרך כלל, ממשקי API שמאובטחים רק באמצעות מפתח יחזירו את אותם נתונים לכל הלקוחות עבור בקשה נתונה. לא יעיל לאחסן את אותו ערך במספר רשומות על סמך מפתח ה-API.
  • כדאי להגדיר מרווחי זמן מתאימים לתפוגת התוקף של המטמון כדי למנוע קריאות מלוכלכות.
  • כשהדבר אפשרי, כדאי לנסות להגדיר את מדיניות המטמון של התשובה שמאכלסת את המטמון כך שתתבצע במהלך תהליך התגובה של ProxyEndpoint PostFlow, כמה שיותר מאוחר. במילים אחרות, צריך להריץ אותו אחרי שלבי התרגום והתהליך של בחירת הרשת (Mediation), כולל תהליך בחירת הרשת שמבוסס על JavaScript והמרה בין JSON ל-XML. שמירת נתונים שעברו תהליך בחירת רשת במטמון מאפשרת לכם להימנע מהעלות של ביצועים שנובעת מהפעלת שלב בחירת הרשת בכל פעם שאתם מאחזרים נתונים שנשמרו במטמון.

    לתשומת ליבכם: אם תהליך בחירת הרשת מניב תגובה שונה מבקשה לבקשה, מומלץ לאחסן במטמון נתונים ללא תהליך בחירת רשת.

  • מדיניות המטמון של התשובה לחיפוש הרשומה במטמון צריכה להתרחש בתהליך PreFlow של בקשת ProxyEndpoint. מומלץ להימנע משימוש בלוגיקה מיותרת, מלבד יצירת מפתח מטמון, לפני שמחזירים רשומה במטמון. אחרת, היתרונות של האחסון במטמון יהיו מינימליים.
  • באופן כללי, תמיד כדאי לבצע את החיפוש במטמון התשובות קרוב ככל האפשר לבקשת הלקוח. לעומת זאת, כדאי לאכלס את המטמון של התשובות קרוב ככל האפשר לתשובה של הלקוח.
  • כשמשתמשים בכמה כללי מדיניות שונים של מטמון תגובות בשרת proxy, צריך לפעול לפי ההנחיות הבאות כדי להבטיח התנהגות נפרדת לכל אחד מהם:
    • ביצוע כל מדיניות על סמך תנאים בלתי ניתנים להפרדה. כך תוכלו לוודא שרק אחת מכמה מדיניות מטמון תגובות מופעלת.
    • מגדירים משאבי מטמון שונים לכל מדיניות מטמון של תגובה. מציינים את משאב המטמון ברכיב <CacheResource> של המדיניות.

המדיניות בנושא מטמון התשובות

מדיניות וקוד בהתאמה אישית

מדיניות או קוד מותאם אישית?

  • השתמשו במדיניות המובנית קודם כול (כשהדבר אפשרי). כללי המדיניות של Apigee עברו תהליך הקשחה, אופטימיזציה ותמיכה. לדוגמה, כדאי להשתמש במדיניות AssignMessage ו-ExtractVariables הרגילות במקום ב-JavaScript (כשהדבר אפשרי) כדי ליצור עומסי נתונים, לחלץ מידע מעומסי נתונים (XPath,‏ JSONPath) וכו'.
  • עדיף להשתמש ב-JavaScript במקום ב-Python וב-Java. עם זאת, אם הביצועים הם הדרישה העיקרית, כדאי להשתמש ב-Java במקום ב-JavaScript.

JavaScript

  • כדאי להשתמש ב-JavaScript אם הוא אינטואיטיבי יותר ממדיניות Apigee (לדוגמה, כשמגדירים את target.url לשילובים רבים של URI שונים).
  • ניתוח מטען נתונים מורכב, כמו איטרציה על אובייקט JSON וקידוד/פענוח Base64.
  • למדיניות JavaScript יש מגבלה זמן, ולכן לולאות אינסופיות חסומות.
  • תמיד צריך להשתמש בשלבים של JavaScript ולהעביר את הקבצים לתיקיית המשאבים jsc. בסוג המדיניות JavaScript, הקוד עובר הידור מראש בזמן הפריסה.

תכנות proxy של API באמצעות JavaScript

Java

  • כדאי להשתמש ב-Java אם הביצועים הם בעדיפות הגבוהה ביותר, או אם לא ניתן להטמיע את הלוגיקה ב-JavaScript.
  • הכללת קובצי מקור של Java במעקב אחר קוד מקור.

למידע נוסף על שימוש ב-Java בשרתי proxy ל-API, אפשר לעיין במאמר המרת התגובה לאותיות רישיות באמצעות קריאה ל-Java ובמדיניות בנושא קריאות ל-Java.

Python

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

הסברים על סקריפטים (Java, ‏ JavaScript, ‏ Python)

  • משתמשים ב-try/catch גלובלי או באפשרות דומה.
  • אפשר להפעיל חריגות בעלות משמעות ולתעד אותן בצורה נכונה לשימוש בתגובות לשגיאות.
  • כדאי להקפיץ חריגות ולתת להן מענה מוקדם. אין להשתמש ב-try/catch הגלובלי כדי לטפל בכל החריגות.
  • לבצע בדיקות של null ו-undefined לפי הצורך. דוגמה למקרה שבו כדאי לעשות זאת היא אחזור של משתני תהליך אופציונליים.
  • הימנעו משימוש בבקשות HTTP/S בתוך קריאה להפעלת סקריפט. במקום זאת, מומלץ להשתמש במדיניות של Apigee ל-ServiceCallout, כי המדיניות מטפלת בחיבורים בצורה חלקה.

JavaScript

  • JavaScript בפלטפורמת ה-API תומכת ב-XML דרך E4X.

מודל אובייקטים של JavaScript

Java

  • כשאתם ניגשים לעומסי העבודה של ההודעות, נסו להשתמש ב-context.getMessage() במקום ב-context.getResponseMessage או ב-context.getRequestMessage. כך אפשר לוודא שהקוד יוכל לאחזר את עומס העבודה, גם בתהליך הבקשה וגם בתהליך התגובה.
  • מייבאים ספריות לארגון או לסביבה של Apigee Edge ולא כוללים אותן בקובץ ה-JAR. כך מקטינים את גודל החבילה ומאפשרים לקובצי JAR אחרים לגשת לאותו מאגר ספריות.
  • מייבאים קובצי JAR באמצעות ממשק ה-API של המשאבים ב-Apigee, במקום לכלול אותם בתיקיית המשאבים של שרת ה-proxy של ה-API. כך תוכלו לקצר את זמני הפריסה ולאפשר ליותר שרתי proxy של API להפנות לאותו קובץ JAR. יתרון נוסף הוא בידוד של מעמיס הכיתות.
  • אין להשתמש ב-Java לטיפול במשאבים (לדוגמה, יצירה וניהול של מאגרי חוטים).

המרת התשובה לאותיות רישיות באמצעות קריאה ל-Java

Python

  • השלכת חריגות בעלות משמעות ותפיסה שלהן בצורה נכונה לשימוש בתגובות לשגיאות ב-Apigee

המדיניות בנושא סקריפטים של Python

ServiceCallouts

  • יש הרבה תרחישים לדוגמה שבהם כדאי להשתמש בשרשרת proxy, שבהם משתמשים בקריאה לשירות ב-proxy API אחד כדי לבצע קריאה ל-proxy API אחר. אם אתם משתמשים בשרשרת שרתי proxy, חשוב להימנע מקריאות חזרה רפלקסיביות לאותו שרת proxy ל-API, כדי לא ליצור לולאה אינסופית.

    אם אתם מתחברים בין שרתים proxy שנמצאים באותה ארגון ובאותה סביבה, כדאי לקרוא את המאמר שרתי proxy של API בשרשור כדי לקבל מידע נוסף על הטמעת חיבור מקומי שימנע עומס יתר מיותר ברשת.

  • יוצרים הודעת בקשה של ServiceCallout באמצעות המדיניות AssignMessage, ומאכלסים את אובייקט הבקשה במשתנה של הודעה. (הפעולה הזו כוללת הגדרה של המטען הייעודי (payload), הנתיב והשיטה של הבקשה).
  • כתובת ה-URL שמוגדרת במדיניות מחייבת את הגדרת הפרוטוקול, כלומר אי אפשר לציין את החלק של הפרוטוקול בכתובת ה-URL, למשל https://, באמצעות משתנה. בנוסף, צריך להשתמש במשתנים נפרדים לחלק של הדומיין בכתובת ה-URL ולשאר כתובת ה-URL. לדוגמה: https://{domain}/{path}
  • שומרים את אובייקט התגובה של ServiceCallout במשתנה הודעה נפרד. לאחר מכן תוכלו לנתח את משתנה ההודעה ולשמור את עומס העבודה המקורי של ההודעה לשימוש במדיניות אחרת.

המדיניות בנושא קריאות תמיכה

גישה לישויות

מדיניות AccessEntity

  • כדי לשפר את הביצועים, מומלץ לחפש אפליקציות לפי uuid במקום לפי שם האפליקציה.

מדיניות של ישות גישה

רישום ביומן

  • שימוש במדיניות syslog משותפת בחבילות ובתוך אותה חבילה. כך תוכלו לשמור על פורמט עקבי של הרישום ביומן.

המדיניות בנושא רישום הודעות ביומן

מעקב

לקוחות Cloud לא צריכים לבדוק רכיבים ספציפיים של Apigee Edge (נתבים, מעבדי הודעות וכו'). צוות התפעול הגלובלי של Apigee עוקב בקפידה אחרי כל הרכיבים, יחד עם בדיקות תקינות של ממשקי API, בהתאם לבקשות של הלקוחות לבדיקות תקינות.

Apigee Analytics

מערכת Analytics יכולה לספק מעקב אחר API לא קריטי, כי היא מודדת את אחוז השגיאות.

מרכזי בקרה של Analytics

מעקב

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

שימוש בכלי המעקב

אבטחה