הגדרת שרת proxy באמצעות YAML

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

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

אתם יכולים להגדיר proxy ל-API של Apigee ב-YAML ולפרוס אותו באמצעות Google Cloud CLI, כחלופה ליצירת חבילת proxy מסורתית ב-XML. אתם מתארים את נקודות הקצה, המסלולים, כללי המדיניות ויעדי ה-Backend של שרת proxy בקובצי YAML שנקראים Apigee Feature Templates, ו-Apigee מהדרת אותם לחבילת שרת proxy רגילה ל-API.

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

למה כדאי להשתמש ב-YAML כדי להגדיר שרתי proxy

הפורמט המסורתי של proxy ל-API ב-Apigee הוא ארכיון ZIP של קובצי XML. ‫YAML מציעה חלופה שרבים מהמפתחים חושבים שהיא מהירה יותר לקריאה, לכתיבה ולבדיקה, והיא פועלת היטב עם כלים מבוססי-AI וכלים אוטונומיים. תבניות התכונות של Apigee נועדו לספק:

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

מושגים מרכזיים

תבניות התכונות של Apigee משתמשות בשלושה סוגי מסמכים. כל אחד מהם הוא קובץ YAML שמזוהה על ידי השדה type שלו.

סוג המסמך ערך של type מטרה
תבנית template נקודת הכניסה שאתם פורסים. תבנית מורכבת מתכונה אחת או יותר ומגדירה את נקודות הקצה והנתיבים של ה-proxy.
תכונה feature יחידת הגדרה לשימוש חוזר – כמו בדיקת אימות, הגבלת קצב או יעד בקצה העורפי – שכוללים בתבנית. התכונות כוללות את המדיניות והמשאבים.
בשם אחרים proxy ה-proxy שנפתר באופן מלא שנוצר על ידי ה-CLI כשמבצעים קומפילציה של תבנית עם התכונות שלה. בדרך כלל, קובץ proxy הוא פלט ביניים שנוצר על ידי CLI, אבל אפשר גם לייבא קובץ proxy ישירות כדי לתרגם אותו לחבילת proxy של API.

אתם יוצרים תבניות ותכונות. ‫Apigee יוצר בשבילכם את ה-proxy במהלך ההידור.

איך זה עובד

כשמייבאים תבנית, Google Cloud CLI מבצע את השלבים הבאים באופן מקומי, ואז מעלה את התוצאה ל-Apigee:

  1. לקמפל. ה-CLI קורא את התבנית ואת קובצי התכונות שהיא מפנה אליהם, ממזג אותם ויוצר הגדרת proxy אחת.
  2. להמיר. ה-CLI ממיר את הגדרת ה-proxy לחבילת שרת proxy רגילה של Apigee API (קובץ ה-ZIP של קובצי ה-XML ש-Apigee מצפה להם).
  3. ייבוא. ממשק ה-CLI מעלה את החבילה ל-Apigee, והמערכת יוצרת גרסה חדשה של proxy ל-API.

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

YAML template + feature files
  |  gcloud beta apigee apis import --from-template
  v
API proxy revision   (created, not yet serving traffic)
  |  gcloud apigee apis deploy
  v
Deployed proxy       (serving traffic in an environment)

הוראות מפורטות מופיעות במאמר בנושא יצירת proxy ל-API מתבנית YAML.

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

התבנית הבאה מגדירה proxy שכולל שתי תכונות – אחת שמוסיפה יעד backend ואחת שמוסיפה הודעת תגובה:

gateway: apigee
schemaVersion: 1.0.0
name: HelloWorld-v1
type: template
description: API proxy for HelloWorld-v1
features:
- proxy-apigeemock.yaml
- response-helloworld.yaml

כל קובץ תכונות שמתבצעת אליו הפניה צריך להיות באותה ספרייה שבה נמצאת התבנית. דוגמה מלאה שאפשר להפעיל וקבצי התכונות שבה מופיעים במאמר יצירת שרת proxy של API מתבנית YAML.

מה אפשר לעשות

  • הגדרת נקודות קצה, נתיבי בסיס, מסלולים, זרימות ויעדי קצה עורפי של שרת proxy ב-YAML.
  • אפשר לארוז משאבים ומדיניות לשימוש חוזר כפיצ'רים, ולשלב אותם בתבנית.
  • הוספת אימות בקצה העורפי ליעדים ב-Google Cloud (לדוגמה, אסימון גישה של Google עבור קצה עורפי של Vertex AI).
  • מייבאים תבנית כעדכון חדש של שרת proxy ל-API באמצעות Google Cloud CLI, ואז פורסים אותה באמצעות פקודת הפריסה הרגילה.

מגבלות

כשיוצרים תבניות ותכונות, חשוב לזכור את הדברים הבאים:

  • התכונות הן קבצים מקומיים. תבנית יכולה להפנות רק לקבצים של תכונות שנמצאים באותה ספרייה. אין תמיכה בהפניה לתכונות באמצעות כתובת URL או מקטלוג משותף.
  • ערכי הפרמטרים משתמשים בערכי ברירת המחדל שלהם. תכונות יכולות להגדיר פרמטרים, אבל ערכי הפרמטרים מוגדרים כברירת המחדל שהוגדרה בתכונה. אין דגל בשורת הפקודה שאפשר להשתמש בו כדי לבטל את הערכים של הפרמטרים בזמן הייבוא.
  • אין תמיכה בפרמטרים של JSONPath. פרמטר שמשתמש בביטוי paths (JSONPath) גורם לכשל בהידור.
  • אין תמיכה בבדיקות. קטע tests מתקבל על ידי הסכימה, אבל המערכת מתעלמת ממנו והוא לא נכלל בחבילה שנוצרת.
  • הסכימה מחמירה. שדות לא ידועים גורמים לשגיאה. יש תמיכה רק בערכים gateway: apigee ו-schemaVersion: 1.0.0.
  • פתרון בעיות מתבצע באמצעות קובץ ה-XML שנוצר. ממשק המשתמש של Apigee וזמן הריצה פועלים עם חבילת ה-bundle שנוצרה. בממשק המשתמש אין אפשרות לחזור למקור ה-YAML.

השלבים הבאים