Zasady OASwalidacji

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

Informacje o zasadzie 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 znajdziesz podsumowanie treści wiadomości z prośbą, które są weryfikowane przez zasadę OASValidation, według komponentu.

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

Przykłady

Przykłady poniżej 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 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 opisujemy elementy podrzędne elementu <OASValidation>.

<DisplayName>

Użyj go 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 wykonywania. 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ą weryfikować treść wiadomości pod kątem schematu treści żądania operacji w specyfikacji OpenAPI. Ustaw wartość 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 elementu <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 elementu <AllowUnspecifiedParameters>)

Konfiguruje działanie 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 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 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 zostać oceniona pod kątem ataków na ładunek JSON. Zwykle jest ona ustawiona na wartość request, ponieważ zazwyczaj musisz ocenić przychodzące żądania z aplikacji klienckich. Aby oceniać wiadomości z odpowiedzią, ustaw wartość response. Ustaw wartość message, aby automatycznie oceniać wiadomość z żądaniem, 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 zasady 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 w formacie JSON
• Zasady SOAPMessageValidation