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

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

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

תקני פיתוח

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

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

תכנות בסגנון Framework

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

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

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

  • המאפיין Policy 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

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

  • כדי לקבל הנחיות לעיצוב API ל-REST, אפשר להוריד את הספר הדיגיטלי Web API Design: The Missing Link.
  • כדי ליצור שרתי proxy ל-API, כדאי להשתמש במדיניות ובפונקציונליות של Apigee Edge בכל מקום שאפשר. אל תכתבו את כל הלוגיקה של ה-proxy במשאבי JavaScript,‏ Java או Python.
  • בניית תהליכי עבודה בצורה מאורגנת. עדיף להשתמש בכמה Flows, שלכל אחד מהם יש תנאי אחד, במקום בכמה קבצים מצורפים מותנים לאותו PreFlow ול-Postflow.
  • כדי ליצור 'מנגנון למקרה של כשל', יוצרים שרת proxy ל-API שמוגדר כברירת מחדל עם BasePath של ProxyEndpoint של /. אפשר להשתמש בזה כדי להפנות בקשות API בסיסיות לאתר של מפתח, כדי להחזיר תגובה מותאמת אישית או כדי לבצע פעולה אחרת שימושית יותר מאשר החזרת messaging.adaptors.http.flow.ApplicationNotFound שמוגדר כברירת מחדל.
  • אפשר להשתמש במשאבי TargetServer כדי להפריד בין הגדרות TargetEndpoint לבין כתובות URL קונקרטיות, וכך לתמוך בקידום מכירות בסביבות שונות.
    מידע נוסף מופיע במאמר איזון עומסים בין שרתים של בק-אנד.
  • אם יש לכם כמה RouteRules, צריך ליצור אחת כ 'ברירת מחדל', כלומר כ-RouteRule ללא תנאי. מוודאים ש-RouteRule שמוגדר כברירת מחדל מוגדר אחרון ברשימת המסלולים המותנים. הערכת הכללים של 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 Design: The Missing Link.

הפעלת CORS

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

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

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

גודל המטען הייעודי (Payload) של ההודעה

כדי למנוע בעיות בזיכרון ב-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 ל-API proxy עם מטען ייעודי (payload) ריק, צריך להעביר את הערך 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 Flow, משתמשים במדיניות AssignMessage כדי ליצור את תגובת השגיאה, ולא במדיניות RaiseFault. הפעלה מותנית של מדיניות AssignMessage על סמך סוג השגיאה שמתרחשת.
  • תמיד כולל מטפל ברירת מחדל בשגיאות מסוג catch-all, כדי שאפשר יהיה למפות שגיאות שנוצרו על ידי המערכת לפורמטים של תגובות לשגיאות שהוגדרו על ידי הלקוח.
  • אם אפשר, תמיד כדאי לוודא שהתשובות עם השגיאות תואמות לפורמטים סטנדרטיים שזמינים בחברה או בפרויקט שלכם.
  • להשתמש בהודעות שגיאה משמעותיות שאנשים יכולים לקרוא, שמציעות פתרון למצב השגיאה.

מידע נוסף זמין במאמר בנושא טיפול בתקלות.

שיטות מומלצות בתחום מפורטות במאמר תכנון תגובות שגיאה ב-RESTful.

התמדה

מפות של צמדי מפתח/ערך

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

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

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

  • לא מאכלסים את מטמון התגובות אם התגובה לא מוצלחת או אם הבקשה היא לא 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> של המדיניות.

לעיון במדיניות בנושא מטמון תשובות

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

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

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

JavaScript

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

מידע נוסף מופיע במאמר Programming API proxies with JavaScript.

Java

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

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

Python

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

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

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

JavaScript

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

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

Java

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

מידע נוסף זמין במאמר המרת התשובה לאותיות רישיות באמצעות קריאה ל-Java.

Python

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

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

ServiceCallouts

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

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

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

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

גישה לישויות

מדיניות AccessEntity

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

מידע נוסף על מדיניות של ישויות גישה

רישום ביומן

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

מדיניות MessageLogging

מעקב

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

Apigee Analytics

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

מידע נוסף על מרכזי בקרה ב-Analytics

מעקב

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

איך משתמשים בכלי המעקב

אבטחה