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

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

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

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

תקני פיתוח

הערות ומסמכי תיעוד

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

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

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

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

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

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

פיתוח proxy ל-API

שיקולים לעיצוב ראשוני

  • כדי לקבל הנחיות לגבי עיצוב של RESTful API, צריך להוריד את הספר האלקטרוני עיצוב ה-Web API: The missing Link.
  • השתמשו ככל האפשר במדיניות ובפונקציונליות של Apigee Edge כדי לבנות שרתי proxy ל-API. להימנע מכתיבת קוד של כל הלוגיקה של שרת ה-proxy במשאבים של JavaScript, Java או Python.
  • חשוב לבנות את תהליכי העבודה בצורה מאורגנת. יש עדיפות ליצירת כמה שלבים, שלכל אחד מהם תנאי יחיד, על פני כמה קבצים מצורפים מותנים לאותו תהליך.
  • בתור 'failsafe', יוצרים שרת proxy ל-API שמוגדר כברירת מחדל עם ProxyEndpoint BasePath של /. אפשר להשתמש בו כדי להפנות בקשות API בסיסיות לאתר מפתחים, כדי להחזיר תגובה מותאמת אישית, או כדי לבצע פעולה אחרת שמועילה יותר מהחזרת ברירת המחדל messaging.adaptors.http.flow.ApplicationNotFound.
  • אפשר להשתמש במשאבים של TargetServer כדי להפריד בין הגדרות של TargetEndpoint מכתובות URL ממשיות, וכך לתמוך בקידום מכירות בסביבות שונות.
    למידע נוסף, אפשר לקרוא את המאמר איזון עומסים בין שרתים לקצה העורפי.
  • אם יש כמה כללי RouteRules, צריך ליצור אותם בתור 'ברירת המחדל', כלומר כ-RouteRule ללא תנאי. מוודאים שברירת המחדל של RouteRule היא אחרונה ברשימת הנתיבים המותנים. הערכים של Route Rules (כללים) יופיעו מלמעלה למטה ב-ProxyEndpoint.
    אפשר לעיין במידע על הגדרת שרת proxy ל-API.
  • גודל חבילת שרת proxy ל-API: חבילות proxy ל-API לא יכולות להיות גדולות יותר מ-15MB. ב-Apigee Edge בענן פרטי, אפשר לשנות את מגבלת הגודל על-ידי שינוי המאפיין 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 בשרתי ה-API של ה-API כדי לתמוך בבקשות ממקורות שונים בצד הלקוח.

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

למידע על הפעלת CORS בשרתי ה-API של ה-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 ואילך, בקשות עם מטען ייעודי (payload) חייבות לכלול את הכותרת Content-Length, או במקרה של שידור הכותרת "Transfer-Encoding: chunked". עבור POST לשרת proxy של API עם מטען ייעודי (payload) ריק, יש להעביר ערך Content-Length של 0.
  • ב-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

טיפול בכשלים

  • שימוש ב-Fault Rules כדי לטפל בכל הבעיות. (ניתן להשתמש במדיניות של RaiseFault כדי להפסיק את תהליך שליחת ההודעות ולשלוח את העיבוד לתהליך FaultRules).
  • בתהליך של FaultRules, משתמשים במדיניות assignMessage כדי ליצור את התגובה לתיקון התקלה, ולא במדיניות של RaiseFault. הפעלה מותנית של כללי מדיניות assignMessage לפי סוג התקלה שמתרחש.
  • תמיד כוללים handler של ברירת מחדל '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 במועד מאוחר ככל האפשר. במילים אחרות, צריך להפעיל אותו אחרי שלבי התרגום והתהליך של תהליך בחירת הרשת, כולל תהליך בחירת הרשת (Mediation) שמבוסס על JavaScript והמרה בין JSON ל-XML. שמירה של נתונים בתהליך בחירת הרשת במטמון מונעת את עלות הביצועים של ביצוע השלב של תהליך בחירת הרשת בכל פעם שמאחזרים נתונים שנשמרו במטמון.

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

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

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

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

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

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

JavaScript

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

למידע נוסף, ראו שרתי proxy של API לתכנות באמצעות JavaScript.

Java

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

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

Python

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

יתרונות מרכזיים בסקריפט (Java, JavaScript, Python)

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

JavaScript

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

ראו מודל אובייקט של JavaScript.

Java

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

אפשר לעיין בקטע המרת התגובה לאותיות רישיות באמצעות יתרונות מרכזיים של Java.

Python

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

אפשר לעיין במדיניות של Python Script.

ServiceCallouts

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

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

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

למידע נוסף, ראו מדיניות בנושא יתרונות מרכזיים של שירות.

גישה לישויות

המדיניות של AccessEntity

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

למידע נוסף, ראו מדיניות הגישה לישות.

רישום ביומן

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

למידע נוסף, אפשר לקרוא את המדיניות בנושא MessageLogging.

מעקב

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

ניתוח נתונים של Apigee

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

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

נתוני מעקב

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

למידע נוסף, ראו שימוש בכלי המעקב.

אבטחה