הדף הזה רלוונטי ל-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 מקמפל תבנית, הוא פותר כל פרמטר של תכונה באופן הבא:
- אם ברשימה
parametersשל התבנית יש רשומה שבה הערך שלnameתואם והערך שלdefaultלא ריק, ה-CLI משתמש בערך הזה. אם התכונה מגדירהuid, שם הרשומה בתבנית חייב להיותFEATURE_NAME.UID.PARAMETER_NAME. - אחרת, ה-CLI משתמש ב-
defaultשל פרמטר התכונה. - אם אף אחד מהם לא מגדיר ערך, הפרמטר יקבל ערך של מחרוזת ריקה. לא מופיעה שגיאה ב-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 קבצים.