Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

מדיניות OASValidation

מדיניות רגילה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

מדיניות OASValidation ‏ (OpenAPI Specification Validation) מאפשרת לאמת הודעת בקשה או תגובה נכנסת בהתאם למפרט OpenAPI 3.0, באמצעות פורמט JSON או YAML. איזה תוכן עובר אימות?

המדיניות OASValidation מציינת את השם של מפרט OpenAPI שבו יש להשתמש לצורך אימות כשהשלב שאליו מצורפת המדיניות מופעל. מפרט OpenAPI מאוחסן כמשאב במיקום הסטנדרטי הבא בחבילת ה-proxy ל-API: ‏apiproxy/resources/oas. למסמך מפרט OpenAPI חייבת להיות סיומת .json, .yml או .yaml.

מוסיפים מפרט OpenAPI כמשאב לחבילת proxy ל-API באמצעות ממשק המשתמש או API, כמו שמתואר במאמר ניהול משאבים.

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

איזה תוכן מאומת?

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

רכיבים	בקשת אימות
Basepath	מאמת את נתיב הבסיס שהוגדר על ידי ה-proxy ל-API, ומתעלם מנתיב הבסיס שצוין במפרט OpenAPI.
נתיב	האימות מוודא שנתיב הבקשה (ללא נתיב הבסיס) תואם לאחת מתבניות הנתיבים שמוגדרות במפרט OpenAPI.
פועל	הכלי מאמת שהפועל מוגדר לנתיב במפרט OpenAPI.
גוף הודעת הבקשה	מאמת את קיום גוף ההודעה בבקשה, אם נדרש. אופציונלי. מאמת את גוף ההודעה מול סכימת גוף הבקשה של הפעולה במפרט OpenAPI. מגדירים את האפשרות הזו באמצעות `<ValidateMessageBody>` הערה: המדיניות מאמתת את גוף הודעת הבקשה מול מפרט OpenAPI רק אם Content-Type מוגדר ל-`application/json`. אם סוג התוכן לא מוגדר ל-`application/json`, האימות של גוף הודעת הבקשה יעבור אוטומטית (בלי לבדוק את התוכן בפועל).
פרמטרים	האימות מוודא שהפרמטרים הנדרשים מופיעים בבקשה, כולל פרמטרים של נתיב, כותרת, שאילתה וקובץ Cookie. הפונקציה מאמתת שערכי הפרמטרים תואמים לאלה שמוגדרים במפרט OpenAPI. אפשרות נוספת היא לאמת אם קיימים פרמטרים בבקשה שלא מוגדרים במפרט OpenAPI. כדי להגדיר את האפשרות הזו, משתמשים ב-`<AllowUnspecifiedParameters>`

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

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

הערה: המדיניות OASValidation של Apigee מאמתת את נתיבי הבקשות והתגובות באופן שונה.
באימות בקשות, המדיניות מאמתת את נתיב הבקשה של proxy ל-API (לדוגמה, /hello עבור https://<BasePath>/hello).
באימות תגובות, המדיניות מאמתת את הנתיב של נקודת הקצה של היעד שאליה Apigee קורא (לדוגמה, /apigee/hello עבור https://{target-basepath}}/apigee/hello).
ההבחנה הזו חשובה אם נתיבי ה-proxy והיעד שונים, כי צריך להתאים את מפרט ה-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>

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

מאפיין	ברירת מחדל	חובה?	תיאור
`name`	לא רלוונטי	חובה	השם הפנימי של המדיניות. הערך של מאפיין `name` יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול להיות ארוך מ-255 תווים. אפשר להשתמש ברכיב `<DisplayName>` כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק המשתמש לניהול.
`continueOnError`	FALSE	אופציונלי	מגדירים את הערך `false` כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המקרים. הגדרה ל-`true` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מאמרים קשורים: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי
`enabled`	TRUE	אופציונלי	מגדירים את הערך `true` כדי לאכוף את המדיניות, או את הערך `false` כדי להשבית את המדיניות. המדיניות לא נאכפת גם אם היא עדיין משויכת לזרימה.
`async`	FALSE	הוצא משימוש	המאפיין הזה הוצא משימוש.

הפניה לרכיב צאצא

בקטע הזה מתוארים רכיבי הבן של <OASValidation>.

`<DisplayName>`

אפשר להשתמש במאפיין הזה בנוסף למאפיין name כדי לתת למדיניות שם אחר, שנשמע יותר טבעי, ב-UI של עורך ה-proxy לניהול.

הרכיב <DisplayName> משותף לכל סוגי המדיניות.

ערך ברירת המחדל	לא רלוונטי
חובה?	זה שינוי אופציונלי. אם לא מציינים את `<DisplayName>`, המערכת משתמשת בערך של מאפיין `name` של המדיניות.
סוג	String
רכיב אב	<`PolicyElement`>
רכיבי צאצא	ללא

רכיב <DisplayName> משתמש בתחביר הבא:

תחביר

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

דוגמה

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

לרכיב <DisplayName> אין מאפיינים או רכיבי צאצא.

`<OASResource>`

מציינים את מפרט OpenAPI שרוצים לבצע אימות מולו. אפשר לאחסן את הקובץ הזה:

במסגרת ה-API proxy בקטע /apiproxy/resources/oas בחבילת ה-API proxy
בקטע Resources בתצוגת הניווט של כלי העריכה של proxy ל-API.

מידע נוסף מופיע במאמר בנושא ניהול משאבים.

אפשר לציין את מפרט OpenAPI באמצעות תבנית הודעה, כמו {oas.resource.url}. במקרה כזה, הערך של משתנה הזרימה oas.resource.url (בסוגריים מסולסלים) יוערך ויוחלף במחרוזת המטען הייעודי בזמן הריצה. מידע נוסף זמין במאמר בנושא תבניות הודעות.

ערך ברירת המחדל	ללא
חובה?	חובה
סוג	String
רכיב אב	`<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 מצוין <OASResource> עם דרישות אבטחה שהוגדרו ברמה הגלובלית, דרישות האבטחה לא נאכפות. כדי לוודא שהדרישות נאכפות, צריך להגדיר את כל דרישות האבטחה ברמת הפעולה במפרט OpenAPI שמועבר ברכיב <OASResource> של המדיניות הזו. מידע נוסף זמין במאמר בעיות מוכרות ב-Apigee.

<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.

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

ערך ברירת המחדל	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>

דוגמה

<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, מתבצעת הערכה אוטומטית של הודעת הבקשה כשהמדיניות מצורפת לזרימת הבקשה, ושל הודעת התגובה כשהמדיניות מצורפת לזרימת התגובה.

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

קודי שגיאה

בקטע הזה מתוארים קודי התקלה והודעות השגיאה שמוחזרים, ומשתני התקלה שמוגדרים על ידי Apigee כשמדיניות כזו מפעילה שגיאה. חשוב לדעת את המידע הזה אם אתם מפתחים כללי תקלות לטיפול בתקלות. מידע נוסף על שגיאות שקשורות למדיניות ועל טיפול בשגיאות

שגיאות זמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

קוד תקלה	סטטוס HTTP	מטרה
`steps.oasvalidation.Failed`	`400`	אי אפשר לאמת את גוף הודעת הבקשה מול מפרט ה-OpenAPI שסופק.
`steps.oasvalidation.Failed`	`500`	אי אפשר לאמת את גוף ההודעה בתגובה בהתאם למפרט OpenAPI שסופק.
`steps.oasvalidation.SourceMessageNotAvailable`	`500`	המשתנה שצוין ברכיב `<Source>` של המדיניות לא נמצא בהיקף או שלא ניתן לפתור אותו.
`steps.oasvalidation.NonMessageVariable`	`500`	האלמנט `<Source>` מוגדר למשתנה שאינו מסוג message.

שגיאות בהטמעה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שמכיל את המדיניות הזו.

שם השגיאה	מטרה
`ResourceDoesNotExist`	קובץ מפרט OpenAPI שאליו יש הפניה ברכיב `<OASResource>` לא קיים.
`ResourceCompileFailed`	מפרט OpenAPI שכלול בפריסה מכיל שגיאות שמונעות את ההידור שלו. בדרך כלל, המשמעות היא שהמפרט לא תואם למפרט OpenAPI 3.0.
`BadResourceURL`	אי אפשר לעבד את מפרט OpenAPI שאליו יש הפניה ברכיב `<OASResource>`. השגיאה הזו יכולה לקרות אם הקובץ הוא לא קובץ JSON או YAML, או אם כתובת ה-URL של הקובץ לא צוינה בצורה נכונה.

משתני תקלות

המשתנים האלה מוגדרים כשהמדיניות הזו מפעילה שגיאה בזמן הריצה. מידע נוסף על שגיאות שקשורות למדיניות

משתנה	תיאור	דוגמה
`fault.category`	הקטגוריה של התקלה. כשמדיניות דוחה בקשה, הערך של השדה הזה תמיד יהיה `Step`.	`fault.category = "Step"`
`fault.name`	שם התקלה, כפי שמופיע בטבלה שגיאות בזמן ריצה שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	`fault.name Matches "ResourceDoesNotExist"`
`fault.reason`	הסיבה לתקלה. זו מחרוזת שניתן לקרוא, שמסבירה את הסיבה לתקלה.	`OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"`
`fault.subcategory`	קטגוריית המשנה של התקלה. כשמדיניות דוחה בקשה, הערך של השדה הזה תמיד יהיה `OASValidationFailure`.	`fault.subcategory = "OASValidationFailure"`
`OASValidation.policy_name.failed`	‫`policy_name` הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה.	`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 <x0A>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 משתנים	הגדרות של כמה שרתים

שימוש בתבניות בסכימה

תקן OpenAPI Specification מאפשר למפרטים לקבוע schema כדי לתאר את סוג הנתונים של פרמטר או שדה. עבור פרמטר או שדה מסוג מחרוזת, הסכימה יכולה גם להגדיר pattern, שהוא ביטוי רגולרי (regex) שמגדיר צורות תקינות למחרוזת.

לדוגמה, נניח שיש לכם את קטע המפרט הבא של OpenAPI:

paths:
  /products/{product-id}:
    get:
      operationId: getProduct
      summary: Get product by id
      description: returns information regarding a product, by id
      parameters:
        - name: product-id
          in: path
          description: id of the product
          required: true
          schema:
            type: string
            pattern: '^\w{3}-\d{4}$'

לפי המפרט הזה, בבקשת הפעולה getProduct, הפרמטר product-id צריך להתאים לביטוי הרגולרי שצוין, שמגדיר רצף של 3 תווים של מילים, מקף ו-4 ספרות עשרוניות.

מפרט OpenAPI מסתמך על תקן האימות של סכימת JSON כדי להגדיר באופן רשמי את ההתנהגות של התבנית באימות של ערך המחרוזת, ועל תקן הליבה של סכימת JSON כדי לספק המלצות ליוצרי סכימות לגבי קבוצת התחביר המוגבלת של ביטויים רגולריים. בתקן האחרון מומלץ להימנע משימוש בתכונות הבאות בתבניות במסמכי מפרט OpenAPI: בדיקות מקדימות (lookaheads) ובדיקות מקדימות הפוכות (lookbehinds), הפניות חוזרות וביטויים של תווים אוקטליים.

כברירת מחדל, Apigee מאמת את מסמך מפרט OpenAPI שאליו מתייחסת מדיניות OASValidation ומדווח על שגיאות אם מסמך המפרט לא בנוי בצורה תקינה. ‫Apigee גם מאמת תבניות של ביטויים רגולריים במסמך המפרט ומדווח על בעיות שנמצאו בו.

חשוב לציין שאם משתמשים בתכונות של ביטויים רגולריים שלא נכללות בקבוצת המשנה המומלצת, מערכת Apigee לא תאמת את הביטוי הרגולרי ותשהה כל אימות נוסף של מסמך מפרט OpenAPI. אם יש שגיאה במסמך, או בביטוי הרגולרי שמשתמש בתכונה שלא נכללת בקבוצת המשנה המומלצת, או אם תכונת הביטוי הרגולרי לא נתמכת בזמן הריצה של Apigee, השגיאה תזוהה רק בזמן הריצה כשהמדיניות תופעל.

בטבלה הבאה מופיעות כמה דוגמאות.

דוגמת קוד	התנהגות
`^\w{3}-\d{4}$`	התבנית תקינה. היא משתמשת רק בתכונות של ביטויים רגולריים שנמצאות בקבוצת המשנה המומלצת. מערכת Apigee תאפשר שמירה או ייבוא של ה-proxy, ובזמן הריצה מדיניות OASValidation תפעל כמצופה ותאמת את הפרמטר מול התבנית.
`^([a-z]\w{3}-\d{4}$`	התבנית לא תקינה כי חסרה בה סוגר סוגר. התבנית לא משתמשת בתכונות של ביטוי רגולרי מחוץ לקבוצת המשנה המומלצת. מערכת Apigee תדווח על השגיאה הזו בזמן הייבוא או השמירה של ה-API Proxy.
`^(?![a-z]\w{3}-\d{4}$`	התבנית לא תקינה. כמו בדוגמה הקודמת, חסרה סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר סוגר
`^(?![a-z])\w{3}-\d{4}$`	התבנית תקינה, אבל היא משתמשת בחיפוש קדימה שלילי, שלא נכלל בקבוצת המשנה המומלצת של תכונות הביטוי הרגולרי. מערכת Apigee תשעה את האימות של מסמך מפרט OpenAPI. בזמן הריצה, כשמריצים את מדיניות ה-OASValidation שמפנה למפרט באמצעות התבנית הזו, מערכת Apigee תחיל את הביטוי הרגולרי הזה בצורה נכונה כדי לאמת את ערך הפרמטר, כי זמן הריצה של Apigee תומך למעשה בחיפוש קדימה שלילי.
`^(a)?b(?(1)c\|d)$`	התבנית תקפה, אבל נעשה בה שימוש בתנאי של קבוצת לכידה, שנמצא מחוץ לקבוצת המשנה המומלצת של תכונות הביטוי הרגולרי. מערכת Apigee תשעה את האימות של מסמך מפרט OpenAPI. בזמן הריצה, כשמריצים את מדיניות OASValidation שמפנה למפרט באמצעות התבנית הזו, מערכת Apigee תחזיר שגיאה כי זמן הריצה של Apigee לא תומך בתכונת הביטוי הרגולרי הזו.

כדי למנוע כשלים בזמן הריצה, מומלץ להשתמש רק בתת-קבוצה מומלצת של תכונות בביטוי הרגולרי.

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

איזה תוכן מאומת?

דוגמאות

אימות הודעת הבקשה

אימות פרמטרים

רכיב <OASValidation>

תחביר

מדיניות ברירת המחדל

הפניה לרכיב צאצא

<DisplayName>

תחביר

דוגמה

<OASResource>

תחביר

דוגמה

<Options>

תחביר

דוגמה

<ValidateMessageBody>

תחביר

דוגמה

<AllowUnspecifiedParameters>

תחביר

דוגמה

תחביר

דוגמה

תחביר

דוגמה

תחביר

דוגמה

<Source>

תחביר

דוגמה

סכימה של המדיניות הזו

קודי שגיאה

שגיאות זמן ריצה

שגיאות בהטמעה

משתני תקלות

תכונות נתמכות של מפרטי OpenAPI

שימוש בתבניות בסכימה

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

מדיניות OASValidation

רכיב `<OASValidation>`

`<DisplayName>`

`<OASResource>`

`<AllowUnspecifiedParameters>`

`<Source>`