Criterio OASValidation

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Informazioni sulla policy OASValidation

La policy OASValidation (OpenAPI Specification Validation) consente di convalidare un messaggio di richiesta o risposta in entrata rispetto a una specifica OpenAPI 3.0 (JSON o YAML). Consulta la sezione Quali contenuti vengono convalidati?

La policy OASValidation specifica il nome della specifica OpenAPI da utilizzare per la convalida quando viene eseguito il passaggio a cui è associata la policy. La specifica OpenAPI viene archiviata come risorsa nella seguente posizione standard all'interno del bundle del proxy API: apiproxy/resources/oas. La specifica OpenAPI deve avere un'estensione .json, .yml, .yaml.

Aggiungi una specifica OpenAPI come risorsa a un bundle di proxy API utilizzando la UI o l'API, come descritto in Gestisci le risorse.

Quali contenuti vengono convalidati?

La tabella seguente riassume il contenuto del messaggio di richiesta convalidato dalla policy OASValidation, per componente.

La seguente tabella riassume il contenuto del messaggio di risposta convalidato dalla policy OASValidation, per componente.

Esempi

Gli esempi seguenti mostrano alcuni dei modi in cui puoi utilizzare la policy OASValidation per convalidare i messaggi rispetto a una specifica 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>

Elemento <OASValidation>

Definisce la policy OpenAPI Specification Validation.

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

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Riferimento dell'elemento secondario

Questa sezione descrive gli elementi secondari di <OASValidation>.

<DisplayName>

Utilizzalo in aggiunta all'attributo name per etichettare la policy nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutte le policy.

L'elemento <DisplayName> utilizza la seguente sintassi:

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

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

L'elemento <DisplayName> non ha attributi o elementi secondari.

<OASResource>

Specifica la specifica OpenAPI in base alla quale eseguire la convalida. Puoi archiviare questo file:

• Nell'ambito del proxy API in /apiproxy/resources/oas nel bundle del proxy API
• Nella sezione Resources della visualizzazione Navigator dell'editor del proxy API.

Per saperne di più, consulta Gestisci le risorse.

Puoi specificare la specifica OpenAPI utilizzando un modello di messaggio, ad esempio {oas.resource.url}. In questo caso, il valore della variabile di flusso oas.resource.url (tra parentesi graffe) verrà valutato e sostituito nella stringa del payload in fase di runtime. Per saperne di più, consulta Modelli di messaggi.

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

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

L'elemento <OASResource> non ha attributi o elementi secondari.

<Options>

Configura le opzioni per la policy.

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

Specifica se la policy deve convalidare il corpo del messaggio rispetto allo schema del corpo della richiesta dell'operazione nella specifica OpenAPI. Impostalo su true per convalidare i contenuti del corpo del messaggio. Impostalo su false per convalidare solo l'esistenza del corpo del messaggio.

Puoi controllare se l'esecuzione del flusso continua dopo un errore di convalida impostando l'attributo continueOnError per l'elemento <OASValidation> su 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>

Configura il comportamento della policy se nella richiesta sono presenti parametri di intestazione, query o cookie non definiti nella specifica 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> (figlio di <AllowUnspecifiedParameters>)

Configura il comportamento della policy se nella richiesta sono presenti parametri di intestazione non definiti nella specifica OpenAPI.

Per consentire di specificare nella richiesta parametri di intestazione non definiti nella specifica OpenAPI, imposta questo parametro su true. In caso contrario, imposta questo parametro su false per causare l'errore di esecuzione della policy.

<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> (figlio di <AllowUnspecifiedParameters>)

Configura il comportamento della policy se nella richiesta sono presenti parametri di query non definiti nella specifica OpenAPI.

Per consentire la specifica nella richiesta di parametri di query non definiti nella specifica OpenAPI, imposta questo parametro su true. In caso contrario, imposta questo parametro su false per causare l'errore di esecuzione della policy.

<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> (figlio di <AllowUnspecifiedParameters>)

Configura il comportamento della policy se nella richiesta sono presenti parametri dei cookie non definiti nella specifica OpenAPI.

Per consentire la specifica nella richiesta di parametri dei cookie non definiti nella specifica OpenAPI, imposta questo parametro su true. In caso contrario, imposta questo parametro su false per causare l'errore di esecuzione della policy.

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

Messaggio JSON da valutare rispetto agli attacchi ai payload JSON. In genere, questo valore è impostato su request, poiché di solito devi valutare le richieste in entrata dalle app client. Imposta su response per valutare i messaggi di risposta. Imposta su message per valutare automaticamente il messaggio di richiesta quando la policy è collegata al flusso di richiesta e il messaggio di risposta quando la policy è collegata al flusso di risposta.

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

L'elemento <Source> non ha attributi o elementi secondari.

Schemi

Ogni tipo di policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.

Codici di errore

Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore in fase di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori dei criteri.

Funzionalità supportate delle specifiche OpenAPI

La policy OASValidation supporta le funzionalità della specifica OpenAPI riassunte nella tabella seguente, per categoria. Sono elencate anche le funzionalità non supportate.

Argomenti correlati

• Policy JSON Threat Protection
• Policy SOAPMessageValidation