הפניית הגדרות YAML של שרת proxy ל-API

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

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

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

מוסכמות

  • שמות השדות כתובים ב-camelCase. לדוגמה, schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • הסכימה מחמירה. שדות לא ידועים גורמים לשגיאה כשמייבאים את הקובץ.
  • שדות חובה. רק gateway ו-schemaVersion מאומתים כשקובץ מנותח. בפועל, צריך למלא גם את השדות האחרים שמסומנים ב-כן בטבלאות הבאות כדי ליצור proxy ל-API שפועל.

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

כל מסמך של template,‏ feature ו-proxy מתחיל בשדות הבאים.

שם תיאור ברירת מחדל חובה?
gateway שער היעד. חייב להיות apigee. לא רלוונטי כן
schemaVersion גרסת הסכימה של המסמך. חייב להיות 1.0.0. לא רלוונטי כן
name שם המסמך. בתבנית או בשרת proxy, זהו שם ה-proxy ל-API שכתוב בחבילה. לא רלוונטי כן
type סוג המסמך: template, feature או proxy. לא רלוונטי כן
description תיאור קריא לאנשים. לא רלוונטי לא
priority מספר שלם שקובע את הסדר שבו התכונות מופעלות במהלך ההידור. המספרים הנמוכים יותר מוחלים קודם. 100 לא

סוג המסמך: תבנית

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

שם תיאור ברירת מחדל חובה?
features רשימה של קובצי תכונות שצריך להרכיב בשרת ה-Proxy. כל רשומה היא נתיב לקובץ תכונה, ביחס לספרייה שמכילה את התבנית (לדוגמה, ./features/spike-arrest.yaml). [] לא
parameters רשימה של פרמטרים שמגדירים ערכים לפרמטרים של התכונות. הערך של default ברשומה מבטל את הערך של default בפרמטר התכונה עם אותו name. ראו פרמטר. [] לא
endpoints רשימה של נקודות קצה (endpoints) שמגדירות נתיבי בסיס ומסלולים. [] לא
targets רשימה של יעדים שמגדירים חיבורים לקצה העורפי. [] לא

סוג המסמך: תכונה

תכונה היא יחידת הגדרה שאפשר להשתמש בה שוב ושוב, וכוללים אותה בתבנית. תכונה מכילה כללי מדיניות ומשאבים, ויכולה לתרום תהליכים, נקודות קצה (endpoints) ויעדים לשרת ה-proxy שעבר הידור. בנוסף לשדות הנפוצים ברמה העליונה, ישות כוללת את השדות הבאים.

שם תיאור ברירת מחדל חובה?
displayName שם לתצוגה שקריא לאנשים. לא רלוונטי לא
uid מזהה ייחודי שמפריד בין כללי המדיניות והמשאבים של התכונה, אם התבנית כוללת את התכונה יותר מפעם אחת. אם הפיצ'ר מגדיר uid, ה-CLI מוסיף את הקידומת UID- לכל אחד משמות המדיניות והמשאבים שלו ומעדכן את ההפניות אליהם. אם לא מוגדר uid לתכונה, ה-CLI משתמש בשמות כפי שהם כתובים. לא רלוונטי לא
documentation מסמכי תיעוד מורחבים על התכונה. לא רלוונטי לא
categories רשימה של תוויות קטגוריה בפריסה גמישה. [] לא
parameters רשימה של פרמטרים שהתכונה מגדירה. [] לא
defaultEndpoint נקודת קצה של שרת proxy שהתהליכים וכלל ברירת המחדל שלה לטיפול בשגיאות מוזגו לכל נקודת קצה של שרת ה-proxy שעבר הידור. אפשר להשתמש בזה כדי לצרף את כללי המדיניות של תכונה מסוימת לתהליך הבקשה או התגובה. לא רלוונטי לא
defaultTarget יעד proxy שמשמש כחיבור ברירת מחדל לקצה העורפי. לא רלוונטי לא
endpoints רשימה של נקודות קצה (endpoints) של שרת proxy להוספה לשרת ה-proxy. נקודת קצה עם שם זהה לנקודת קצה קיימת מחליפה אותה. [] לא
targets רשימה של יעדי שרת proxy להוספה לשרת ה-proxy. יעד עם שם זהה ליעד קיים מחליף אותו. [] לא
policies רשימה של כללי מדיניות שהתכונה מספקת. אם התכונה מגדירה uid, ה-CLI מוסיף לכל שם מדיניות את הקידומת UID- במהלך ההידור, לדוגמה sa1-SA-SpikeArrest. אחרת, ה-CLI משתמש בשמות המדיניות כפי שהם כתובים. [] לא
resources רשימה של משאבים שהתכונה מספקת, כמו קובצי JavaScript או קובצי מאפיינים. [] לא

סוג המסמך: ייפוי כוח

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

לשרת proxy יש את אותם שדות כמו לתכונה, אבל הוא משתמש ב-endpoints וב-targets (ולא ב-defaultEndpoint או ב-defaultTarget) ותמיד מייצג שרת proxy מלא שאפשר לפרוס. הערך של type הוא proxy.

אובייקטים מוטמעים

פרמטר

פרמטר מספק ערך לתכונה. התכונה מצהירה על הפרמטרים שלה, והתבנית יכולה להגדיר את הערכים שלהם ברשימת parameters משלה. כשה-CLI מקמפל תבנית, הוא פותר כל פרמטר של תכונה באופן הבא:

  1. אם ברשימה parameters של התבנית יש רשומה שבה הערך של name תואם והערך של default לא ריק, ה-CLI משתמש בערך הזה. אם התכונה מגדירה uid, שם הרשומה בתבנית חייב להיות FEATURE_NAME.UID.PARAMETER_NAME.
  2. אחרת, ה-CLI משתמש ב-default של פרמטר התכונה.
  3. אם אף אחד מהם לא מגדיר ערך, הפרמטר יקבל ערך של מחרוזת ריקה. לא מופיעה שגיאה ב-CLI.

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

שם תיאור ברירת מחדל חובה?
name שם הפרמטר. מופיע בתוכן המומלץ בתור {name}. לא רלוונטי כן
displayName שם קריא לאנשים. לא רלוונטי לא
description תיאור של הפרמטר. לא רלוונטי לא
default בתכונה, הערך שמשמש כשלא מוגדר ערך בתבנית. בתבנית, הערך של פרמטר התכונה עם אותו שם. ה-CLI מתעלם מערך ריק. ה-CLI מחליף את הערך שנקבע במקום {name} במחרוזות של התכונה. לא רלוונטי לא
examples רשימה של ערכים לדוגמה. [] לא
maps מפה של החלפות ערכים. אם הערך שנקבע הוא מפתח במפה, הוא יוחלף בערך הממופה. לא רלוונטי לא
paths רשימה של ביטויי JSONPath. לא נתמך בגרסה הזו – השימוש בו גורם לשגיאה. לא רלוונטי לא

endpoint

בשימוש ברשימת endpoints של תבנית.

שם תיאור ברירת מחדל חובה?
name שם נקודת הקצה. לא רלוונטי כן
basePath נתיב הבסיס שבו הלקוחות משתמשים כדי לקרוא לשרת ה-proxy, לדוגמה /v1/gemini. לא רלוונטי לא
routes רשימה של מסלולים שממפים בקשות ליעדים. [] לא

proxyEndpoint

הוא משמש ב-defaultEndpoint וב-endpoints של תכונה, ובשרת proxy שעבר הידור. הרחבה של נקודת הקצה (endpoint) עם טיפול בתהליך.

שם תיאור ברירת מחדל חובה?
flows רשימה של תהליכים. תהליכים בשם PreFlow או PostFlow ממופים לתהליך התואם ב-Apigee. כל שם אחר ממוקם במאגר התהליכים הגנריים. [] לא
postClientFlow תהליך אחד שפועל אחרי שהתשובה נשלחת ללקוח. לא רלוונטי לא
faultRules רשימה של תהליכים שמשמשים ככללי שגיאה. [] לא
defaultFaultRule כלל שגיאה שפועל כשאין כלל שגיאה אחר שתואם. לא רלוונטי לא

נתיב

שם תיאור ברירת מחדל חובה?
name שם המסלול. לא רלוונטי כן
target שם נקודת הקצה (endpoint) שאליה רוצים לנתב. לא רלוונטי לא
condition תנאי שחייב להתקיים כדי שהנתיב הזה יחול. לא רלוונטי לא

רצף פעולות

שם תיאור ברירת מחדל חובה?
name שם התהליך. משתמשים ב-PreFlow או ב-PostFlow לתהליכים הרגילים של בקשה/תגובה. לא רלוונטי כן
mode ‫Request או Response. קובע אם השלבים יופעלו על הבקשה או על התגובה. Request לא
condition תנאי שחייב להתקיים כדי שהתהליך יפעל. לא רלוונטי לא
steps רשימה מסודרת של שלבים (הפעלות של מדיניות). [] לא

שלב

שלב מפעיל מדיניות בתוך תהליך.

שם תיאור ברירת מחדל חובה?
name שם המדיניות שרוצים להפעיל. בתוך תכונה, משתמשים בשם המקומי של המדיניות. המקמפל משכתב אותו לשם ממרחב השמות. לא רלוונטי כן
condition תנאי שחייב להתקיים כדי שהשלב יופעל. לא רלוונטי לא

faultRule

מרחיב את התהליך בשדה אחד נוסף.

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

שם תיאור ברירת מחדל חובה?
alwaysEnforce אם true, כלל ברירת המחדל תמיד נאכף. false לא

target

בשימוש ברשימת targets של תבנית.

שם תיאור ברירת מחדל חובה?
name שם היעד. הפניה על ידי target של מסלול. לא רלוונטי כן
url כתובת ה-URL של הקצה העורפי. לא רלוונטי לא
auth סכימת האימות של קצה העורפי של Google Cloud, לדוגמה GoogleAccessToken או GoogleIDToken. לא רלוונטי לא
scopes רשימה של היקפי הרשאות OAuth שצריך לבקש. רלוונטי כשמוגדרת המדיניות auth. [] לא
aud הקהל שאמור להשתמש באסימון. רלוונטי כשמוגדרת המדיניות auth. לא רלוונטי לא

proxyTarget

משמש ב-defaultTarget וב-targets של תכונה, ובשרת proxy שעבר הידור. מרחיב את target עם טיפול בזרימה ושינויים של חיבור גולמי.

שם תיאור ברירת מחדל חובה?
flows רשימה של תהליכים שפועלים בבקשה או בתגובה של היעד. [] לא
faultRules רשימה של תהליכים שמשמשים ככללי שגיאה. [] לא
defaultFaultRule כלל שגיאה. לא רלוונטי לא
httpTargetConnection ייצוג גולמי של הרכיב HTTPTargetConnection, להגדרה מתקדמת. אם המדיניות מוגדרת, היא מקבלת עדיפות על פני המדיניות url, auth, scopes ו-aud. לא רלוונטי לא
localTargetConnection ייצוג גולמי של רכיב LocalTargetConnection. אם המדיניות מוגדרת, היא מקבלת עדיפות על פני חיבור HTTP. לא רלוונטי לא

policy

המדיניות מוגדרת בתכונה. ההגדרה שלו כתובה בקטע content באמצעות מוסכמת המאפיין/הטקסט שמתוארת במוסכמת תוכן המדיניות.

שם תיאור ברירת מחדל חובה?
name שם המדיניות. לא רלוונטי כן
type סוג המדיניות של Apigee, לדוגמה VerifyAPIKey, SpikeArrest או Javascript. חייב להתאים למפתח היחיד ברמה העליונה ב-content. לא רלוונטי כן
content מילון עם מפתח אחד ששווה ל-type. הערך המוטמע מתאר את ה-XML של המדיניות לפי המוסכמה שבהמשך. {} כן

מוסכמות לגבי תוכן המדיניות

כללי המדיניות של Apigee הם קובצי XML. ב-YAML, מייצגים את ה-XML הזה ב-content באמצעות הכללים הבאים:

  • במילון content יש בדיוק מפתח אחד, שחייב להתאים ל-type של המדיניות.
  • מאפייני רכיבים מופיעים מתחת למפתח metadata.
  • טקסט של רכיב מופיע מתחת למפתח _text. לדוגמה, <Foo bar="baz">qux</Foo> הופך ל-Foo: {metadata: {bar: "baz"}, _text: "qux"}. אם לאלמנט יש רק טקסט ואין לו מאפיינים, אפשר לכתוב את הטקסט ישירות כערך.
  • רכיבי צאצא מוטמעים מתחת לשם התג שלהם. תגים שחוזרים על עצמם הופכים לרשימה.

לדוגמה, מדיניות התכונות הזו:

policies:
- name: VA-VerifyAPIKey
  type: VerifyAPIKey
  content:
    VerifyAPIKey:
      metadata:
        name: VA-VerifyAPIKey
        enabled: "true"
        continueOnError: "false"
      DisplayName: VA-VerifyAPIKey
      APIKey:
        metadata:
          ref: request.header.x-api-key

מקומפל ל-XML של המדיניות הזו:

<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey">
  <APIKey ref="request.header.x-api-key"></APIKey>
  <DisplayName>VA-VerifyAPIKey</DisplayName>
</VerifyAPIKey>

משאב

משאב הוא קובץ שתכונה מוסיפה לחבילה, כמו קובץ JavaScript או קובץ מאפיינים.

שם תיאור ברירת מחדל חובה?
name שם הקובץ, למשל hello-world.js. אם התכונה מגדירה uid, ה-CLI מוסיף לשם המשאב את הקידומת UID- במהלך הקומפילציה. אחרת, ה-CLI משתמש בשם כפי שהוא כתוב. לא רלוונטי כן
type סוג המשאב, שקובע את תת-הספרייה בחבילה, למשל jsc (JavaScript) או properties. לא רלוונטי כן
content תוכן הקובץ הגולמי. לא רלוונטי לא

שדות שלא נתמכים בגרסה הזו

  • paths בפרמטר (JSONPath). אם תשתמשו בו, הקומפילציה תיכשל.
  • tests בכל מסמך. השדה מתקבל אבל המערכת מתעלמת ממנו, והוא לא נכלל בחבילה שנוצרת.

מגבלות

חבילת ה-proxy ל-API שנוצרה לא יכולה לחרוג מ-‎10 MiB ללא דחיסה או מ-256 קבצים.

השלבים הבאים