Zasady OASwalidacji

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Informacje o zasadzie OASValidation

Zasada OASValidation (OpenAPI Specification Validation) umożliwia sprawdzanie przychodzącego żądania lub komunikatu odpowiedzi pod kątem zgodności ze specyfikacją OpenAPI 3.0 (JSON lub YAML). Zobacz Jakie treści są sprawdzane?.

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

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

Jakie treści są sprawdzane?

Tabela poniżej zawiera podsumowanie treści wiadomości żądania, które są sprawdzane przez zasadę OASValidation, według komponentu.

Tabela poniżej zawiera podsumowanie treści komunikatu odpowiedzi, które są weryfikowane przez zasadę OASValidation, według komponentu.

Przykłady

Poniższe przykłady pokazują, jak można używać zasady OASValidation do sprawdzania poprawności wiadomości pod kątem 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 zasadę 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>

Ten element ma te atrybuty, które są wspólne dla wszystkich zasad:

Dokumentacja elementu podrzędnego

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

<DisplayName>

Używaj go razem z atrybutem name, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną, bardziej naturalnie brzmiącą nazwą.

Element <DisplayName> jest wspólny dla wszystkich zasad.

Element <DisplayName> używa tej składni:

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

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

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

<OASResource>

Określa specyfikację OpenAPI, pod kątem której ma zostać przeprowadzona weryfikacja. Możesz przechowywać ten plik:

• W zakresie serwera proxy interfejsu API w sekcji /apiproxy/resources/oas w pakiecie serwera proxy interfejsu API.
• W sekcji Resources w widoku nawigatora edytora serwerów proxy interfejsu API.

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

Specyfikację OpenAPI możesz określić za pomocą szablonu wiadomości, takiego jak {oas.resource.url}. W tym przypadku wartość zmiennej przepływu oas.resource.url (w nawiasach klamrowych) zostanie oceniona i zastąpiona w 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.

<Options>

Konfiguruje opcje zasady.

<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 zasada powinna sprawdzać treść wiadomości pod kątem schematu treści żądania operacji w specyfikacji OpenAPI. Ustaw wartość true, aby sprawdzić zawartość treści wiadomości. Ustaw wartość false, aby sprawdzać tylko, czy treść wiadomości istnieje.

Możesz określić, czy po wystąpieniu błędu weryfikacji wykonywanie przepływu ma być kontynuowane, 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 elementu <AllowUnspecifiedParameters>)

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

Aby zezwolić na 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 elementu <AllowUnspecifiedParameters>)

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

Aby zezwolić na 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 wykonywania 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 elementu <AllowUnspecifiedParameters>)

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

Aby zezwolić na 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 wykonywania 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 zostać oceniona pod kątem ataków na ładunek JSON. Najczęściej ustawia się wartość request, ponieważ zwykle trzeba oceniać żądania przychodzące z aplikacji klienckich. Aby oceniać wiadomości z odpowiedzią, ustaw wartość response. Ustaw wartość message, aby automatycznie oceniać komunikat żądania, gdy zasada jest dołączona do przepływu żądania, i komunikat 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 zasady jest definiowany przez schemat XML (.xsd). Schematy zasad są dostępne na GitHubie.

Kody błędów

W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi takich błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.

Zmienne błędów

Te zmienne są ustawiane, gdy zasada wywołuje błąd w czasie działania. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami.

Obsługiwane funkcje specyfikacji OpenAPI

Zasada OASValidation obsługuje 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

• Zasada ochrony przed zagrożeniami JSON
• Zasada SOAPMessageValidation