אתם צופים במסמכי התיעוד של Apigee Edge.
אפשר לעיין במסמכי התיעוד של Apigee X. מידע

מידע על המדיניות OASValidation
מדיניות OASValidation (אימות מפרט OpenAPI) מאפשרת לכם לאמת בקשה נכנסת או הודעת תגובה מול מפרט OpenAPI 3.0 (JSON או YAML). איזה תוכן עובר אימות?
המדיניות OASValidation מציינת את השם של מפרט OpenAPI שבו יש להשתמש לצורך אימות כשהשלב שאליו מצורפת המדיניות מופעל.
מפרט ה-OpenAPI מאוחסן כמשאב במיקום הסטנדרטי הבא בחבילת ה-API Proxy: apiproxy/resources/oas
.
למפרט OpenAPI צריך להיות התוסף .json
, .yml
או .yaml
.
מוסיפים מפרט OpenAPI כמשאב לחבילת proxy של API באמצעות ממשק המשתמש או API, כמו שמתואר במאמר ניהול משאבים.
איזה תוכן מאומת?
בטבלה הבאה מפורט סיכום של תוכן הודעת הבקשה שעובר אימות על ידי מדיניות OASValidation, לפי רכיב.
רכיבים | בקש אימות |
---|---|
נתיב בסיס | מאמת את נתיב הבסיס שהוגדר על ידי שרת ה-API הפרוקסי, ומתעלם מנתיב הבסיס שצוין במפרט OpenAPI. |
נתיב | האימות מוודא שנתיב הבקשה (ללא נתיב הבסיס) תואם לאחת מתבניות הנתיבים שמוגדרות במפרט OpenAPI. |
פועל | האימות מוודא שהפועל מוגדר לנתיב במפרט OpenAPI. |
גוף הודעת הבקשה |
הערה: המדיניות מאמתת את גוף הודעת הבקשה מול מפרט OpenAPI רק אם Content-Type מוגדר ל- |
פרמטרים |
|
בטבלה הבאה מופיע סיכום של תוכן הודעת התגובה שמאומת על ידי מדיניות 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.
ערך ברירת המחדל | מידע נוסף מופיע בכרטיסייה מדיניות ברירת מחדל שבהמשך. |
חובה? | חובה |
סוג | אובייקט מורכב |
רכיב אב | לא רלוונטי |
רכיבי צאצא |
<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>
This element has the following attributes that are common to all policies:
Attribute | Default | Required? | Description |
---|---|---|---|
name |
N/A | Required |
The internal name of the policy. The value of the Optionally, use the |
continueOnError |
false | Optional | Set to "false" to return an error when a policy fails. This is expected behavior for most policies. Set to "true" to have flow execution continue even after a policy fails. |
enabled |
true | Optional | Set to "true" to enforce the policy. Set to "false" to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow. |
async |
false | Deprecated | This attribute is deprecated. |
הפניה לרכיב צאצא
בקטע הזה מתוארים רכיבי הבן של <OASValidation>
.
<DisplayName>
Use in addition to the name
attribute to label the policy in the
management UI proxy editor with a different, more natural-sounding name.
The <DisplayName>
element is common to all policies.
Default Value | n/a |
Required? | Optional. If you omit <DisplayName> , the value of the
policy's name attribute is used |
Type | String |
Parent Element | <PolicyElement> |
Child Elements | None |
The <DisplayName>
element uses the following syntax:
Syntax
<PolicyElement> <DisplayName>policy_display_name</DisplayName> ... </PolicyElement>
Example
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
The <DisplayName>
element has no attributes or child elements.
<OASResource>
מציין את מפרט OpenAPI שצריך לבצע אימות מולו. אפשר לאחסן את הקובץ הזה:
- בטווח של ה-proxy ל-API בקטע
/apiproxy/resources/oas
בחבילת ה-proxy ל-API - בקטע
Resources
בתצוגת הניווט של כלי העריכה של שרת ה-API הפרוקסי.
מידע נוסף זמין במאמר בנושא ניהול משאבים.
אפשר לציין את מפרט OpenAPI באמצעות תבנית הודעה, כמו {oas.resource.url}
.
במקרה כזה, הערך של משתנה הזרימה oas.resource.url
(בסוגריים מסולסלים) יוערך ויוחלף במחרוזת המטען הייעודי בזמן הריצה.
מידע נוסף זמין במאמר בנושא תבניות של הודעות.
ערך ברירת המחדל | ללא |
חובה? | חובה |
סוג | מחרוזת |
רכיב אב |
<OASValidation>
|
רכיבי צאצא | ללא |
תחביר
התחביר של רכיב <OASResource>
הוא:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> ... </OASValidation>
דוגמה
בדוגמה הבאה יש הפניה למפרט my-spec.yaml
שמאוחסן ב-/apiproxy/resources/oas
בחבילת ה-API Proxy:
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> </OASValidation>
לרכיב <OASResource>
אין מאפיינים או רכיבי צאצא.
<Options>
הגדרת אפשרויות למדיניות.
ערך ברירת המחדל | לא רלוונטי |
חובה? | אופציונלי |
סוג | סוג מורכב |
רכיב אב |
<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
, כי בדרך כלל צריך להעריך בקשות נכנסות מאפליקציות לקוח.
מגדירים את הערך response כדי להעריך הודעות תגובה.
הערך 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.
קודי שגיאה
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause | |
---|---|---|---|
steps.oasvalidation.Failed |
500 | Request message body cannot be validated against the provided OpenAPI Specification. | |
steps.oasvalidation.SourceMessageNotAvailable |
500 |
Variable specified in the |
|
steps.oasvalidation.NotMessageVariable |
500 |
|
build |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause | |
---|---|---|
ResourceDoesNotExist |
OpenAPI Specification referenced in the <OASResource> element does not exist.
|
|
ResourceCompileFailed |
OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0. | |
BadResourceURL |
OpenAPI Specification referenced in the <OASResource> element cannot be processed. This can occur if the file is not a JSON or YAML file or the
file URL is not specified correctly.
|
Fault variables
These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "ResourceDoesNotExist" |
oasvalidation.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | oasvalidation.myoaspolicy.failed = true |
תכונות נתמכות של מפרטי OpenAPI
מדיניות OASValidation תומכת בתכונות של מפרט OpenAPI שמסוכמות בטבלה הבאה, לפי קטגוריה. מופיעה גם רשימה של התכונות שלא נתמכות.
קטגוריה | נתמך | לא נתמך |
---|---|---|
פורמטים של סוגי נתונים | boolean date date-time double float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid |
binary byte password |
אובייקט דיסקרימינטור | מיפוי propertyName |
לא רלוונטי |
אובייקט מסוג מדיה | סכימה | קידוד דוגמה דוגמאות |
אובייקט פעולות | parameters requestBody responses security (partial support) |
callbacks deprecated servers |
אובייקט הפרמטרים | allowEmptyValue in ( query , header , path )required responses schema style ( deepObject , form , formmatrix , label , pipeDelimited , simple , spaceDelimited )הערה: deepObject תומך רק בפרמטרים של מחרוזות. הוא לא תומך במערכים ובאובייקטים מקוננים.
|
allowReserved deprecated example examples content |
אובייקט Paths | delete get head options parameters patch post put trace variables |
שרתים |
אובייקט גוף הבקשה | application/json application/hal+json application/x-www-form-urlencoded ( encoding object not supported)content required |
application/xml multipart/form-data text/plain text/xml |
אובייקט תגובה | application/json application/hal+json application/x-www-form-urlencoded ( encoding object not supported)content headers |
application/xml links text/plain text/xml |
אובייקט התשובות | ברירת מחדל קוד סטטוס HTTP |
לא רלוונטי |
אובייקט סכימה | $ref additionalProperties (רק בווריאציה של דגל בוליאני) allOf (מתעלמים אם additionalProperties הוא false )anyOf enum exclusiveMaximum/exclusiveMinimum format items maximum/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf not nullable oneOf pattern properties required title type uniqueItems |
deprecated example readOnly writeOnly xml |
אובייקט של תוכנית אבטחה | ב- (header , query ) (מתעלמים אם type הוא http )שם סוג ( apiKey , http )
|
bearerFormat flows openIdConnectUrl scheme |
אובייקט שרת | כתובת URL משתנים |
הגדרות של כמה שרתים |