OASValidation-Richtlinie

Sie lesen gerade die Dokumentation zu Apigee Edge.
Zur Dokumentation zu Apigee X info

Über die OASValidation-Richtlinie

Mit der OASValidation-Richtlinie (OpenAPI-Spezifikation) können Sie eine eingehende Anfrage oder Antwortnachricht mit einer OpenAPI 3.0-Spezifikation (JSON oder YAML) prüfen. Siehe Welche Inhalte werden validiert?

Die OASValidation-Richtlinie gibt den Namen der OpenAPI-Spezifikation an, die für die Validierung verwendet werden soll, wenn der Schritt, mit dem die Richtlinie verknüpft ist, ausgeführt wird. Die OpenAPI-Spezifikation wird als Ressource im folgenden Standardspeicherort im API-Proxy-Bundle gespeichert: apiproxy/resources/oas. Die OpenAPI-Spezifikation muss die Erweiterung .json, .yml und .yaml haben.

Fügen Sie einem API-Proxy-Bundle mithilfe der UI oder API eine OpenAPI-Spezifikation als Ressource hinzu, wie unter Ressourcen verwalten beschrieben.

Welche Inhalte werden validiert?

Die folgende Tabelle fasst den Nachrichteninhalt der Anfrage, die von der OASValidation-Richtlinie validiert wird, nach Komponente zusammen.

Die folgende Tabelle fasst den Nachrichteninhalt der Antwort, die von der OASValidation-Richtlinie validiert wird, nach Komponente zusammen.

Beispiele

Folgende Beispiele zeigen einige Möglichkeiten, wie Sie die OASValidation-Richtlinie verwenden können, um Nachrichten anhand einer OpenAPI 3.0-Spezifikation zu prüfen.

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

Element <OASValidation>

Definiert die OASValidation-Richtlinie (OpenAPI Specification Validation).

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

This element has the following attributes that are common to all policies:

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <OASValidation> beschrieben.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

The <DisplayName> element uses the following syntax:

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

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

The <DisplayName> element has no attributes or child elements.

<OASResource>

Gibt die OpenAPI-Spezifikation an, gegen die validiert werden soll. Sie können diese Datei speichern:

• Im API-Proxy-Bereich unter /apiproxy/resources/oas im API-Proxy-Bundle
• Im Abschnitt Resources der Navigatoransicht des API-Proxy-Editors.

Weitere Informationen finden Sie unter Ressourcen verwalten.

Sie können die OpenAPI-Spezifikation mithilfe einer Nachrichtenvorlage angeben, beispielsweise {oas.resource.url}. In diesem Fall wird der Wert der Flussvariablen oas.resource.url (in geschweiften Klammern) ausgewertet und zur Laufzeit durch den Nutzlaststring ersetzt. Weitere Informationen finden Sie unter SMS-Vorlagen.

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

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

Das <OASResource>-Element hat keine Attribute oder untergeordnete Elemente.

<Options>

Konfiguriert Optionen für die Richtlinie.

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

Gibt an, ob der Richtlinientext in der OpenAPI-Spezifikation mit dem Anfragetexttext des Vorgangs abgeglichen werden soll. Setzen Sie diesen Wert auf true, um den Inhalt des Nachrichteninhalts zu validieren. Setzen Sie diesen Wert auf false, um nur zu prüfen, ob der Nachrichtentext vorhanden ist.

Sie können festlegen, ob der Ablauf nach einem Validierungsfehler weiterhin ausgeführt wird. Setzen Sie dazu das Attribut continueOnError für das Element <OASValidation> auf wahr.

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

Konfiguriert das Verhalten der Richtlinie, wenn die Anfrage Header-, Abfrage- oder Cookie-Parameter enthält, die nicht in der OpenAPI-Spezifikation definiert sind.

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

Konfiguriert das Verhalten der Richtlinie, wenn in der Anfrage Headerparameter vorhanden sind, die nicht in der OpenAPI-Spezifikation definiert sind.

Damit Headerparameter in der Anfrage angegeben werden können, die nicht in der OpenAPI-Spezifikation definiert sind, setzen Sie diesen Parameter auf wahr. Setzen Sie andernfalls diesen Parameter auf falsch, damit die Richtlinienausführung fehlschlägt.

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

Konfiguriert das Verhalten der Richtlinie für den Fall, dass die Anfrage Abfrageparameter enthält, die nicht in der OpenAPI-Spezifikation definiert sind.

Damit Abfrageparameter in der Anfrage angegeben werden können, die nicht in der OpenAPI-Spezifikation definiert sind, setzen Sie diesen Parameter auf wahr. Setzen Sie andernfalls diesen Parameter auf falsch, damit die Richtlinienausführung fehlschlägt.

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

Konfiguriert das Verhalten der Richtlinie für den Fall, dass die Anfrage Cookieparameter enthält, die nicht in der OpenAPI-Spezifikation definiert sind.

Damit Cookieparameter in der Anfrage angegeben werden können, die nicht in der OpenAPI-Spezifikation definiert sind, setzen Sie diesen Parameter auf wahr. Setzen Sie andernfalls diesen Parameter auf falsch, damit die Richtlinienausführung fehlschlägt.

<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-Nachricht, die im Hinblick auf Angriffe über JSON-Nutzlasten ausgewertet werden soll. Dies ist meistens auf request gesetzt, da Sie in der Regel eingehende Anfragen von Client-Apps evaluieren müssen. Durch die Einstellung auf response werden Antwortnachrichten bewertet. Durch die Einstellung auf message wird automatisch die Anfragenachricht bewertet, wenn die Richtlinie an den Anfrageablauf angehängt wird. Wenn die Richtlinie an den Antwortablauf angehängt wird, wird bei dieser Einstellung automatisch die Antwortnachricht bewertet.

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

Das <Source>-Element hat keine Attribute oder untergeordnete Elemente.

Schemas

Jeder Richtlinientyp wird durch ein XML-Schema (.xsd) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.

Fehlercodes

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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

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.

Unterstützte OpenAPI-Spezifikationsfeatures

Die OASValidation-Richtlinie unterstützt die OpenAPI-Spezifikationsfeatures, die in der folgenden Tabelle nach Kategorie zusammengefasst sind. Die nicht unterstützten Features sind ebenfalls aufgelistet.

Weitere Informationen

• JSON-Richtlinie zum Schutz vor Bedrohungen
• SOAPMessageValidation-Richtlinie