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, gdy wykonywany jest krok, 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 lub .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?

W tabeli poniżej podsumowano treść wiadomości żądania, która jest weryfikowana przez zasadę OASValidation według komponentu.

W tej tabeli znajdziesz podsumowanie zawartości wiadomości odpowiedzi, która jest weryfikowana 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>

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>

Używaj tego atrybutu w połączeniu z atrybutem name, aby oznaczyć zasadę w edytorze proxy interfejsu zarządzania inną, bardziej naturalnie brzmiącą nazwą.

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

Element <DisplayName> ma tę 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, 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 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 podstawiona 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 oceniać żą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 żądania, 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

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