Zasady OASwalidacji

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Informacje o zasadach OASValidation

Zasada OASValidation (OpenAPI Specification Validation) umożliwia weryfikację przychodzącego żądania lub wiadomości z odpowiedzią na podstawie specyfikacji OpenAPI 3.0 (JSON lub YAML). Zobacz jakie treści są weryfikowane

Zasada OASValidation określa nazwę specyfikacji OpenAPI, która ma być używana do weryfikacji podczas wykonywania kroku, do którego jest dołączona. Specyfikacja OpenAPI jest przechowywana jako zasób w standardowej lokalizacji w pakiecie proxy interfejsu API: apiproxy/resources/oas. Specyfikacja OpenAPI musi mieć rozszerzenie .json, .yml, .yaml.

Dodaj specyfikację OpenAPI jako zasób do pakietu proxy interfejsu API za pomocą interfejsu lub interfejsu API zgodnie z opisem w artykule Zarządzanie zasobami.

Jakie treści są weryfikowane?

Poniższa tabela zawiera podsumowanie treści wiadomości z żądaniem, które są weryfikowane przez regułę OASValidation według komponentu.

W tej tabeli znajdziesz podsumowanie treści wiadomości odpowiedzi, które są weryfikowane przez komponenty zasad OASValidation.

Przykłady

Poniższe przykłady pokazują, jak za pomocą zasady OASValidation weryfikować wiadomości na podstawie specyfikacji 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>

Element <OASValidation>

Definiuje zasady weryfikacji specyfikacji 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>

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

Odwołanie do elementu podrzędnego

W tej sekcji opisujemy elementy podrzędne elementu <OASValidation>.

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

Określa specyfikację OpenAPI, z którą ma być przeprowadzona weryfikacja. Ten plik możesz przechowywać:

• W zakresie proxy interfejsu API w sekcji /apiproxy/resources/oas w pakiecie proxy interfejsu API
• W sekcji Resources w widoku Nawigator edytora proxy interfejsu API.

Więcej informacji znajdziesz w artykule o zarządzaniu zasobami.

Specyfikację OpenAPI możesz określić za pomocą szablonu wiadomości, np. {oas.resource.url}. W tym przypadku wartość zmiennej przepływu oas.resource.url (w nawiasach klamrowych) zostanie obliczona i wstawiona do ciągu ładunku w czasie działania. Więcej informacji znajdziesz w artykule Szablony wiadomości.

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

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

Element <OASResource> nie ma atrybutów ani elementów podrzędnych.

<Opcje>

Konfiguruje opcje zasad.

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

Określa, czy zasady mają sprawdzać treść wiadomości pod kątem schematu treści żądania operacji w specyfikacji OpenAPI. Ustaw jako true, aby zweryfikować zawartość treści wiadomości. Ustaw wartość false, aby sprawdzić tylko, czy treść wiadomości istnieje.

Możesz określić, czy wykonanie przepływu ma być kontynuowane po wystąpieniu błędu weryfikacji, ustawiając atrybut continueOnError elementu <OASValidation> na wartość 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>

Konfiguruje działanie zasady, jeśli w żądaniu występują parametry nagłówka, zapytania lub pliku cookie, które nie są zdefiniowane w specyfikacji 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> (element podrzędny <AllowUnspecifiedParameters>)

Konfiguruje zachowanie zasady, jeśli w żądaniu występują parametry nagłówka, które nie są zdefiniowane w specyfikacji OpenAPI.

Aby umożliwić określanie w żądaniu parametrów nagłówka, które nie są zdefiniowane w specyfikacji OpenAPI, ustaw ten parametr na true. W przeciwnym razie ustaw ten parametr na false, aby spowodować niepowodzenie wykonania zasady.

<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> (element podrzędny <AllowUnspecifiedParameters>)

Konfiguruje zachowanie zasady, jeśli w żądaniu występują parametry zapytania, które nie są zdefiniowane w specyfikacji OpenAPI.

Aby umożliwić określanie w żądaniu parametrów zapytania, które nie są zdefiniowane w specyfikacji OpenAPI, ustaw ten parametr na true. W przeciwnym razie ustaw ten parametr na false, aby spowodować niepowodzenie wykonania zasady.

<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> (element podrzędny <AllowUnspecifiedParameters>)

Konfiguruje działanie zasady, jeśli w żądaniu występują parametry plików cookie, które nie są zdefiniowane w specyfikacji OpenAPI.

Aby umożliwić określanie w żądaniu parametrów plików cookie, które nie są zdefiniowane w specyfikacji OpenAPI, ustaw ten parametr na true. W przeciwnym razie ustaw ten parametr na false, aby spowodować niepowodzenie wykonania zasady.

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

Wiadomość JSON, która ma być oceniana pod kątem ataków na ładunek JSON. Zwykle jest to ustawione na wartość request, ponieważ zazwyczaj musisz ocenić żądania przychodzące z aplikacji klienckich. Aby oceniać wiadomości z odpowiedzią, ustaw wartość response. Ustaw wartość message, aby automatycznie oceniać wiadomość z prośbą, gdy zasada jest dołączona do przepływu prośby, oraz wiadomość z odpowiedzią, gdy zasada jest dołączona do przepływu odpowiedzi.

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

Element <Source> nie ma atrybutów ani elementów podrzędnych.

Schematy

Każdy typ zasad jest zdefiniowany przez schemat XML (.xsd). Schematy zasad są dostępne na GitHubie.

Kody błędów

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.

Obsługiwane funkcje specyfikacji OpenAPI

Zasady OASValidation obsługują funkcje specyfikacji OpenAPI, które zostały podsumowane w tabeli poniżej według kategorii. Wymienione są też funkcje, które nie są obsługiwane.

Powiązane artykuły

• Zasady ochrony przed zagrożeniami JSON
• Zasady SOAPMessageValidation