מדיניות OASVerify

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

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

דוגמאות

בדוגמאות הבאות מוצגים כמה מהאופנים שבהם אפשר להשתמש במדיניות OASValidation כדי לאמת הודעות בהתאם למפרט OpenAPI 3.0.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

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

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

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

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

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

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

<DisplayName>

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

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

התחביר של רכיב <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 name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

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

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

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

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

‫<Header> (ילד/ה של <AllowUnspecifiedParameters>)

מגדירה את ההתנהגות של המדיניות אם יש פרמטרים של כותרת בבקשה שלא מוגדרים במפרט OpenAPI.

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

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

‫<Query> (ילד/ה של <AllowUnspecifiedParameters>)

הגדרת אופן הפעולה של המדיניות אם יש פרמטרים של שאילתה בבקשה שלא מוגדרים במפרט OpenAPI.

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

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

‫<Cookie> (ילד/ה של <AllowUnspecifiedParameters>)

ההגדרה הזו קובעת את ההתנהגות של המדיניות אם יש פרמטרים של קובצי Cookie בבקשה שלא מוגדרים במפרט OpenAPI.

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

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Source>

הודעת JSON שצריך להעריך אותה בהשוואה למטענים ייעודיים (payload) של JSON שמשמשים להתקפות. בדרך כלל הערך שמוגדר הוא request, כי בדרך כלל צריך להעריך בקשות נכנסות מאפליקציות לקוח. מגדירים את הערך response כדי להעריך הודעות תגובה. הערך message גורם להערכה אוטומטית של הודעת הבקשה כשהמדיניות מצורפת לתהליך הבקשה, ושל הודעת התשובה כשהמדיניות מצורפת לתהליך התשובה.

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

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

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

שגיאות בפריסה

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

משתני שבר

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

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

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

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

• מדיניות להגנה מפני איומים ב-JSON
• מדיניות SOAPMessageValidation