OASValidation-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

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. Das OpenAPI-Spezifikationsdokument muss die Erweiterung .json, .yml oder .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.

Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.

Welche Inhalte werden validiert?

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

Komponenten	Anfragevalidierung
Basispfad	Validiert den vom API-Proxy definierten Basispfad und ignoriert den in der OpenAPI-Spezifikation angegebenen Basispfad.
Pfad	Validiert, dass der Anfragepfad (ohne den Basispfad) mit einem der in der OpenAPI-Spezifikation definierten Pfadmuster übereinstimmt.
Verb	Validiert, dass das Verb für den Pfad in der OpenAPI-Spezifikation definiert ist.
Nachrichtentext der Anfrage	Validiert, dass der Nachrichtentext in der Anfrage vorhanden ist, falls erforderlich. Er validiert den Nachrichtentext anhand des Anfragetextschemas des Vorgangs in der OpenAPI-Spezifikation. Konfigurieren Sie diese Option mit `<ValidateMessageBody>`. Hinweis: Die Richtlinie validiert den Nachrichtentext der Anfrage anhand der OpenAPI-Spezifikation nur dann, wenn der Inhaltstyp auf `application/json` eingestellt ist. Wenn der Inhaltstyp nicht auf `application/json` gesetzt ist, ist die Validierung des Nachrichtentexts der Anfrage automatisch erfolgreich, ohne dass der Inhalt tatsächlich validiert wurde.
Parameter	Validiert, dass die erforderlichen Parameter in der Anfrage vorhanden sind, einschließlich der Pfad-, Header-, Abfrage- und Cookie-Parameter. Validiert, dass die Parameterwerte mit den in der OpenAPI-Spezifikation definierten übereinstimmen. Überprüft optional, ob in der Anfrage Parameter vorhanden sind, die nicht in der OpenAPI-Spezifikation definiert sind. Konfigurieren Sie diese Option mit `<AllowUnspecifiedParameters>`.

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

Komponenten	Antwortenvalidierung
Pfad	Validiert, dass der Anfragepfad (ohne den Basispfad) mit einem der in der OpenAPI-Spezifikation definierten Pfadmuster übereinstimmt.
Verb	Validiert, dass das Verb für den Pfad in der OpenAPI-Spezifikation definiert ist.
Nachrichtentext der Antwort	Validiert, dass der Nachrichtentext in der Antwort vorhanden ist, falls erforderlich. Validiert, dass die Antwortheader in der OpenAPI-Spezifikation in der Antwortnachricht enthalten sind und der Wert der Antwortheader mit dem Schema übereinstimmt. Überprüft optional den Nachrichtentext anhand des Antworttextschemas des Vorgangs in der OpenAPI-Spezifikation. Konfigurieren Sie diese Option mit `<ValidateMessageBody>`.

Hinweis:Die OASValidation-Richtlinie von Apigee validiert Anfrage- und Antwortpfade unterschiedlich.
Bei der Anfragevalidierung wird der Anfragepfad des API-Proxy validiert (z. B. /hello für https://<BasePath>/hello).
Bei der Antwortvalidierung wird der Pfad des Zielendpunkts validiert, der von Apigee aufgerufen wird (z. B. /apigee/hello für https://{target-basepath}}/apigee/hello).
Diese Unterscheidung ist wichtig, wenn sich Proxy- und Zielpfade unterscheiden, da Sie Ihre OpenAPI-Spezifikation für die Antwortvalidierung entsprechend anpassen müssen.

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.

Anfragenachricht validieren

Im folgenden Beispiel prüft die myoaspolicy-Richtlinie den Text der Anfragenachricht anhand des Nachrichtentextschemas der Anfrage des Vorgangs, das in der my-spec.json-OpenAPI-Spezifikation definiert ist.

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

Stimmt der Nachrichtentext nicht mit der OpenAPI-Spezifikation überein, so wird ein policies.oasvalidation.Failed-Fehler zurückgegeben.

Parameter validieren

Im folgenden Beispiel wird die Richtlinie so konfiguriert, dass sie fehlschlägt, falls ein Header, eine Abfrage oder ein Cookie-Parameter in der Anfrage angegeben wird, der in der OpenAPI-Spezifikation nicht definiert ist.

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

Standardwert	Siehe unten, Tab Standardrichtlinie
Erforderlich?	Erforderlich
Typ	Komplexes Objekt
Übergeordnetes Element	–
Untergeordnete Elemente	`<DisplayName>` `<OASResource>` `<Source>` `<Options>` `<Source>`

Syntax

Das <OASValidation>-Element verwendet die folgende Syntax:

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

Standardrichtlinie

Das folgende Beispiel zeigt die Standardeinstellungen, wenn Sie in der Apigee-UI Ihrem Ablauf eine OASValidation-Richtlinie hinzufügen:

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

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Attribut	Standard	Erforderlich?	Beschreibung
`name`	-	Erforderlich	Der interne Name der Richtlinie. Der Wert des Attributs `name` kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten. Optional können Sie das Element `<DisplayName>` verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.
`continueOnError`	false	Optional	Legen Sie `false` fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie `true` fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf
`enabled`	wahr	Optional	Setzen Sie den Wert auf `true`, um die Richtlinie zu erzwingen. Legen Sie `false` fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist.
`async`	false	Verworfen	Dieses Attribut wurde verworfen.

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.

Default Value	N/A
Required?	Optional. If you omit `<DisplayName>`, the value of the policy's `name` attribute is used.
Type	String
Parent Element	<`PolicyElement`>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

Standardwert	–
Erforderlich?	Erforderlich
Typ	String
Übergeordnetes Element	`<OASValidation>`
Untergeordnete Elemente	Keine

Syntax

Das <OASResource>-Element verwendet die folgende Syntax:

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

Beispiel

Folgendes Beispiel verweist auf die Spezifikation my-spec.yaml, die unter /apiproxy/resources/oas im API-Proxy-Bundle gespeichert ist:

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

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

Hinweis: Wenn die OASValidation-Richtlinie eine <OASResource> mit Sicherheitsanforderungen auf globaler Ebene angibt, werden die Sicherheitsanforderungen nicht erzwungen. Damit die Durchsetzung gewährleistet ist, müssen alle Sicherheitsanforderungen in der OpenAPI-Spezifikation, die im <OASResource>-Element dieser Richtlinie übergeben wird, auf operation-Ebene festgelegt werden. Weitere Informationen finden Sie unter Bekannte Probleme mit Apigee.

<Options>

Konfiguriert Optionen für die Richtlinie.

Standardwert	–
Erforderlich?	Optional
Typ	Komplexer Typ
Übergeordnetes Element	`<OASValidation>`
Untergeordnete Elemente	`<ValidateMessageBody>` `<AllowUnspecifiedParameters>`

Syntax

Das <Options>-Element verwendet die folgende Syntax:

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

Beispiel

Im folgenden Beispiel werden die Optionen für die Richtlinie konfiguriert. Jede dieser Optionen wird im Folgenden näher beschrieben.

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

Hinweis: Die Richtlinie validiert den Nachrichtentext der Anfrage anhand der OpenAPI-Spezifikation nur dann, wenn der Inhaltstyp auf application/json eingestellt ist. Wenn der Inhaltstyp nicht auf application/json gesetzt ist, ist die Validierung des Nachrichtentexts der Anfrage automatisch erfolgreich, ohne dass der Inhalt tatsächlich validiert wurde.

Standardwert	falsch
Erforderlich?	Optional
Typ	Boolescher Wert
Übergeordnetes Element	`<Options>`
Untergeordnete Elemente	Keine

Syntax

Das <ValidateMessageBody>-Element verwendet die folgende Syntax:

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

Beispiel

Im folgenden Beispiel wird die Validierung des Nachrichtentexts aktiviert:

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

Standardwert	–
Erforderlich?	Optional
Typ	Komplexer Typ
Übergeordnetes Element	`<Options>`
Untergeordnete Elemente	`<Header>` `<Query>` `<Cookie>`

Syntax

Das <AllowUnspecifiedParameters>-Element verwendet die folgende Syntax:

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

Beispiel

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

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.

Standardwert	wahr
Erforderlich?	Boolesch
Typ	Komplexer Typ
Übergeordnetes Element	`<AllowUnspecifiedParameters>`
Untergeordnete Elemente	Keine

Syntax

Das <Header>-Element verwendet die folgende Syntax:

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

Beispiel

Im folgenden Beispiel wird die Richtlinie so konfiguriert, dass ein Headerparameter in der Anfrage angegeben wird, der nicht in der OpenAPI-Spezifikation definiert ist.

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

Standardwert	wahr
Erforderlich?	Boolesch
Typ	Komplexer Typ
Übergeordnetes Element	`<AllowUnspecifiedParameters>`
Untergeordnete Elemente	Keine

Syntax

Das <Query>-Element verwendet die folgende Syntax:

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

Beispiel

Im folgenden Beispiel wird die Richtlinie so konfiguriert, dass ein Abfrageparameter in der Anfrage angegeben wird, der nicht in der OpenAPI-Spezifikation definiert ist.

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

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.

Standardwert	wahr
Erforderlich?	Boolesch
Typ	Komplexer Typ
Übergeordnetes Element	`<AllowUnspecifiedParameters>`
Untergeordnete Elemente	Keine

Syntax

Das <Cookie>-Element verwendet die folgende Syntax:

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

Beispiel

Im folgenden Beispiel wird die Richtlinie so konfiguriert, dass ein Abfrageparameter in der Anfrage angegeben wird, der nicht in der OpenAPI-Spezifikation definiert ist.

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

Standardwert	Anfrage
Erforderlich?	Optional
Typ	String
Übergeordnetes Element	`<Source>`
Untergeordnete Elemente	Keine

Syntax

Das <Source>-Element verwendet die folgende Syntax:

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

Beispiel

Im folgenden Beispiel wird die Anfragenachricht automatisch ausgewertet, wenn die Richtlinie an den Anfrageablauf angehängt wird, und wenn die Richtlinie an den Antwortablauf angehängt wird, wird die Antwortnachricht ausgewertet:

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

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

Schema für diese Richtlinie

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

Fault code	HTTP status	Cause
`steps.oasvalidation.Failed`	`400`	The Request message body cannot be validated against the provided OpenAPI Specification.
`steps.oasvalidation.Failed`	`500`	The Response message body cannot be validated against the provided OpenAPI Specification.
`steps.oasvalidation.SourceMessageNotAvailable`	`500`	Variable specified in the `<Source>` element of the policy is either out of scope or cannot be resolved.
`steps.oasvalidation.NonMessageVariable`	`500`	`<Source>` element is set to a variable that is not of type message.

Deployment errors

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

Error name	Cause
`ResourceDoesNotExist`	OpenAPI Specification referenced in the `<OASResource>` element does not exist.
`ResourceCompileFailed`	OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
`BadResourceURL`	OpenAPI Specification referenced in the `<OASResource>` element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

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.

Variable	Description	Example
`fault.category`	The category of the fault. When the policy rejects a request, this will always hold `Step`.	`fault.category = "Step"`
`fault.name`	The name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "ResourceDoesNotExist"`
`fault.reason`	The reason for the fault. It is a human-readable string explaining the reason for the fault.	`OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"`
`fault.subcategory`	The subcategory of the fault. When the policy rejects a request, this will always hold `OASValidationFailure`.	`fault.subcategory = "OASValidationFailure"`
`OASValidation.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`OASValidation.myoaspolicy.failed = true`

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.

Kategorie	Unterstützt	Nicht unterstützt
Datentypformate	boolean date date-time double email float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid	binary byte password
Diskriminator-Objekt	mapping propertyName	–
Medientypobjekt	schema	encoding example examples
Vorgangsobjekt	parameters requestBody responses security (partial support)	callbacks deprecated servers
Parameterobjekt	allowEmptyValue in (`query`, `header`, `path`) required responses schema style (`deepObject`, `form`, `formmatrix`, `label`, `pipeDelimited`, `simple`, `spaceDelimited`) Hinweis: `deepObject` unterstützt nur Stringparameter. Arrays und verschachtelte Objekte werden nicht unterstützt.	allowReserved deprecated example examples content
Pfadobjekt	delete get head options parameters patch post put trace variables	Server
Anfragetextobjekt	application/json application/hal+json application/x-www-form-urlencoded (`encoding`-Objekt wird nicht unterstützt) content required	application/xml multipart/form-data text/plain text/xml
Antwortobjekt	application/json application/hal+json application/x-www-form-urlencoded (`encoding`-Objekt wird nicht unterstützt) content headers	application/xml links text/plain text/xml
Antwortenobjekt	default HTTP-Statuscode	–
Schema-Objekt	$ref additionalProperties (nur boolesche Flagvariante) allOf (wird ignoriert, wenn `additionalProperties` `false` ist) 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
Sicherheitsschema-Objekt	in (`header`, `query`) (wird ignored, wenn `type` `http` ist) name type (`apiKey`, `http`)	bearerFormat flows openIdConnectUrl scheme
Serverobjekt	url variables	Mehrere Serverdefinitionen

Muster im Schema verwenden

Der OpenAPI-Spezifikationsstandard erlaubt es, in Spezifikationen ein schema anzugeben, um den Datentyp eines Parameters oder Felds zu beschreiben. Für einen Parameter oder ein Feld vom Typ „String" kann das Schema auch eine pattern definieren. Dabei handelt es sich um einen regulären Ausdruck (Regex), der gültige Formen für den String definiert.

Betrachten Sie beispielsweise das folgende Fragment der OpenAPI-Spezifikation:

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}$'

Diese Spezifikation erfordert, dass für den getProduct-Vorgang der Parameter product-id dem angegebenen regulären Ausdruck entsprechen muss, der eine Sequenz aus 3 Wortzeichen, einen Bindestrich und 4 Dezimalstellen festlegt.

Die OpenAPI-Spezifikation verweist auf den JSON-Schemavalidierungsstandard, um das Verhalten des Musters bei der Validierung des Stringwerts formal zu definieren, und auf den JSON Schema Core-Standard, um Empfehlungen für Schemaautoren bezüglich der eingeschränkten Syntax regulärer Ausdrücke zu geben. Dieser letztere Standard empfiehlt, in Mustern in OpenAPI-Spezifikationsdokumenten u. a. die Verwendung von Lookarounds (Lookaheads und Lookbehinds), Rückverweisen und oktalen Zeichenausdrücken zu vermeiden.

Standardmäßig validiert Apigee das OpenAPI-Spezifikationsdokument, auf das in der OASValidation-Richtlinie verwiesen wird, und meldet Fehler, wenn das Spezifikationsdokument nicht wohlgeformt ist. Apigee validiert auch Regex-Muster in Ihrem Spezifikationsdokument und meldet gefundene Probleme.

Wenn Sie reguläre Ausdrücke verwenden, die nicht zum empfohlenen Subset gehören, validiert Apigee die regulären Ausdrücke nicht und setzt die zusätzliche Validierung Ihres OpenAPI-Spezifikationsdokuments aus. Wenn im Dokument oder im regulären Ausdruck, der eine Funktion außerhalb der empfohlenen Teilmenge verwendet, ein Fehler vorliegt oder die Regex-Funktion von der Apigee-Laufzeit nicht unterstützt wird, wird der Fehler erst zur Laufzeit erkannt, wenn die Richtlinie ausgeführt wird.

In der folgenden Tabelle finden Sie einige Beispiele.

Muster	Verhalten
`^\w{3}-\d{4}$`	Das Muster ist gültig. Es werden nur reguläre Ausdrücke aus der empfohlenen Teilmenge verwendet. Apigee erlaubt das Speichern oder Importieren des Proxys. Zur Laufzeit funktioniert die OASValidation-Richtlinie wie vorgesehen und validiert den Parameter anhand des Musters.
`^([a-z]\w{3}-\d{4}$`	Das Muster ist ungültig, da eine schließende Klammer fehlt. Das Muster verwendet keine Regex-Funktionen außerhalb der empfohlenen Teilmenge. Apigee meldet diesen Fehler, wenn Sie Ihren API-Proxy importieren oder speichern.
`^(?![a-z]\w{3}-\d{4}$`	Das Muster ist ungültig. Wie im vorherigen Beispiel fehlt auch hier eine schließende Klammer. Apigee meldet diesen Fehler jedoch nicht, wenn Sie Ihren API-Proxy speichern oder importieren, da im regulären Ausdruck ein negativer Lookahead verwendet wird, der nicht zum empfohlenen Subset von regulären Ausdrücken gehört. Der Fehler wird erst zur Laufzeit erkannt, wenn die Richtlinie ausgeführt wird.
`^(?![a-z])\w{3}-\d{4}$`	Das Muster ist gültig, verwendet aber einen negativen Lookahead, der nicht zur empfohlenen Teilmenge von regulären Ausdrücken gehört. Apigee setzt die Validierung des OpenAPI-Spezifikationsdokuments aus. Wenn Sie zur Laufzeit die OASValidation-Richtlinie ausführen, die mit diesem Muster auf eine Spezifikation verweist, wird dieser reguläre Ausdruck von Apigee korrekt angewendet, um den Parameterwert zu validieren, da die Apigee-Laufzeit negative Lookaheads unterstützt.
`^(a)?b(?(1)c\|d)$`	Das Muster ist gültig, verwendet aber eine bedingte Erfassungsgruppe, die nicht zur empfohlenen Teilmenge der regulären Ausdrücke gehört. Apigee setzt die Validierung des OpenAPI-Spezifikationsdokuments aus. Wenn Sie zur Laufzeit die OASValidation-Richtlinie ausführen, die mit diesem Muster auf eine Spezifikation verweist, gibt Apigee einen Fehler zurück, da die Apigee-Laufzeit dieses Regex-Feature nicht unterstützt.

Wir empfehlen, in Ihrem regulären Ausdruck nur die empfohlene Teilmenge von Funktionen zu verwenden, um Laufzeitfehler zu vermeiden.

OASValidation-Richtlinie Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Welche Inhalte werden validiert?

Beispiele

Anfragenachricht validieren

Parameter validieren

Element <OASValidation>

Syntax

Standardrichtlinie

Verweis auf untergeordnetes Element

<DisplayName>

Syntax

Example

<OASResource>

Syntax

Beispiel

<Options>

Syntax

Beispiel

<ValidateMessageBody>

Syntax

Beispiel

<AllowUnspecifiedParameters>

Syntax

Beispiel

Syntax

Beispiel

Syntax

Beispiel

Syntax

Beispiel

<Source>

Syntax

Beispiel

Schema für diese Richtlinie

Fehlercodes

Runtime errors

Deployment errors

Fault variables

Unterstützte OpenAPI-Spezifikationsfeatures

Muster im Schema verwenden

Weitere Informationen

OASValidation-Richtlinie

Element `<OASValidation>`

`<DisplayName>`

`<OASResource>`

`<AllowUnspecifiedParameters>`

`<Source>`