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

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

אפשר לעיין במסמכי העזרה של Apigee Edge.

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

מכיוון שהתוצאה היא חבילת proxy ל-API רגילה של Apigee, proxy ל-API שיוצרים בדרך הזו פועל באותה סביבת זמן ריצה של Apigee, עם אותן מדיניות והתנהגות כמו proxy ל-API שיוצרים בממשק המשתמש של 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 הפרוקסי שנפתר באופן מלא שה-CLI יוצר כשמבצעים קומפילציה של תבנית עם התכונות שלה. בדרך כלל, קובץ proxy הוא פלט ביניים שנוצר על ידי CLI, אבל אפשר גם לייבא קובץ proxy ישירות כדי לתרגם אותו לחבילת proxy ל-API.

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

איך זה עובד

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

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

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

YAML template + feature files
  |  gcloud 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.

השלבים הבאים