מדיניות OASValidation

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

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

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

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

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

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

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

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

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

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

  • בטווח של ה-proxy ל-API בקטע /apiproxy/resources/oas בחבילת ה-proxy ל-API
  • בקטע 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> אין מאפיינים או רכיבי צאצא.

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

ערך ברירת המחדל בקשה
חובה? אופציונלי
סוג 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 שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה. 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
 בינארי
בייט
סיסמה
אובייקט דיסקרימינטור מיפוי
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
משתנים 		הגדרות של כמה שרתים

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

תקן מפרט OpenAPI מאפשר לציין 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}$'

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

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

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

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

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

דוגמת קוד התנהגות
^\w{3}-\d{4}$

הקו לביטול הנעילה תקין. הוא משתמש רק בתכונות של ביטויים רגולריים בתוך קבוצת המשנה המומלצת. ‫Apigee יאפשר שמירה או ייבוא של ה-proxy, ובזמן הריצה המדיניות OASValidation תפעל כמצופה ותאמת את הפרמטר מול התבנית.
^([a-z]\w{3}-\d{4}$

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

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

התבנית תקינה, אבל היא משתמשת בחיפוש קדימה שלילי, שנמצא מחוץ לקבוצת המשנה המומלצת של תכונות הביטוי הרגולרי. מערכת Apigee תשעה את האימות של מסמך מפרט OpenAPI. בזמן הריצה, כשמריצים את מדיניות OASValidation שמפנה למפרט באמצעות התבנית הזו, מערכת Apigee תחיל את הביטוי הרגולרי הזה בצורה נכונה כדי לאמת את ערך הפרמטר, כי זמן הריצה של Apigee תומך למעשה בחיפוש קדימה שלילי.
^(a)?b(?(1)c|d)$

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

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

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