מוצג התיעוד של Apigee Edge.
נכנסים למסמכי התיעוד של Apigee X. מידע
מידע על המדיניות בנושא OASValidation
המדיניות OASValidation (OpenAPI Specification Validation) מאפשרת לאמת בקשה או הודעת תגובה נכנסת מול מפרט OpenAPI 3.0 (JSON או YAML). עיינו בקטע איזה תוכן מאומת?
מדיניות OASValidation מציינת את השם של מפרט OpenAPI שיש להשתמש בו לאימות כאשר מתבצע השלב שאליו המדיניות מצורפת.
המפרט של OpenAPI מאוחסן כמשאב במיקום הסטנדרטי הבא בחבילת ה-API של שרת ה-proxy: apiproxy/resources/oas
.
מפרט OpenAPI חייב לכלול תוסף .json
, .yml
, .yaml
.
הוסף מפרט OpenAPI כמשאב לחבילת proxy של API באמצעות ממשק המשתמש או API, כפי שמתואר במאמר ניהול משאבים.
איזה תוכן מאומת?
בטבלה הבאה מוצג סיכום של התוכן של הודעת הבקשה שאומת על ידי מדיניות OASValidation, לפי רכיב.
רכיבים | בקש אימות |
---|---|
נתיב בסיס | מאמת את נתיב הבסיס שהוגדר על ידי שרת ה-proxy של ה-API. מתעלם מנתיב הבסיס שצוין במפרט OpenAPI. |
נתיב | מוודא שנתיב הבקשה (פחות נתיב הבסיס) תואם לאחת מדפוסי הנתיב המוגדרים במפרט OpenAPI. |
פועל | מוודא שהפועל מוגדר לנתיב במפרט OpenAPI. |
גוף ההודעה של הבקשה |
הערה: המדיניות מאמתת גוף של הודעת בקשה בהתאם למפרט OpenAPI רק אם סוג התוכן מוגדר לערך |
פרמטרים |
|
בטבלה הבאה מוצג סיכום של התוכן של הודעת התגובה שאומת על ידי מדיניות OASValidation, לפי רכיב.
רכיבים | אימות של תשובות |
---|---|
נתיב | מוודא שנתיב הבקשה (פחות נתיב הבסיס) תואם לאחת מדפוסי הנתיב המוגדרים במפרט OpenAPI. |
פועל | מוודא שהפועל מוגדר לנתיב במפרט OpenAPI. |
גוף הודעת התשובה |
|
דוגמאות
בדוגמאות הבאות אפשר לראות כמה מהדרכים שבהן אפשר להשתמש במדיניות OASValidation כדי לאמת הודעות מול מפרט OpenAPI 3.0.
אימות הודעת הבקשה
בדוגמה הבאה, המדיניות myoaspolicy
מאמתת את הגוף של הודעת הבקשה מול סכימת הגוף של בקשת הפעולה שהוגדרה במפרט my-spec.json
OpenAPI.
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.json</OASResource> <Options> <ValidateMessageBody>true</ValidateMessageBody> </Options> <Source>request</Source> </OASValidation>
אם גוף ההודעה לא תואם למפרט של OpenAPI, תוחזר השגיאה policies.oasvalidation.Failed
.
אימות פרמטרים
בדוגמה הבאה המדיניות מוגדרת להיכשל אם מציינים בבקשה פרמטרים של כותרת, שאילתה או קובץ cookie שלא מוגדרים במפרט OpenAPI.
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Header>false</Header> <Query>false</Query> <Cookie>false</Cookie> </AllowUnspecifiedParameters> </Options> </OASValidation>
רכיב <OASValidation>
מגדיר את מדיניות האימות של OpenAPI Specification.
ערך ברירת מחדל | מידע נוסף זמין בכרטיסייה מדיניות ברירת מחדל שבהמשך |
חובה? | חובה |
סוג | אובייקט מורכב |
רכיב הורה | לא רלוונטי |
רכיבי צאצא |
<DisplayName> <OASResource> <Source> <Options> <Source> |
תחביר
הרכיב <OASValidation>
משתמש בתחביר הבא:
<OASValidation continueOnError="[true|false]" enabled="[true|false]" name="policy_name" > <!-- All OASValidation child elements are optional except OASResource --> <DisplayName>policy_display_name</DisplayName> <OASResource>validation_JSON_or_YAML</OASResource> <Options> <ValidateMessageBody>[true|false]</ValidateMessageBody> <AllowUnspecifiedParameters> <Header>[true|false]</Header> <Query>[true|false]</Query> <Cookie>[true|false]</Cookie> </AllowUnspecifiedParameters> </Options> <Source>message_to_validate</Source> </OASValidation>
מדיניות ברירת מחדל
הדוגמה הבאה מציגה את הגדרות ברירת המחדל כשמוסיפים מדיניות אימות OAS לתהליך בממשק המשתמש של Apigee:
<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1"> <DisplayName>OpenAPI Spec Validation-1</DisplayName> <Properties/> <Source>request</Source> <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource> </OASValidation>
לרכיב הזה יש את המאפיינים הבאים, המשותפים לכל כללי המדיניות:
מאפיין | ברירת מחדל | חובה? | תיאור |
---|---|---|---|
name |
לא רלוונטי | נדרש |
השם הפנימי של המדיניות. הערך של המאפיין אפשר להשתמש ברכיב |
continueOnError |
false | אופציונלי | צריך להגדיר את הערך 'False' כדי להחזיר שגיאה כשהמדיניות נכשלת. זו התנהגות צפויה ברוב סוגי המדיניות. הערך של הפרמטר הוא TRUE כדי שביצוע הפעולות יתבצע גם אחרי שמדיניות תיכשל. |
enabled |
true | אופציונלי | כדי לאכוף את המדיניות צריך להגדיר את הערך True. מגדירים את המדיניות כ-"false" כדי "להשבית" את המדיניות. המדיניות הזו לא תיאכף גם אם היא תצורף לתהליך. |
async |
false | הוצא משימוש | המאפיין הזה הוצא משימוש. |
הפניה לרכיב צאצא
בקטע הזה מתוארים רכיבי הצאצא של <OASValidation>
.
<DisplayName>
בנוסף למאפיין name
, צריך להוסיף תווית למדיניות
בעורך ה-proxy לניהול ממשק המשתמש עם שם אחר שנשמע טבעי יותר.
הרכיב <DisplayName>
משותף לכל כללי המדיניות.
ערך ברירת מחדל | לא רלוונטי |
חובה? | אפשרות. אם משמיטים את הערך <DisplayName> , המערכת תשתמש בערך של
המאפיין name של המדיניות |
סוג | מחרוזת |
רכיב הורה | <PolicyElement> |
רכיבי צאצא | אין |
הרכיב <DisplayName>
משתמש בתחביר הבא:
תחביר
<PolicyElement> <DisplayName>policy_display_name</DisplayName> ... </PolicyElement>
דוגמה
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
לאלמנט <DisplayName>
אין מאפיינים או רכיבי צאצא.
<OASResource>
מציין את מפרט OpenAPI שצריך לבצע אימות מולו. אפשר לאחסן את הקובץ הזה:
- בהיקף של שרת ה-API בקטע
/apiproxy/resources/oas
בחבילה של שרת ה-API של שרת ה-proxy - בקטע
Resources
בתצוגת Navigator של עורך שרת ה-API.
מידע נוסף זמין במאמר ניהול משאבים.
אפשר לציין את מפרט OpenAPI באמצעות תבנית הודעה, כמו {oas.resource.url}
.
במקרה הזה, הערך של משתנה הזרימה oas.resource.url
(בסוגריים מסולסלים) ייבדק
ויוחלף במחרוזת של המטען הייעודי (payload) בזמן הריצה.
מידע נוסף זמין במאמר תבניות של הודעות.
ערך ברירת מחדל | אין |
חובה? | חובה |
סוג | מחרוזת |
רכיב הורה |
<OASValidation>
|
רכיבי צאצא | אין |
תחביר
הרכיב <OASResource>
משתמש בתחביר הבא:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> ... </OASValidation>
דוגמה
הדוגמה הבאה מפנה למפרט my-spec.yaml
שמאוחסן במסגרת /apiproxy/resources/oas
בחבילה של שרת proxy ל-API:
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> </OASValidation>
לאלמנט <OASResource>
אין מאפיינים או רכיבי צאצא.
<אפשרויות>
הגדרת האפשרויות של המדיניות.
ערך ברירת מחדל | לא רלוונטי |
חובה? | אופציונלי |
סוג | סוג מורכב |
רכיב הורה |
<OASValidation>
|
רכיבי צאצא |
<ValidateMessageBody> <AllowUnspecifiedParameters> |
תחביר
הרכיב <Options>
משתמש בתחביר הבא:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <ValidateMessageBody>[true|false]</ValidateMessageBody> <AllowUnspecifiedParameters> <Header>[true|false]</Header> <Query>[true|false]</Query> <Cookie>[true|false]</Cookie> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
דוגמה
בדוגמה הבאה מוגדרות האפשרויות של המדיניות. כל אחת מהאפשרויות מתוארת בפירוט בהמשך.
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <ValidateMessageBody>false</ValidateMessageBody> <AllowUnspecifiedParameters> <Header>false</Header> <Query>false</Query> <Cookie>false</Cookie> </AllowUnspecifiedParameters> </Options> </OASValidation>
<ValidateMessageBody>
המדיניות מציינת אם המדיניות צריכה לאמת את גוף ההודעה מול סכימת גוף הבקשה של הפעולה במפרט OpenAPI. צריך להגדיר את הערך כ-true כדי לאמת את תוכן ההודעה. צריך להגדיר את הערך false כדי לאמת רק שגוף ההודעה קיים.
אפשר לקבוע אם ביצוע הזרימה ימשיך בעקבות שגיאת אימות, על ידי הגדרת הערך של מאפיין continueOnError
עבור הרכיב <OASValidation>
כ-true.
ערך ברירת מחדל | false |
חובה? | אופציונלי |
סוג | ערך בוליאני |
רכיב הורה |
<Options>
|
רכיבי צאצא | אין |
תחביר
הרכיב <ValidateMessageBody>
משתמש בתחביר הבא:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <ValidateMessageBody>[true|false]</ValidateMessageBody> </Options> ... </OASValidation>
דוגמה
הדוגמה הבאה מפעילה את האימות של תוכן ההודעה:
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <ValidateMessageBody>true</ValidateMessageBody> </Options> </OASValidation>
<AllowUnspecifiedParameters>
המדיניות מגדירה את התנהגות המדיניות אם הבקשה כוללת פרמטרים של כותרת, שאילתה או קובץ cookie שאינם מוגדרים במפרט OpenAPI.
ערך ברירת מחדל | לא רלוונטי |
חובה? | אופציונלי |
סוג | סוג מורכב |
רכיב הורה |
<Options>
|
רכיבי צאצא |
<Header> <Query> <Cookie> |
תחביר
הרכיב <AllowUnspecifiedParameters>
משתמש בתחביר הבא:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <AllowUnspecifiedParameters> <Header>[true|false]</Header> <Query>[true|false]</Query> <Cookie>[true|false]</Cookie> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
דוגמה
בדוגמה הבאה המדיניות מוגדרת להיכשל אם מציינים בבקשה פרמטרים של כותרת, שאילתה או קובץ cookie שלא מוגדרים במפרט OpenAPI.
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Header>false</Header> <Query>false</Query> <Cookie>false</Cookie> </AllowUnspecifiedParameters> </Options> </OASValidation>
<Header>
(צאצא של <AllowUnspecifiedParameters>
)
המדיניות מגדירה את התנהגות המדיניות אם הבקשה כוללת פרמטרים של כותרת שאינם מוגדרים במפרט OpenAPI.
כדי לאפשר ציון של פרמטרים של כותרת בבקשה שאינם מוגדרים במפרט OpenAPI, צריך להגדיר את הפרמטר הזה ל-true. אחרת, יש להגדיר את הפרמטר הזה כ-false כדי לגרום לכשל בביצוע המדיניות.
ערך ברירת מחדל | true |
חובה? | ערך בוליאני |
סוג | סוג מורכב |
רכיב הורה |
<AllowUnspecifiedParameters>
|
רכיבי צאצא | אין |
תחביר
הרכיב <Header>
משתמש בתחביר הבא:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <AllowUnspecifiedParameters> <Header>[true|false]</Header> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
דוגמה
בדוגמה הבאה המדיניות מוגדרת לכשל אם צוין בבקשה פרמטר של כותרת שלא מוגדר במפרט OpenAPI.
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Header>false</Header> </AllowUnspecifiedParameters> </Options> </OASValidation>
<Query>
(צאצא של <AllowUnspecifiedParameters>
)
המדיניות מגדירה את התנהגות המדיניות אם הבקשה כוללת פרמטרים של שאילתה שלא מוגדרים במפרט OpenAPI.
כדי לאפשר ציון של פרמטרים של שאילתה בבקשה שאינם מוגדרים במפרט OpenAPI, צריך להגדיר את הפרמטר הזה ל-true. אחרת, יש להגדיר את הפרמטר הזה כ-false כדי לגרום לכשל בביצוע המדיניות.
ערך ברירת מחדל | true |
חובה? | ערך בוליאני |
סוג | סוג מורכב |
רכיב הורה |
<AllowUnspecifiedParameters>
|
רכיבי צאצא | אין |
תחביר
הרכיב <Query>
משתמש בתחביר הבא:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <AllowUnspecifiedParameters> <Query>[true|false]</Query> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
דוגמה
בדוגמה הבאה המדיניות מוגדרת להיכשל אם צוין פרמטר שאילתה בבקשה שלא מוגדר במפרט OpenAPI.
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Query>false</Query> </AllowUnspecifiedParameters> </Options> </OASValidation>
המדיניות מגדירה את התנהגות המדיניות אם הבקשה כוללת פרמטרים של קובצי cookie שלא מוגדרים במפרט OpenAPI.
כדי לאפשר ציון של פרמטרים של קובצי cookie בבקשה שאינם מוגדרים במפרט OpenAPI, צריך להגדיר את הפרמטר הזה ל-true. אחרת, יש להגדיר את הפרמטר הזה כ-false כדי לגרום לכשל בביצוע המדיניות.
ערך ברירת מחדל | true |
חובה? | ערך בוליאני |
סוג | סוג מורכב |
רכיב הורה |
<AllowUnspecifiedParameters>
|
רכיבי צאצא | אין |
תחביר
הרכיב <Cookie>
משתמש בתחביר הבא:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <AllowUnspecifiedParameters> <Query>[true|false]</Query> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
דוגמה
בדוגמה הבאה המדיניות מוגדרת להיכשל אם צוין פרמטר שאילתה בבקשה שלא מוגדר במפרט OpenAPI.
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Cookie>false</Cookie> </AllowUnspecifiedParameters> </Options> </OASValidation>
<Source>
הודעת JSON לבדיקה מפני התקפות מטען ייעודי (payload) של JSON. בדרך כלל הערך הזה מוגדר לערך
request
, כי בדרך כלל צריך להעריך בקשות נכנסות מאפליקציות של לקוח.
כדי להעריך את הודעות התשובה צריך להגדיר את הערך תשובה.
צריך להגדיר את הערך message כדי להעריך אוטומטית את הודעת הבקשה
כשהמדיניות מצורפת לתהליך הבקשה ואת הודעת התשובה כשהמדיניות מצורפת לתהליך התגובה.
ערך ברירת מחדל | בקשה |
חובה? | אופציונלי |
סוג | מחרוזת |
רכיב הורה |
<Source>
|
רכיבי צאצא | אין |
תחביר
הרכיב <Source>
משתמש בתחביר הבא:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Source>[message|request|response]</Source> ... </OASValidation>
דוגמה
בדוגמה הבאה מתבצעת הערכה אוטומטית של הודעת הבקשה כשהמדיניות מצורפת לתהליך הבקשה ואת הודעת התשובה כאשר המדיניות מצורפת לתהליך התשובה:
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Source>message</Source> </OASValidation>
לאלמנט <Source>
אין מאפיינים או רכיבי צאצא.
סכימות
כל סוג מדיניות מוגדר באמצעות סכימת XML (.xsd
). סכימות של מדיניות זמינות ב-GitHub.
קודי שגיאה
בקטע הזה מתוארים קודי התקלות והודעות השגיאה שמוחזרים, ומשתני השגיאה שמוגדרים על ידי Edge כשהמדיניות הזו גורמת לשגיאה. חשוב לדעת אם אתם מפתחים כללים לתיקון תקלות. מידע נוסף זמין במאמר מה צריך לדעת על שגיאות מדיניות ועל טיפול בפגמים.
שגיאות בזמן ריצה
השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.
קוד שגיאה | סטטוס HTTP | סיבה | |
---|---|---|---|
steps.oasvalidation.Failed |
500 | לא ניתן לאמת את גוף הודעת הבקשה מול מפרט OpenAPI שסופק. | |
steps.oasvalidation.SourceMessageNotAvailable |
500 |
המשתנה שצוין ברכיב |
|
steps.oasvalidation.NotMessageVariable |
500 |
רכיב |
build |
שגיאות בפריסה
השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.
שם השגיאה | סיבה | |
---|---|---|
ResourceDoesNotExist |
מפרט OpenAPI שיש אליו הפניה ברכיב <OASResource> לא קיים.
|
|
ResourceCompileFailed |
מפרט OpenAPI שכלול בפריסה מכיל שגיאות שמונעות את ההידור שלו. בדרך כלל הדבר מצביע על כך שהמפרט לא מעוצב כראוי במפרט OpenAPI 3.0. | |
BadResourceURL |
לא ניתן לעבד את מפרט OpenAPI שיש אליו הפניה ברכיב <OASResource> . מצב כזה יכול לקרות אם הקובץ אינו קובץ JSON או YAML, או אם
כתובת ה-URL של הקובץ לא צוינה.
|
משתני שבר
המשתנים האלה מוגדרים כשהמדיניות הזו גורמת לשגיאה בזמן הריצה. אפשר לקרוא מידע נוסף במאמר מה צריך לדעת על שגיאות מדיניות.
משתנים | מיקום | דוגמה |
---|---|---|
fault.name="fault_name" |
fault_name הוא שם התקלה, כפי שמפורט בטבלה שגיאות זמן ריצה שלמעלה. שם הטעות הוא החלק האחרון בקוד השגיאה. | fault.name Matches "ResourceDoesNotExist" |
oasvalidation.policy_name.failed |
policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לשגיאה. | oasvalidation.myoaspolicy.failed = true |
תכונות נתמכות של מפרטי OpenAPI
מדיניות OASValidation תומכת בתכונות המפרט של OpenAPI שמוצגות בסיכום בטבלה הבאה, לפי קטגוריה. בהמשך מפורטות גם התכונות שלא נתמכות.
קטגוריה | נתמך | מה לא ניתן לעשות |
---|---|---|
פורמטים של סוגי נתונים | בוליאני date date-time double float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid |
בינארי בייט סיסמה |
אובייקט הדיסקרימינטור | מיפוי propertyName |
לא רלוונטי |
אובייקט סוג מדיה | סכימה | קידוד דוגמה דוגמאות |
אובייקט פעולות | פרמטרים requestBody תגובות אבטחה (תמיכה חלקית) |
קריאות חוזרות שרתים הוצאו משימוש |
אובייקט Parameters (פרמטרים) | AllowEmptyValue ב-( query , header , path )חובה תגובות סכימה סגנון ( deepObject , form , formmatrix , label , pipeDelimited , simple , spaceDelimited )הערה: deepObject תומך בפרמטרים של מחרוזת בלבד; אין תמיכה במערכים ובאובייקטים בתצוגת עץ.
|
תוכן לדוגמה לדוגמה דוגמאות לשימוש בתכונה allowReserve |
אובייקט של נתיבים | מחיקה get head אפשרויות פרמטרים תיקון פוסט put trace משתנים |
שרתים |
בקשת אובייקט גוף | application/json Application/hal+json Application/x-www-form-urlcoding ( encoding אובייקט לא נתמך)content חובה |
application/xml multipart/form-data text/plain text/xml |
אובייקט תגובה | application/json Application/hal+json application/x-www-form-urlencoded ( encoding אובייקט לא נתמך)content כותרות |
application/xml links text/plain text/xml |
אובייקט תשובות | ברירת מחדל קוד סטטוס HTTP |
לא רלוונטי |
אובייקט סכימה | $ref additionalProperties (וריאציה של דגל בוליאני בלבד) allOf (המערכת מתעלמת אם הערך של additionalProperties הוא false )anyOf enum specificMaximum/UniqueMinimum format items maximum/Minimum maxItems/minItems maxLength/minLength maxProperties/minProperties MultipleOf not nullable oneOf pattern nullable oneOf pattern |
הוצא משימוש דוגמה readOnly writeOnly xml |
אובייקט סכמת אבטחה | בשדה (header , query ) (המערכת תתעלם אם type הוא http )סוג apiKey , http )
|
bearerFormat flows openIdConnectUrl scheme |
אובייקט של שרת | משתנים כתובת URL |
הגדרות מרובות של שרתים |