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

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

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

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

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

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

שם תיאור ברירת מחדל חובה?
features רשימה של שמות קבצים של תכונות שיוצרים מהם את ה-proxy. כל שם חייב להיות שם של קובץ שנמצא באותה ספרייה כמו התבנית. [] לא
parameters רשימה של ערכי פרמטרים שמספקים ערכי ברירת מחדל לתכונות. [] לא
endpoints רשימה של נקודות קצה שמגדירות נתיבי בסיס ומסלולים. [] לא
targets רשימה של יעדים שמגדירים חיבורים לשרת העורפי. [] לא

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

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

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

סוג המסמך: proxy

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

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

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

פרמטר

פרמטר מספק ערך לתכונה. הערך של פרמטר הוא default.

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

endpoint

המאפיין הזה משמש ברשימת endpoints של תבנית.

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

proxyEndpoint

המאפיינים האלה נמצאים בשימוש ב-defaultEndpoint וב-endpoints של תכונה, וגם בשרת Proxy שעבר קומפילציה. ‫Extends endpoint with flow handling.

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

מסלול

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

רצף פעולות

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

שלב

שלב מריץ מדיניות בתוך תהליך.

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

faultRule

ההרחבה flow עם שדה נוסף אחד.

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

יעד

המאפיין הזה משמש ברשימת 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 (או name) במהלך הקומפילציה. לא רלוונטי כן
type סוג המשאב, שקובע את ספריית המשנה בחבילה, למשל jsc (JavaScript) או properties. לא רלוונטי כן
content התוכן הגולמי של הקובץ. לא רלוונטי לא

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

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

מגבלות

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

השלבים הבאים