Zasady OASwalidacji

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

Zasady dotyczące OASValidation

Zasada OASValidation (weryfikacja specyfikacji OpenAPI) umożliwia sprawdzanie przychodzących żądań lub odpowiedzi pod kątem zgodności ze specyfikacją OpenAPI 3.0 (w formacie JSON lub YAML). Zobacz Jakie treści są weryfikowane?

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

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

Jakie treści są weryfikowane?

W tabeli poniżej podano treści żądania weryfikowane przez zasady OASValidation według komponentu.

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

Przykłady

Poniższe przykłady pokazują, jak można używać reguły OASValidation do sprawdzania wiadomości pod kątem zgodności ze specyfikacją 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:

Odwołanie do elementu podrzędnego

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

<DisplayName>

Oprócz atrybutu name możesz użyć innej, bardziej naturalnie brzmiącej nazwy, aby oznaczyć zasadę w edytorze proxy w interfejsie zarządzania.

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, według której ma być przeprowadzana weryfikacja. Plik możesz przechowywać:

• W zakresie proxy interfejsu API w sekcji /apiproxy/resources/oas w pakiecie proxy interfejsu API
• W sekcji Resources w widoku Navigatora w edytorze przekierowania interfejsu API.

Więcej informacji znajdziesz w artykule Zarządzanie 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 zastąpiona w ciągu danych 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 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 zasady mają sprawdzać poprawność treści wiadomości na podstawie schematu treści żądania operacji w specyfikacji OpenAPI. Ustaw jako true, aby zweryfikować zawartość treści wiadomości. Ustaw na false, aby sprawdzić tylko istnienie treści wiadomości.

Aby określić, czy wykonanie przepływu ma być kontynuowane po wystąpieniu błędu weryfikacji, ustaw atrybut continueOnError elementu <OASValidation> na 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 plików 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> (dziecko elementu <AllowUnspecifiedParameters>)

Konfiguruje działanie zasady, jeśli w zapytaniu są parametry nagłówka, które nie są zdefiniowane w specyfikacji OpenAPI.

Aby umożliwić określenie 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 fałsz, 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> (dziecko elementu <AllowUnspecifiedParameters>)

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

Aby umożliwić określenie 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 fałsz, 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> (dziecko elementu <AllowUnspecifiedParameters>)

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

Aby umożliwić określenie 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 fałsz, 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 do oceny w kontekście ataków na ładunek JSON; Zwykle jest to ustawione na request, ponieważ zwykle trzeba ocenić przychodzące żądania z aplikacji klienckich. Aby oceniać wiadomości z odpowiedziami, ustaw wartość na response. Ustaw na message, aby automatycznie oceniać wiadomość z prośbą, gdy zasada jest dołączona do procesu żądania, oraz wiadomość z odpowiedzią, gdy zasada jest dołączona do procesu 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 definiowany przez schemat XML (.xsd). Informacje na temat schematów zasad znajdziesz 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

Zasady OASValidation obsługują funkcje specyfikacji OpenAPI, które są podsumowane w tabeli poniżej według kategorii. Wyświetlają się też funkcje, które nie są obsługiwane.

Powiązane artykuły

• Zasady ochrony przed zagrożeniami w formacie JSON
• Zasady dotyczące SOAPMessageValidation