นโยบายการตรวจสอบความถูกต้องของ OAS

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X info

เกี่ยวกับนโยบาย OASValidation

นโยบาย OASValidation (การตรวจสอบข้อกำหนดของ OpenAPI) ช่วยให้คุณตรวจสอบข้อความคำขอหรือการตอบกลับขาเข้าเทียบกับข้อกำหนดของ OpenAPI 3.0 (JSON หรือ YAML) ได้ ดูเนื้อหาใดบ้างที่ได้รับการตรวจสอบ

นโยบาย OASValidation จะระบุชื่อของข้อกำหนด OpenAPI ที่จะใช้สำหรับการตรวจสอบเมื่อขั้นตอนที่แนบนโยบายไว้ทำงาน ข้อกำหนด OpenAPI จะจัดเก็บเป็นทรัพยากรในตำแหน่งมาตรฐานต่อไปนี้ภายในแพ็กเกจพร็อกซี API: apiproxy/resources/oas ข้อกำหนดเฉพาะของ OpenAPI ต้องมีนามสกุล .json, .yml, .yaml

เพิ่มข้อกำหนด OpenAPI เป็นทรัพยากรลงในแพ็กเกจพร็อกซี API โดยใช้ UI หรือ API ตามที่อธิบายไว้ในจัดการทรัพยากร

เนื้อหาใดบ้างที่ได้รับการตรวจสอบความถูกต้อง

ตารางต่อไปนี้สรุปเนื้อหาข้อความคำขอที่ตรวจสอบโดยนโยบาย OASValidation ตามคอมโพเนนต์

คอมโพเนนต์ ขอการตรวจสอบ
Basepath ตรวจสอบเส้นทางฐานที่กำหนดโดยพร็อกซี API โดยไม่สนใจเส้นทางฐานที่ระบุในข้อกำหนดเฉพาะของ OpenAPI
เส้นทาง ตรวจสอบว่าเส้นทางคำขอ (ไม่รวมเส้นทางฐาน) ตรงกับรูปแบบเส้นทางที่กำหนดไว้ในข้อกำหนดเฉพาะของ OpenAPI
คำกริยา ตรวจสอบว่ามีการกำหนดคำกริยาสำหรับเส้นทางในข้อกำหนด OpenAPI
เนื้อหาข้อความคำขอ
  • ตรวจสอบว่ามีเนื้อหาข้อความในคำขอหรือไม่ หากจำเป็น
  • ตรวจสอบเนื้อหาข้อความเทียบกับสคีมาเนื้อหาคำขอของการดำเนินการในข้อกำหนด OpenAPI (ไม่บังคับ) กำหนดค่าตัวเลือกนี้โดยใช้ <ValidateMessageBody>

หมายเหตุ: นโยบายจะตรวจสอบเนื้อหาข้อความคำขอเทียบกับข้อกำหนด OpenAPI เฉพาะในกรณีที่ตั้งค่า Content-Type เป็น application/json หากไม่ได้ตั้งค่าประเภทเนื้อหาเป็น application/json การตรวจสอบเนื้อหาข้อความคำขอจะผ่านโดยอัตโนมัติ (โดยไม่ได้ตรวจสอบเนื้อหาจริงๆ)

พารามิเตอร์
  • ตรวจสอบว่าพารามิเตอร์ที่จำเป็นอยู่ในคำขอ ซึ่งรวมถึงพารามิเตอร์เส้นทาง ส่วนหัว การค้นหา และคุกกี้
  • ตรวจสอบว่าค่าพารามิเตอร์ตรงกับค่าที่กำหนดไว้ในข้อกำหนด OpenAPI
  • ตรวจสอบหรือไม่ก็ได้ว่ามีพารามิเตอร์ในคำขอที่ไม่ได้กำหนดไว้ในข้อกำหนด OpenAPI หรือไม่ กำหนดค่าตัวเลือกนี้โดยใช้ <AllowUnspecifiedParameters>

ตารางต่อไปนี้สรุปเนื้อหาข้อความตอบกลับที่ตรวจสอบโดยนโยบาย OASValidation ตามคอมโพเนนต์

คอมโพเนนต์ การตรวจสอบคำตอบ
เส้นทาง ตรวจสอบว่าเส้นทางคำขอ (ไม่รวมเส้นทางฐาน) ตรงกับรูปแบบเส้นทางที่กำหนดไว้ในข้อกำหนดเฉพาะของ OpenAPI
คำกริยา ตรวจสอบว่ามีการกำหนดคำกริยาสำหรับเส้นทางในข้อกำหนด OpenAPI
เนื้อหาข้อความตอบกลับ
  • ตรวจสอบว่ามีเนื้อหาข้อความในการตอบกลับหรือไม่ หากจำเป็น
  • ตรวจสอบว่าส่วนหัวการตอบกลับในข้อกำหนด OpenAPI มีอยู่ในข้อความตอบกลับ และค่าของส่วนหัวการตอบกลับตรงกับสคีมา
  • ตรวจสอบเนื้อหาข้อความกับสคีมาเนื้อหาการตอบกลับของการดำเนินการในข้อกำหนด OpenAPI (ไม่บังคับ) กำหนดค่าตัวเลือกนี้โดยใช้ <ValidateMessageBody>

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงวิธีบางส่วนที่คุณสามารถใช้นโยบาย OASValidation เพื่อตรวจสอบข้อความเทียบกับข้อกำหนด OpenAPI 3.0

ตรวจสอบข้อความคำขอ

ในตัวอย่างต่อไปนี้ นโยบาย myoaspolicy จะตรวจสอบเนื้อหาของข้อความคำขอเทียบกับสคีมาเนื้อหาข้อความคำขอของการดำเนินการที่กำหนดไว้ในข้อกำหนด OpenAPI my-spec.json 

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

หากเนื้อหาข้อความไม่เป็นไปตามข้อกำหนดเฉพาะของ OpenAPI ระบบจะแสดงข้อผิดพลาด policies.oasvalidation.Failed

ตรวจสอบพารามิเตอร์

ตัวอย่างต่อไปนี้จะกำหนดค่านโยบายให้ล้มเหลวหากมีการระบุพารามิเตอร์ส่วนหัว การค้นหา หรือคุกกี้ในคำขอที่ไม่ได้กำหนดไว้ในข้อกำหนดเฉพาะของ 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 ลงในโฟลว์ใน UI ของ 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> เพื่อติดป้ายกํากับนโยบายในตัวแก้ไขพร็อกซี UI การจัดการด้วยชื่อภาษาอื่นที่เป็นธรรมชาติได้
continueOnError เท็จ ไม่บังคับ ตั้งค่าเป็น "false" เพื่อแสดงข้อผิดพลาดเมื่อนโยบายล้มเหลว ซึ่งเป็นลักษณะการทํางานที่คาดหวังตามนโยบายส่วนใหญ่ ตั้งค่าเป็น "จริง" เพื่อดําเนินการโฟลว์ข้อมูลต่อไป แม้ว่านโยบายจะล้มเหลวก็ตาม
enabled จริง ไม่บังคับ ตั้งค่าเป็น "true" เพื่อบังคับใช้นโยบาย ตั้งค่าเป็น "false" เพื่อ "ปิด" นโยบาย ระบบจะไม่บังคับใช้นโยบายแม้ว่าจะยังคงแนบไปกับโฟลว์
async   เท็จ เลิกใช้ แอตทริบิวต์นี้เลิกใช้งานแล้ว

การอ้างอิงองค์ประกอบย่อย

ส่วนนี้จะอธิบายองค์ประกอบย่อยของ <OASValidation>

<DisplayName>

ใช้ร่วมกับแอตทริบิวต์ name เพื่อติดป้ายกำกับนโยบายในเครื่องมือแก้ไขพร็อกซี UI การจัดการด้วยชื่ออื่นที่ฟังดูเป็นธรรมชาติมากขึ้น

องค์ประกอบ <DisplayName> เป็นองค์ประกอบที่ใช้ร่วมกันในทุกนโยบาย

ค่าเริ่มต้น ไม่มี
ต้องระบุหรือไม่ ไม่บังคับ หากคุณละเว้น <DisplayName> ระบบจะใช้ค่าของแอตทริบิวต์ name ของนโยบาย
ประเภท สตริง
องค์ประกอบหลัก <PolicyElement>
องค์ประกอบย่อย ไม่มี

องค์ประกอบ <DisplayName> ใช้ไวยากรณ์ต่อไปนี้

ไวยากรณ์

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

ตัวอย่าง

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

องค์ประกอบ <DisplayName> ไม่มีแอตทริบิวต์หรือองค์ประกอบย่อย

<OASResource>

ระบุข้อกำหนด OpenAPI ที่จะตรวจสอบ คุณจัดเก็บไฟล์ต่อไปนี้ได้

  • ที่ขอบเขตพร็อกซี API ในส่วน /apiproxy/resources/oas ในแพ็กเกจพร็อกซี API
  • ในส่วน Resources ของมุมมอง Navigator ของเครื่องมือแก้ไขพร็อกซี 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

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

องค์ประกอบ <OASResource> ไม่มีแอตทริบิวต์หรือองค์ประกอบย่อย

<ตัวเลือก>

กำหนดค่าตัวเลือกสำหรับนโยบาย

ค่าเริ่มต้น ไม่มี
ต้องระบุหรือไม่ ไม่บังคับ
ประเภท ประเภทที่ซับซ้อน
องค์ประกอบหลัก <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

ค่าเริ่มต้น เท็จ
ต้องระบุหรือไม่ ไม่บังคับ
ประเภท บูลีน
องค์ประกอบหลัก <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>

กำหนดค่าลักษณะการทำงานของนโยบายหากมีพารามิเตอร์ส่วนหัว การค้นหา หรือคุกกี้อยู่ในคำขอที่ไม่ได้กำหนดไว้ในข้อกำหนด 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>

ตัวอย่าง

ตัวอย่างต่อไปนี้จะกำหนดค่านโยบายให้ล้มเหลวหากมีการระบุพารามิเตอร์ส่วนหัว การค้นหา หรือคุกกี้ในคำขอที่ไม่ได้กำหนดไว้ในข้อกำหนดเฉพาะของ 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 เพื่อให้การดำเนินการตามนโยบายล้มเหลว

ค่าเริ่มต้น จริง
ต้องระบุหรือไม่ บูลีน
ประเภท ประเภทที่ซับซ้อน
องค์ประกอบหลัก <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 เพื่อให้การดำเนินการตามนโยบายล้มเหลว

ค่าเริ่มต้น จริง
ต้องระบุหรือไม่ บูลีน
ประเภท ประเภทที่ซับซ้อน
องค์ประกอบหลัก <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>

กำหนดค่าลักษณะการทำงานของนโยบายหากมีพารามิเตอร์คุกกี้อยู่ในคำขอที่ไม่ได้กำหนดไว้ในข้อกำหนดเฉพาะของ OpenAPI

หากต้องการอนุญาตให้ระบุพารามิเตอร์คุกกี้ในคำขอที่ไม่ได้กำหนดไว้ในข้อกำหนด OpenAPI ให้ตั้งค่าพารามิเตอร์นี้เป็น true ไม่เช่นนั้น ให้ตั้งค่าพารามิเตอร์นี้เป็น false เพื่อให้การดำเนินการตามนโยบายล้มเหลว

ค่าเริ่มต้น จริง
ต้องระบุหรือไม่ บูลีน
ประเภท ประเภทที่ซับซ้อน
องค์ประกอบหลัก <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 ที่จะประเมินกับการโจมตีเพย์โหลด 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

รหัสข้อผิดพลาด

ส่วนนี้จะอธิบายโค้ดข้อผิดพลาดและข้อความแสดงข้อผิดพลาดที่แสดงผลและตัวแปรข้อผิดพลาดที่ Edge กําหนดเมื่อนโยบายนี้ทําให้เกิดข้อผิดพลาด ข้อมูลนี้เป็นสิ่งสำคัญที่ต้องทราบหากคุณกำลังกำหนดกฎข้อผิดพลาดเพื่อจัดการกับข้อผิดพลาด ดูข้อมูลเพิ่มเติมได้ที่สิ่งที่คุณต้องทราบเกี่ยวกับข้อผิดพลาดของนโยบายและการจัดการข้อผิดพลาด

ข้อผิดพลาดเกี่ยวกับรันไทม์

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อนโยบายทำงาน

รหัสข้อผิดพลาด สถานะ HTTP สาเหตุ
steps.oasvalidation.Failed 500 ตรวจสอบเนื้อหาของคำขอกับข้อกําหนดของ OpenAPI ที่ระบุไม่ได้
steps.oasvalidation.SourceMessageNotAvailable 500

ตัวแปรที่ระบุในองค์ประกอบ <Source> ของนโยบายอยู่นอกขอบเขตหรือแก้ไขไม่ได้
steps.oasvalidation.NotMessageVariable 500

องค์ประกอบ <Source> ได้รับการตั้งค่าเป็นตัวแปรที่ไม่ใช่ประเภท ข้อความ

ข้อผิดพลาดในการทำให้ใช้งานได้

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อคุณใช้พร็อกซีที่มีนโยบายนี้

ชื่อข้อผิดพลาด สาเหตุ
ResourceDoesNotExist ไม่มีข้อมูลจำเพาะของ OpenAPI ที่อ้างอิงในองค์ประกอบ <OASResource>
ResourceCompileFailed ข้อมูลจำเพาะของ OpenAPI ที่รวมอยู่ในการทำให้ใช้งานได้มีข้อผิดพลาดที่ทำให้ไม่สามารถคอมไพล์ได้ โดยทั่วไปเป็นการบ่งชี้ว่าข้อมูลจำเพาะไม่ใช่ OpenAPI Specification 3.0 ที่มีรูปแบบถูกต้อง
BadResourceURL ไม่สามารถประมวลผลข้อมูลจำเพาะของ OpenAPI ที่อ้างอิงในองค์ประกอบ <OASResource> ได้ ปัญหานี้อาจเกิดขึ้นหากไฟล์ไม่ใช่ไฟล์ JSON หรือ YAML หรือระบุ URL ของไฟล์ไม่ถูกต้อง

ตัวแปรของข้อผิดพลาด

ระบบจะตั้งค่าตัวแปรเหล่านี้เมื่อนโยบายนี้ทริกเกอร์ข้อผิดพลาดขณะรันไทม์ ดูข้อมูลเพิ่มเติมเกี่ยวกับสิ่งที่คุณจำเป็นต้องทราบเกี่ยวกับข้อผิดพลาดของนโยบาย

ตัวแปร สถานที่ ตัวอย่าง
fault.name="fault_name" fault_name คือชื่อของข้อผิดพลาดตามที่แสดงในตารางข้อผิดพลาดรันไทม์ด้านบน ชื่อข้อผิดพลาดคือส่วนสุดท้ายของโค้ดข้อผิดพลาด fault.name Matches "ResourceDoesNotExist"
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
ออบเจ็กต์ตัวแบ่ง mapping
propertyName 		ไม่มี
ออบเจ็กต์ประเภทสื่อ สคีมา encoding
example
examples
ออบเจ็กต์การดำเนินการ parameters
requestBody
responses
security (รองรับบางส่วน) 		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
ออบเจ็กต์เส้นทาง delete
get
head
options
parameters
patch
post
put
trace
variables 		เซิร์ฟเวอร์
ออบเจ็กต์เนื้อหาคำขอ application/json
application/hal+json
application/x-www-form-urlencoded (ไม่รองรับออบเจ็กต์ encoding)
content
ต้องระบุ 		application/xml
multipart/form-data
text/plain
text/xml
ออบเจ็กต์การตอบกลับ application/json
application/hal+json
application/x-www-form-urlencoded (ไม่รองรับออบเจ็กต์ encoding)
content
headers 		application/xml
links
text/plain
text/xml
ออบเจ็กต์คำตอบ default
รหัสสถานะ 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
ออบเจ็กต์รูปแบบการรักษาความปลอดภัย in (header, query) (ระบบจะไม่สนใจหาก type เป็น http)
name
type (apiKey, http) 		bearerFormat
flows
openIdConnectUrl
scheme
ออบเจ็กต์เซิร์ฟเวอร์ url
variables 		คำจำกัดความของเซิร์ฟเวอร์หลายรายการ

หัวข้อที่เกี่ยวข้อง