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

לפרוקסי יש את אותם שדות כמו לתכונה, אבל הוא משתמש ב-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 תנאי שחייב להתקיים כדי שהתהליך יפעל. לא רלוונטי לא
steps רשימה מסודרת של שלבים (הפעלות של מדיניות). [] לא

שלב

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

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

faultRule

הארכה של הזרימה עם שדה נוסף אחד.

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

שם תיאור ברירת מחדל חובה?
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 בכל מסמך. השדה מתקבל אבל המערכת מתעלמת ממנו, והוא לא נכלל בחבילה שנוצרת.

מגבלות

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

השלבים הבאים