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

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

במסמך הזה מפורטות שיטות מומלצות לפיתוח של proxy ל-API באמצעות Apigee.

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

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

תקני פיתוח

תגובות ומסמכים

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

כתיבת קוד בסגנון Framework

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

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

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

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

פיתוח של proxy ל-API

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

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

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

• כדי לקבל הנחיות לעיצוב API ל-REST, אפשר להוריד את הספר הדיגיטלי Web API Design: The Missing Link.
• כדי ליצור שרתי proxy ל-API, כדאי להשתמש במדיניות ובפונקציונליות של Apigee בכל מקום שאפשר. אל תקודו את כל הלוגיקה של ה-proxy במשאבי JavaScript,‏ Java או Python.
• מומלץ ליצור את תהליכי העבודה בצורה מסודרת. עדיף ליצור כמה תהליכי עבודה, שלכל אחד מהם יש תנאי אחד, במקום ליצור כמה קבצים מצורפים מותנים לאותו PreFlow ול-Postflow.
• כדי ליצור 'מנגנון למקרה של כשל', יוצרים שרת proxy ל-API כברירת מחדל עם BasePath של ProxyEndpoint ‏/. אפשר להשתמש בזה כדי להפנות בקשות API בסיסיות לאתר של מפתח, כדי להחזיר תגובה מותאמת אישית או כדי לבצע פעולה אחרת שימושית יותר מאשר החזרת messaging.adaptors.http.flow.ApplicationNotFound שמוגדר כברירת מחדל.
• כדי להשיג ביצועים אופטימליים, Apigee ממליצה להשתמש בלא יותר מ-3,000 נתיבי בסיס של שרתי proxy ל-API לכל סביבת Apigee או קבוצת סביבות. חריגה מההמלצה הזו עלולה להוביל לזמן אחזור מוגבר בכל הפריסות החדשות והקיימות של proxy ל-API.
• שימוש במשאבי TargetServer כדי להפריד בין הגדרות TargetEndpoint לבין כתובות URL קונקרטיות, לתמיכה בקידום בסביבות שונות.
  אפשר לעיין במאמר בנושא איזון עומסים בין שרתים עורפיים.
• אם יש לכם כמה RouteRule, צריך ליצור אחד כברירת מחדל, כלומר כ-RouteRule ללא תנאי. חשוב לוודא ש-RouteRule ברירת המחדל מוגדר אחרון ברשימת המסלולים המותנים. המערכת בודקת את ה-RouteRule מלמעלה למטה ב-ProxyEndpoint. אפשר לעיין בהפניה להגדרת proxy ל-API.
• גודל חבילת proxy ל-API: הגודל של חבילות proxy ל-API לא יכול להיות גדול מ-15MB.
• ניהול גרסאות API: כדי לקרוא על ההמלצות של Apigee בנושא ניהול גרסאות API, אפשר לעיין במאמר Versioning בספר הדיגיטלי Web API Design: The Missing Link.

הפעלת CORS

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

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

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

הערה: רוב הדפדפנים תומכים ב-CORS. כאן אפשר למצוא רשימה מלאה של הדפדפנים הנתמכים. תיאור מפורט של CORS זמין בהמלצה של W3C בנושא שיתוף משאבים בין מקורות.

אם אתם משתמשים במדיניות בנושא מטמוןב-proxy ל-API, אתם צריכים לוודא שהתגובה של מדיניות ה-CORS לא נשמרת במטמון.

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

גודל המטען הייעודי (payload) של ההודעה בתהליכי בקשה או תגובה ב-Apigee מוגבל כברירת מחדל ל-10MB. משתמשים שצריכים לעבד מטען ייעודי (payload) גדול יכולים להגדיר מגבלה גבוהה יותר באמצעות הרכיב <Properties> בהגדרות של ProxyEndpoint או TargetEndpoint של שרתי ה-API שלהם.

מידע נוסף על שימוש במאפיינים response.payload.parse.limit או request.payload.parse.limit כדי להגדיר גודל מטען ייעודי מרבי של עד 30MB לזרימות של בקשות או תגובות זמין במאמר בנושא הפניה להגדרת proxy ל-API.

שימו לב: חריגה מגודל ההודעה שצוין תוביל לשגיאה protocol.http.TooBigBody.

כדאי לשקול את האסטרטגיות המומלצות הבאות לטיפול בגדלים גדולים של הודעות ב-Apigee:

• מומלץ מאוד לבודד שרתי proxy של API שמטפלים לעיתים קרובות במטענים גדולים בסביבה ייעודית כדי להימנע מתרחיש פוטנציאלי של "שכן רועש". פרוקסי שמנהלים מטענים ייעודיים (payload) גדולים צורכים כמויות גדולות יותר של משאבי CPU וזיכרון במערכת, במיוחד כשמשתמשים בהם בשילוב עם כללים שפועלים עם מטענים ייעודיים גדולים.
• מומלץ גם להגביל את השימוש במדיניות לאינטראקציה עם נתוני payload גדולים. שימוש במדיניות כדי לנתח ולהעתיק שוב ושוב נתוני payload של בקשות או תגובות עלול לפגוע בביצועי המערכת.
• ארגונים שמטפלים בנפחים גדולים של בקשות עם מטען ייעודי גדול מוזמנים לספק כתובות IP נוספות כדי למנוע את התופעה של מיצוי יציאות בגלל שינוי גודל אופקי.
• מומלץ לשקול הזרמה של בקשות ותגובות. הערה: כשמבצעים סטרימינג, למדיניות כבר אין גישה לתוכן ההודעות. איך שולחים בקשות ומקבלים תשובות בסטרימינג
• אם הארגון שלכם משתמש בתשלום לפי שימוש, מומלץ להשתמש במגבלות שניתנות להגדרה עבור מטען ייעודי גדול רק עבור שרתי proxy של API שנפרסו בסביבה מקיפה.

טיפול בתקלות

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

מידע נוסף על טיפול בתקלות

התמדה

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

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

מדיניות בנושא פעולות ב-KeyValueMap

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

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

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

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

מדיניות ResponseCache

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

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

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

JavaScript

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

Java

אזהרה: במדיניות JavaCallout, אין תמיכה בהסתמכות על ספריות Java שכלולות ב-Apigee. הספריות האלה מיועדות רק לפונקציונליות של מוצר Apigee, ואין ערובה לכך שספרייה מסוימת תהיה זמינה מגרסה לגרסה.

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

מידע על שימוש ב-Java ב-API proxy זמין במאמר JavaCallout policy.

Python

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

קריאות לסקריפט (Java, ‏ JavaScript, ‏ Python)

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

JavaScript

• ‫JavaScript בפלטפורמת ה-API תומך ב-XML באמצעות E4X.

מידע נוסף מופיע במאמר בנושא מודל אובייקטים של JavaScript.

Java

אזהרה: במדיניות JavaCallout, אין תמיכה בהסתמכות על ספריות Java שכלולות ב-Apigee. הספריות האלה מיועדות רק לפונקציונליות של מוצר Apigee, ואין ערובה לכך שספרייה תהיה זמינה מגרסה לגרסה.

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

Python

• העלאת חריגים משמעותיים וטיפול בהם בצורה נכונה לשימוש בתגובות של Apigee fault

מדיניות PythonScript

ServiceCallouts

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

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

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

מדיניות בנושא ServiceCallout

גישה לישויות

מדיניות AccessEntity

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

מידע נוסף על מדיניות AccessEntity

רישום ביומן

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

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

מעקב

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

Apigee Analytics

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

מרכזי בקרה ב-Analytics

ניפוי באגים

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

איך משתמשים בכלי לניפוי באגים

אבטחה

• כדי להגביל את הגישה לסביבת הבדיקה, משתמשים במדיניות הגבלת כתובות IP. מאפשרים גישה לכתובות ה-IP של מכונות או סביבות הפיתוח, ומונעים גישה מכל כתובת אחרת. מידע נוסף זמין במאמר בנושא מדיניות AccessControl.
• תמיד צריך להחיל מדיניות להגנה על תוכן (JSON או XML) על שרתי proxy של API שנפרסו בסביבת ייצור. ראו מדיניות JSONThreatProtection.
• בנושאים הבאים מפורטות עוד שיטות מומלצות לשיפור האבטחה:
  • מדיניות XMLThreatProtection
  • מדיניות RegularExpressionProtection
  • מדיניות SOAPMessageValidation

לוגיקה מותאמת אישית בממשקי proxy ל-API

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

‫Apigee מספק למפתחים כמה אפשרויות להתמודדות עם לוגיקה מותאמת אישית כזו. במסמך הזה נסביר על האפשרויות האלה ומתי כדאי להשתמש בכל אחת מהן:

מדיניות	תרחישים לדוגמה לשימוש במדיניות
‫JavaScript ו-PythonScript	מתי כדאי להשתמש במאפיין הזה: היכולות של מדיניות JavaScript זהות לאלה של מדיניות PythonScript. ההיכרות של המפתח עם שפה מסוימת היא בדרך כלל הסיבה לבחירה בה על פני שפה אחרת. הכללים של JavaScript ו-PythonScript מתאימים ביותר לעיבוד לוגיקה מוטמעת שלא מורכבת מדי ולא דורשת שימוש בספריות של צד שלישי. הביצועים של המדיניות הזו לא טובים כמו הביצועים של מדיניות JavaCallout. מתי לא מומלץ להשתמש במודעות מהסוג הזה: שער ה-API של Apigee הוא לא שרת אפליקציות (וגם לא מספק את זמן הריצה המלא של JavaScript כמו node.js). אם העיבוד של ה-callout תמיד נמשך יותר משנייה, סביר להניח שהלוגיקה לא שייכת לשער וצריכה להיות חלק מהשירות הבסיסי. שיטה מומלצת: ב-Apigee מומלץ להשתמש ב-JavaScript במקום ב-PythonScript, כי הביצועים של JavaScript טובים יותר.
JavaCallout	מתי כדאי להשתמש במאפיין הזה: חשוב מאוד שהביצועים של עיבוד הלוגיקה בשורה יהיו טובים. רוב הלוגיקה מסופקת על ידי ספריות Java קיימות. מתי לא מומלץ להשתמש במודעות מהסוג הזה: שער ה-API של Apigee הוא לא שרת אפליקציות, והוא לא מיועד לטעינת מסגרות כמו Spring, ‏ JEE וכו'. אם בדרך כלל לוקח יותר משנייה לעבד את ה-callout, אפשר להניח שהלוגיקה היא פונקציונלית (לוגיקה עסקית). כדאי לשקול להשתמש בשירות חיצוני. כדי להגן על שער ה-API של Apigee מפני שימוש לרעה, יש הגבלות על סוג הקוד שאפשר להריץ. לדוגמה, קוד Java שמנסה לגשת לספריות קריפטו מסוימות או לגשת למערכת הקבצים נחסם מהרצה. אפליקציות Java, במיוחד כאלה שמסתמכות על ספריות של צד שלישי, יכולות להכיל הרבה קובצי JAR (גדולים). הפעולות האלה עלולות להאט את זמן האתחול של השערים.
ExternalCallout	מתי כדאי להשתמש במאפיין הזה: הכי מתאים להוצאת לוגיקה מותאמת אישית ולאפשר ללוגיקה המותאמת אישית לגשת להקשר של ההודעה (ולשנות אותו אם צריך). התכונה External callouts (הפעלת קריאות חיצוניות) מבוססת על gRPC, והביצועים שלה עשויים להיות טובים יותר מאלה של ServiceCallout. כשמשתמשים ב-Apigee או ב-Apigee Hybrid ב-Google Cloud, כדאי להשתמש ב-Cloud Functions או ב-Cloud Run כדי לארח את הלוגיקה הזו. כחלופה יעילה לתכונה Hosted Targets ב-Apigee Edge. מתי לא מומלץ להשתמש: ללוגיקה פשוטה שאפשר להריץ במהירות, בשורה.
ServiceCallout	מתי כדאי להשתמש במאפיין הזה: עדיף להטמיע לוגיקה מורכבת מחוץ לשער. ללוגיקה הזו יכול להיות מחזור חיים משלה (גרסאות ומהדורות), והיא לא משפיעה על הפעולה של שער הכניסה. כשנקודת הקצה של REST/SOAP/GraphQL כבר קיימת או שאפשר להטמיע אותה בקלות כשמשתמשים ב-Apigee או ב-Apigee Hybrid ב-Google Cloud, כדאי להשתמש ב-Cloud Functions או ב-Cloud Run כדי לארח את הלוגיקה הזו. כחלופה יעילה לתכונה Hosted Targets ב-Apigee Edge. מתי לא מומלץ להשתמש: ללוגיקה פשוטה שאפשר להריץ במהירות, בשורה proxy ל-API צריך להעביר הקשר (כמו משתנים) או לקבל הקשר מההטמעה החיצונית

לסיכום:

1. אם הלוגיקה פשוטה או טריוויאלית, כדאי להשתמש ב-JavaScript (עדיף) או ב-PythonScript.
2. אם הלוגיקה של רכיב ה-inline דורשת ביצועים טובים יותר מ-JavaScript או מ-PythonScript, צריך להשתמש ב-JavaCallout.
3. אם הלוגיקה צריכה להיות חיצונית, צריך להשתמש ב-ExternalCallout.
4. אם כבר יש לכם הטמעות חיצוניות או שהמפתחים מכירים את REST, כדאי להשתמש ב-ServiceCallout.

האיור הבא ממחיש את התהליך הזה: