מדיניות OASValidation

אתם צופים במסמכי התיעוד של 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. הגדרת האפשרות הזו באמצעות <ValidateMessageBody>

הערה: המדיניות מאמתת את גוף הודעת הבקשה מול מפרט OpenAPI רק אם Content-Type מוגדר ל-application/json. אם סוג התוכן לא מוגדר כ-application/json, האימות של גוף הודעת הבקשה יעבור אוטומטית (בלי לבצע אימות של התוכן).

פרמטרים
  • האימות מוודא שהפרמטרים הנדרשים מופיעים בבקשה, כולל פרמטרים של נתיב, כותרת, שאילתה וקובץ Cookie.
  • הכלי מאמת שערכי הפרמטרים תואמים לאלה שמוגדרים במפרט OpenAPI.
  • אפשר גם לאמת אם קיימים בבקשה פרמטרים שלא מוגדרים במפרט OpenAPI. הגדרת האפשרות הזו באמצעות <AllowUnspecifiedParameters>

בטבלה הבאה מופיע סיכום של תוכן הודעת התגובה שמאומת על ידי מדיניות OASValidation, לפי רכיב.

רכיבים אימות תשובות
נתיב האימות מוודא שנתיב הבקשה (ללא נתיב הבסיס) תואם לאחת מתבניות הנתיבים שמוגדרות במפרט OpenAPI.
פועל האימות מוודא שהפועל מוגדר לנתיב במפרט OpenAPI.
גוף הודעת התשובה
  • מאמת את קיום גוף ההודעה בתגובה, אם נדרש.
  • הכלי מאמת שכותרות התגובה במפרט OpenAPI מופיעות בהודעת התגובה, ושהערך של כותרות התגובה תואם לסכימה.
  • אופציונלי: מאמת את גוף ההודעה מול סכימת גוף התגובה של הפעולה במפרט OpenAPI. הגדרת האפשרות הזו באמצעות <ValidateMessageBody>

דוגמאות

בדוגמאות הבאות מוצגים כמה מהאופנים שבהם אפשר להשתמש במדיניות 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>

לרכיב הזה יש את המאפיינים הבאים, המשותפים לכל כללי המדיניות:

מאפיין ברירת מחדל חובה? תיאור
name לא רלוונטי נדרש

השם הפנימי של המדיניות. הערך של המאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. האורך המקסימלי של הערך הוא 255 תווים.

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

  • בטווח של ה-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>

מגדירה את ההתנהגות של המדיניות אם יש פרמטרים של כותרת בבקשה שלא מוגדרים במפרט 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 <Source> element of the policy is either out of scope or cannot be resolved.
steps.oasvalidation.NotMessageVariable 500

<Source> element is set to a variable that is not of type message.

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
email
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
משתנים 		הגדרות של כמה שרתים

נושאים קשורים